Duo Agentic Identity for agentgateway

Duo Agentic Identity for agentgateway is a Beta feature.

Overview

AI agents connected to tools via the Model Context Protocol (MCP) are part of enterprise workflows, executing complex tasks autonomously on behalf of users. This creates a critical security gap: how do you control what an AI agent can do and on whose behalf?

agentgateway provides a managed gateway layer for MCP servers, and Duo serves as the identity and authorization engine. The Duo Authorization Connector intercepts every inbound request to agentgateway. On each tool invocation, it extracts the Duo-issued access token from the authenticated request and evaluates the request against centrally managed authorization policies. Based on the allow-or-deny decision, the connector enforces fine-grained authorization before any MCP tool call reaches the back-end server.

Key capabilities:

• MCP server onboarding and tool discovery.
• User authentication via Duo OAuth 2.1/OIDC with Dynamic Client Registration (DCR) or Client ID Metadata Documents (CIMD).
• User identity extraction and Duo group membership lookup.
• Fine-grained tool-level authorization policies mapped to Duo user groups.
• Audit trail of all agent-to-tool invocations.

Duo Agentic Identity for agentgateway requires a Duo Premier plan subscription.

Prerequisites

Before you begin, make sure you have the following:

• A Duo Premier plan subscription or an active Duo Premier trial.
• Access to the Duo Admin Panel as an administrator with the Owner or Administrator administrative role or equivalent custom role.
• A DMZ Linux VM or server where you will install Docker.
• At least one MCP server deployed and accessible from the agentgateway host.
• An Internet-resolvable fully qualified domain name (FQDN) for the agentgateway endpoint.
• A valid SSL certificate for the FQDN from a public certificate authority. Self-signed certificates or certificates from an internal CA will cause connection failures to the MCP gateway from Duo.
• (Optional) Users and groups provisioned or synced to the Duo Directory. You may also manually create users and groups to target with your MCP tool access policies.

Create the MCP Application in Duo

This application handles inbound user authentication to agentgateway using Duo Single Sign-On with Dynamic Client Registration (DCR) or Client ID Metadata Documents (CIMD).

1. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.

2. Locate the entry for Model Context Protocol (MCP) - Single Sign-On with the "SSO" label in the catalog. Click the + Add button to start configuring Model Context Protocol (MCP) - Single Sign-On. See Protecting Applications for more information about protecting applications with Duo and additional application options. You'll need the information on the Model Context Protocol (MCP) - Single Sign-On page later to complete your setup.

3. No active Duo users can log in to new applications until you grant access. Update the User access setting to grant access to this application to users in selected Duo groups, or to all users. Learn more about user access to applications. If you do not change this setting now, be sure to update it so that your test user has access before you test your setup.

   This setting only applies to users who exist in Duo with "Active" status. This does not affect application access for existing users with "Bypass" status, existing users for whom the effective Authentication Policy for the application specifies "Bypass 2FA" or "Skip MFA", or users who do not exist in Duo when the effective New User Policy for the application allows access to users unknown to Duo without MFA.

4. On the General tab, configure the following settings:

   Setting	Value
   Grant Type	Select Authorization Code for user AI agents. Select Client Credentials for Duo to pull the tools list.
   Access Token Lifetime	(Optional) Adjust the access token lifetime as needed. Minimum: 5 minutes.
   Sign-In Redirect URLs	https://sso.duosecurity.com/oidc/default/callback
   Resource URL	Your agentgateway public URL, which typically ends with /mcp.

   

5. On the Scopes tab, optionally update the attribute mapping of the default scopes, add custom scopes, or configure claim transformations if needed.

6. On the Clients tab, make these changes in the "Public Client Registration" section:

   1. Under "Public Client Registration", click in the Scopes field to add the openid, profile, and email scopes.
   2. Enable one or both of the following registration options: Enable clients to self-register using CIMD and Enable clients to register themselves during the authentication flow.

   Verify that your clients support CIMD registration before enabling that option.

   

7. Scroll down to the "Confidential Client Registration" section to add the clients that will use this MCP through agentgateway. For each client, enter a meaningful Client Name, an optional description, and then add the required scopes. This example adds Claude Code as a client.

   

8. Adjust additional settings for your new MCP application at this time — like changing the application's name from the default value or assigning policies or administrative units.

9. Click Save.

Add Ownership and Risk Information

Go to the "Ownership and Risk" section of the application's page in the Duo Admin Panel to assign application owners and classify the application's risk level. Cisco Identity Intelligence automatically imports this information to populate relevant fields.

You may set any of the following:

• Technical Owner: Search for and assign Duo users responsible for technical configuration and maintenance of this application.
• Business Owner: Search for and assign Duo users responsible for business decisions and access approvals related to this application.
• Application Sensitivity: Select this application's risk level from the drop-down list. Default: Not Set.
• Compliance Requirements: Select any applicable regulatory frameworks for this application (SOX (Sarbanes-Oxley), HIPAA, PCI-DSS, etc.) from the list.

Scroll to the bottom of the page and click Save to apply your changes.

Create the agentgateway Application in Duo

This application provides the API credentials that the Duo Authorization Connector uses for tool-level authorization decisions.

1. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.

2. Locate the entry for agentgateway in the catalog. Click the + Add button to create the application, and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications with Duo and additional application options.

3. In the "Connect Duo Authorization to Gateway Authentication" section, use the Copy from existing integration drop-down to select the MCP integration you created earlier. The OAuth details auto-populate. In the example, selecting the MCP application that had Claude Code added as a client shows that information in the details.

4. Populate the agentgateway URLs information with your agentgateway public URL in the URL field and provide a friendly name as the Gateway name.

   

5. Adjust additional settings for your new agentgateway application at this time — like changing the application's name from the default value or assigning an administrative unit.

6. Click Save.

Add Ownership and Risk Information

Go to the "Ownership and Risk" section of the application's page in the Duo Admin Panel to assign application owners and classify the application's risk level. Cisco Identity Intelligence automatically imports this information to populate relevant fields.

You may set any of the following:

• Technical Owner: Search for and assign Duo users responsible for technical configuration and maintenance of this application.
• Business Owner: Search for and assign Duo users responsible for business decisions and access approvals related to this application.
• Application Sensitivity: Select this application's risk level from the drop-down list. Default: Not Set.
• Compliance Requirements: Select any applicable regulatory frameworks for this application (SOX (Sarbanes-Oxley), HIPAA, PCI-DSS, etc.) from the list.

Scroll to the bottom of the page and click Save to apply your changes.

Deploy the Duo Authorization Connector

The Duo Authorization Connector is a Docker container that enforces Duo authorization policies on every MCP tool invocation. The quickstart deployment uses Docker Compose to create the environment.

Install Docker

Docker is a tool that allows Duo Authorization Connector to run inside its own self-contained environment, called a “container”, on top of your host operating system.

Click one of the tabs below to view Docker installation instructions for your Linux platform.

Download the Quickstart YAML

Download the Docker Compose quickstart YAML file by typing:

curl -JO https://dl.duosecurity.com/duo-authorization-connector-beta-latest-quickstart.yaml

You should see output similar to:

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  3814  100  3814    0     0  15256      0 --:--:-- --:--:-- --:--:-- 15296
curl: Saved to filename 'duo-authorization-connector-beta-v1.0.0-quickstart.yaml'

Make note of the actual file name that was saved; you'll need this in future steps. View checksums for Duo Authorization Connector downloads on the Checksums and Downloads page.

Note: If you do not have curl installed but have wget, use this command:

wget --content-disposition https://dl.duosecurity.com/duo-authorization-connector-beta-latest-quickstart.yaml

Download the Configuration File

Download the example configuration file by typing:

curl -JO https://dl.duosecurity.com/duo-authorization-connector-quickstart.example.conf

You should see output similar to:

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  4009  100  4009    0     0  15810      0 --:--:-- --:--:-- --:--:-- 15845

The downloaded file is quickstart.example.conf. View checksums for Duo Authorization Connector downloads on the Checksums and Downloads page.

Configure the Duo Authorization Connector

Copy the example configuration file to a new file and then create the secrets directory:

cp quickstart.example.conf quickstart.conf
mkdir secrets

Open quickstart.conf in a text editor and update the following sections:

Gateway Section

gateway:
  url: "http://localhost:3000/mcp"
  external_url: "https://api.example.com/mcp"

Gateway TLS Section (Optional)

If agentgateway uses TLS internally instead of a TLS-terminating load balancer, copy your certificate file and key to the virtual machine, uncomment the tls options, and configure the TLS settings with the paths to your certificate files:

tls:
    # cert_file: "./certs/gateway.crt"
    # key_file: "./secrets/gateway_key"

Upstreams Section

Add your upstream MCP server information to the upstreams section:

upstreams:
  - name: everything
    url: "http://everything-mcp:8080/mcp"

  - name: github
    url: "http://github-mcp:8080/mcp"

  - name: slack
    url: "http://slack-mcp:3000/mcp"

OAuth Section

The oauth section requires these values from the agentgateway application's details page in the Duo Admin Panel:

oauth:
  issuer: "https://sso-abcd1234.sso.duosecurity.com/oauth2/DIABCDEFGHI12345678"
  admin_panel_client_id: "97af4356e64e4653ac55784145afda76"

Duo Section

The duo section requires these values from the agentgateway application's details page in the Duo Admin Panel:

duo:
  host: "api-XXXXXXXX.duosecurity.com"
  integration_key: "DIXXXXXXXXXXXXXXXXXX"
  secret_key_file: "./secrets/duo_skey"

Create the Duo secret key file:

echo "YOUR_DUO_SECRET_KEY" > ./secrets/duo_skey
chmod 600 ./secrets/duo_skey

Replace YOUR_DUO_SECRET_KEY with the Secret key value from your Duo agentgateway application.

Create the Gateway .env File

Create a .env text file with the MCP gateway information:

# =============================================================================
  # Gateway Profile
  # =============================================================================
  # Choose which gateway to run: agentgateway (default) or envoy
  # Override at runtime: COMPOSE_PROFILES=envoy docker compose up
  COMPOSE_PROFILES=agentgateway
  
  # =============================================================================
  # Gateway Port
  # =============================================================================
  # Port published on the host for the client-facing MCP endpoint (default: 3000).
  # Set to 443 when using the TLS overlay (docker-compose.tls.yaml).
  # GATEWAY_PORT=443

Your directory should now contain:

duo-authorization-connector-beta-v1.0.0-quickstart.yaml
quickstart.conf
.env
secrets/
  duo_skey

TLS Configuration (Optional)

If you want to enable TLS for the agentgateway endpoint, download the TLS configuration overlay by typing:

curl -JO https://dl.duosecurity.com/duo-authorization-connector.tls.yaml

View checksums for Duo Authorization Connector downloads on the Checksums and Downloads page.

Place your TLS certificate and private key files in the working directory, then add the TLS overlay to your docker compose command in the next step.

Run the Duo Authorization Connector

Start the connector and agentgateway:

docker compose -f duo-authorization-connector-beta-v1.0.0-quickstart.yaml up -d

If using TLS, add the TLS overlay file:

docker compose -f duo-authorization-connector-beta-v1.0.0-quickstart.yaml \
  -f duo-authorization-connector.tls.yaml up -d

Expected output:

[+] Running 3/3
 ✔ Network duo-authz-connector_default        Created
 ✔ Container authz-connector                  Started
 ✔ Container agentgateway                     Started

Verify the containers are running:

docker ps

Expected output:

CONTAINER ID   IMAGE                                        COMMAND                  CREATED          STATUS          PORTS                    NAMES
a1b2c3d4e5f6   duosecurity/authorization-connector:v1.0.0   "/app/authz-connector"   10 seconds ago   Up 8 seconds    0.0.0.0:9090->9090/tcp   authz-connector
b2c3d4e5f6a7   agentgateway/agentgateway:latest             "/app/agentgateway"      10 seconds ago   Up 8 seconds    0.0.0.0:8080->8080/tcp   agentgateway

Configure Authorization Policy

Define which Duo user groups can invoke which MCP tools through agentgateway. The MCP gateway allows no tool use without configured rules or policy.

Create User Groups

You may use Duo user groups managed via directory sync or inbound SCIM in your authorization policy. Assign users to the target groups in the external directory and sync the changes into Duo.

If you need to create authorization groups manually:

1. Log in to the Duo Admin Panel and navigate to Users → Groups.

2. Create groups that correspond to the tool-level access you want to enforce. For example:

   Group	Description
   Engineering	Access to code generation and repository tools
   Finance	Access to financial reporting and analytics tools
   Admin	Access to all available tools

3. Assign users to the appropriate groups.

For more information about creating and managing Duo groups, refer to Using Groups.

Set Up Tool-Level Authorization

1. In the Duo Admin Panel, navigate to Applications → MCP Gateways and Servers.

2. On the "MCP Gateways and Servers" page, locate the agentgateway server you created, and click Configure policy.

3. Enter the policy details describing the intent of the new policy.

4. In the "Configure Policy" section, click + Add another rule.

   1. Use the For user groups drop-down to select one or more Duo groups. Users in any of the selected groups receive the specified access.

   2. Click Select tools in the "Allow tools" box to choose which tools members of the selected groups can invoke. Make your selections from the available tools list on the right to add them to the rule. Click Close on the "All Tools" list when you complete your tool selections.

   3. Verify your group and tool selections in the new rule.

5. Click + Add another rule to create additional rules as needed for other group and tool combinations, or Remove rule to delete a rule from the policy.

6. Click Save policy after creating your tool rules.

Test Your Setup

After completing the deployment and configuration steps, you will have:

• The Duo Authorization Connector connected to Duo’s Authorization API.
• An MCP server configured with agentgateway.
• A Duo Authorization policy configured for the MCP Server.

Verify the authorization flow with an MCP client.

Configure an MCP Client

This example uses the Claude Code CLI as the MCP client. You can substitute any MCP-compatible client.

1. Add agentgateway as an MCP server:

   claude mcp add agentgateway -t http https://mcpgw.example.com/mcp

   Replace mcpgw.example.com with your actual agentgateway FQDN.

2. Launch Claude Code:

   claude

3. Type /mcp to view the list of configured MCP servers.

4. Select the agentgateway entry and press Enter to confirm.

5. Select Authenticate and press Enter to authenticate via Duo Single Sign-On.

6. Claude Code launches your default web browser with the Duo SSO authentication URL. If your browser doesn't launch automatically, copy the URL provided in the text output and paste it into a new browser tab.

7. Log in to Duo SSO and complete additional authentication when prompted.

   

Verify Tool-Level Authorization

1. After authentication, use /mcp to view available MCP tools. Confirm the list matches your group permissions.

2. Invoke a tool that your group has access to. The request succeeds and returns results.

3. If you have access to a second user account that is not authorized for certain tools, authenticate as that user and confirm that unauthorized tools do not appear in the tools list.

Troubleshooting

Need some help? Take a look at our agentgateway Knowledge Base articles or Community discussions. For further assistance, contact Support.

View Container Logs

View logs for the Duo Authorization Connector:

docker logs authz-connector

View logs for agentgateway:

docker logs agentgateway

Common Issues