> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Identity Providers

> Set up Auth0, Microsoft Entra ID, or Descope for MCP client authentication

Configure your identity provider to authenticate users accessing in-house MCP servers through Golf Gateway. Golf Gateway supports Auth0, Microsoft Entra ID (Azure AD), and Descope.

## When IdP Configuration is Required

The IdP configuration in the **Connections** page is required when you have **in-house MCP servers** where you control the identity provider. In this scenario:

1. Users authenticate with your IdP and receive a JWT token
2. MCP clients present this token to Golf Gateway
3. Gateway validates the token using your IdP's JWKS endpoint
4. Gateway extracts user identity for RBAC and audit logging

<Info>
  For **third-party MCP servers** that have their own OAuth authorization, users authenticate through Golf Gateway's Authorization Server, which proxies the OAuth flow between the MCP client and the upstream server. The IdP configuration in Connections is not used in this flow.
</Info>

## Prerequisites

<Tabs>
  <Tab title="Auth0">
    Create a Single Page Application or Regular Web Application in Auth0.

    **Required:**

    * Domain (e.g., `your-tenant.auth0.com`)
    * JWKS endpoint URL (e.g., `https://your-tenant.auth0.com/.well-known/jwks.json`)

    **For Capability Discovery (Optional):**

    * Machine-to-Machine Application
    * Client ID and Client Secret for the M2M app
  </Tab>

  <Tab title="Microsoft Entra ID">
    Register an application in Microsoft Entra ID.

    **Required:**

    * Directory (tenant) ID

    **For Capability Discovery (Optional):**

    * App registration with appropriate permissions
    * Client secret for the app registration
  </Tab>

  <Tab title="Descope">
    Gather your Descope credentials from the Descope Console.

    **Required:**

    * Project ID

    **For Capability Discovery (Optional):**

    * Inbound App credentials
  </Tab>
</Tabs>

## When Capability Discovery Credentials Are Needed

Capability discovery credentials (M2M tokens) enable the gateway to fetch MCP server capabilities autonomously. These are **optional** but required in specific scenarios:

<AccordionGroup>
  <Accordion title="Scheduled capability refresh">
    When you enable automatic capability refresh for an MCP server, the gateway periodically connects to discover tools, prompts, and resources. Since no user is present during these background jobs, M2M credentials authenticate the gateway as a service account.
  </Accordion>

  <Accordion title="Capability versioning with approval workflow">
    When `capability_versioning_enabled` is set on a server, the gateway tracks changes to capabilities over time. New or modified tools are flagged for approval before becoming available. M2M credentials enable the gateway to discover these changes automatically.
  </Accordion>

  <Accordion title="Fine-grained capability RBAC">
    For advanced RBAC that uses tool annotations (read-only, destructive, etc.), the gateway needs capability schemas to enforce policies. M2M credentials allow the gateway to fetch and cache these schemas for runtime access control decisions.
  </Accordion>
</AccordionGroup>

**You don't need capability discovery credentials if:**

* You only use manual, user-initiated capability discovery
* You use simple server-level RBAC without capability granularity
* You don't need scheduled refresh

## Configure via Control Plane

<Tabs>
  <Tab title="Auth0">
    1. Navigate to **Connections** in the sidebar
    2. In the **Identity Providers** section, click **Add identity provider**
    3. Select **Auth0**
    4. Configure the following sections:

    **User Identity Extraction (Required)**

    These fields are required to validate JWT tokens from your MCP clients.

    | Field         | Description                         | Example                                               |
    | ------------- | ----------------------------------- | ----------------------------------------------------- |
    | Display name  | Friendly name for this IdP          | `Production Auth0`                                    |
    | JWKS endpoint | Auth0 JWKS URL for token validation | `https://your-tenant.auth0.com/.well-known/jwks.json` |

    **Token Audience Validation (Optional)**

    Configure audience validation to ensure tokens are intended for your API.

    | Field           | Description                   | Example                   |
    | --------------- | ----------------------------- | ------------------------- |
    | API identifiers | List of valid audience values | `https://api.example.com` |

    <Info>
      API identifiers must match the `aud` claim in your JWT tokens. Add multiple identifiers if your tokens may have different audiences.
    </Info>

    **Capability Discovery (Optional)**

    These M2M credentials allow the gateway to discover MCP server capabilities on behalf of users.

    | Field         | Description                   | Example            |
    | ------------- | ----------------------------- | ------------------ |
    | Client ID     | M2M application Client ID     | `abc123...`        |
    | Client secret | M2M application Client Secret | `***`              |
    | Scopes        | OAuth scopes                  | `openid` (default) |

    5. Click **Save**
  </Tab>

  <Tab title="Microsoft Entra ID">
    1. Navigate to **Connections** in the sidebar
    2. In the **Identity Providers** section, click **Add identity provider**
    3. Select **Microsoft Entra ID**
    4. Configure the following sections:

    **User Identity Extraction (Required)**

    These fields are required to validate JWT tokens from your MCP clients.

    | Field        | Description                | Example                                |
    | ------------ | -------------------------- | -------------------------------------- |
    | Display name | Friendly name for this IdP | `Corporate Entra ID`                   |
    | Tenant ID    | Azure AD tenant ID (UUID)  | `12345678-1234-1234-1234-123456789012` |

    **Token Audience Validation (Optional)**

    Configure audience validation to ensure tokens are intended for your API.

    | Field           | Description                   | Example             |
    | --------------- | ----------------------------- | ------------------- |
    | API identifiers | List of valid audience values | `api://your-app-id` |

    **Capability Discovery (Optional)**

    These credentials allow the gateway to discover MCP server capabilities on behalf of users.

    | Field         | Description                    | Example              |
    | ------------- | ------------------------------ | -------------------- |
    | Client ID     | App registration Client ID     | `abc123...`          |
    | Client secret | App registration Client Secret | `***`                |
    | Scopes        | API scopes                     | `.default` (default) |

    5. Click **Save**
  </Tab>

  <Tab title="Descope">
    1. Navigate to **Connections** in the sidebar
    2. In the **Identity Providers** section, click **Add identity provider**
    3. Select **Descope**
    4. Configure the following sections:

    **User Identity Extraction (Required)**

    These fields are required to validate JWT tokens from your MCP clients.

    | Field        | Description                | Example              |
    | ------------ | -------------------------- | -------------------- |
    | Display name | Friendly name for this IdP | `Descope Production` |
    | Project ID   | Descope Project ID         | `P2abc123...`        |

    <Info>
      For Descope, the JWKS endpoint and issuer URL are automatically derived from your Project ID.
    </Info>

    **Token Audience Validation (Optional)**

    Configure audience validation to ensure tokens are intended for your API.

    | Field           | Description                   | Example                   |
    | --------------- | ----------------------------- | ------------------------- |
    | API identifiers | List of valid audience values | `https://api.example.com` |

    **Capability Discovery (Optional)**

    These credentials allow the gateway to discover MCP server capabilities on behalf of users.

    | Field         | Description               | Example            |
    | ------------- | ------------------------- | ------------------ |
    | Client ID     | Inbound App Client ID     | `abc123...`        |
    | Client secret | Inbound App Client Secret | `***`              |
    | Scopes        | OAuth scopes              | `openid` (default) |

    5. Click **Save**
  </Tab>
</Tabs>

## Configure via YAML (Distributed Mode)

<Tabs>
  <Tab title="Auth0">
    ```yaml theme={null}
    identity_providers:
      - name: auth0
        type: auth0
        issuer: https://YOUR_TENANT.auth0.com/
        jwks_uri: https://YOUR_TENANT.auth0.com/.well-known/jwks.json
        api_identifiers:
          - https://your-api.example.com
        # Optional: M2M credentials for capability discovery
        client_id: ${AUTH0_CLIENT_ID}
        client_secret: ${AUTH0_CLIENT_SECRET}
    ```
  </Tab>

  <Tab title="Microsoft Entra ID">
    ```yaml theme={null}
    identity_providers:
      - name: entra-id
        type: microsoft-entra-id
        tenant_id: YOUR_TENANT_ID
        issuer: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
        jwks_uri: https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys
        api_identifiers:
          - api://your-app-id
        # Optional: Credentials for capability discovery
        client_id: ${ENTRA_ID_CLIENT_ID}
        client_secret: ${ENTRA_ID_CLIENT_SECRET}
    ```
  </Tab>

  <Tab title="Descope">
    ```yaml theme={null}
    identity_providers:
      - name: descope
        type: descope
        project_id: ${DESCOPE_PROJECT_ID}
        # issuer and jwks_uri are auto-generated for Descope
        # Optional: Credentials for capability discovery
        client_id: ${DESCOPE_CLIENT_ID}
        client_secret: ${DESCOPE_CLIENT_SECRET}
    ```
  </Tab>
</Tabs>

## Authentication Flows

Golf Gateway supports two authentication scenarios depending on the MCP server type:

### In-House Servers (Direct IdP Validation)

For MCP servers you own and control, users authenticate with your IdP:

1. User authenticates with your IdP (Auth0, Entra ID, Descope)
2. MCP client receives JWT token
3. Client presents token to Golf Gateway
4. Gateway validates token using IdP's JWKS endpoint (configured in Connections)
5. Gateway extracts user identity and applies RBAC policies
6. Request is forwarded to the in-house MCP server

**This is when IdP configuration in Connections is required.**

### Third-Party Servers (Gateway Authorization Server)

For third-party MCP servers with their own OAuth requirements, Golf Gateway acts as an OAuth 2.0 Authorization Server that proxies authentication between MCP clients and upstream servers:

1. MCP client discovers OAuth endpoints via the gateway
2. Gateway redirects user to authenticate with your platform SSO
3. After authentication, user separately authorizes with the third-party MCP server
4. Gateway stores the user's OAuth token for that server
5. On subsequent requests, gateway injects the stored token when proxying to the upstream server

**IdP configuration in Connections is NOT used in this flow.**

## Linking IdP to MCP Servers

After configuring an IdP, link it to your in-house MCP servers:

1. Go to **Connections** > **MCP Servers**
2. Create or edit an MCP server
3. Set **Server type** to **In-house**
4. Select your IdP from the **Identity provider** dropdown
5. Save

The gateway will now validate tokens for that server using the selected IdP configuration.

## Troubleshooting

### Token validation fails

* Verify JWKS endpoint is accessible from your gateway
* Check that API identifiers match the `aud` claim in your tokens
* Ensure the token hasn't expired

### User identity not extracted

* Verify the JWT contains expected claims (sub, email, name)
* Check gateway logs for token validation errors

### RBAC not working as expected

* Verify group names in RBAC policies match JWT claims exactly (case-sensitive)
* Check the 3-layer policy hierarchy (org → gateway → server)
* Use audit logs to see which user identity was extracted

## Next Steps

* [Set Up Server RBAC](/gateway/guides/security/setup-server-rbac) - Control server access based on user identity
* [Set Up Capability RBAC](/gateway/guides/security/setup-capability-rbac) - Fine-grained tool permissions