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

# OAuth in SCM

> OAuth 2.1 authentication for MCP Gateway in SCM deployments — powered by Palo Alto Networks Cloud Authentication Service (CAS).

CAS (Cloud Authentication Service) is the OAuth 2.1 authentication method for MCP Gateway in **SCM (Strata Cloud Manager)** deployments. When an MCP client connects to a gateway running in SCM mode, CAS handles user authentication through Palo Alto Networks' identity infrastructure instead of the AI Gateway's built-in OAuth.

<Info>
  For standard deployments, use [AI Gateway OAuth](/docs/aigw/product/mcp-gateway/authentication/oauth) or [External OAuth](/docs/aigw/product/mcp-gateway/authentication/external-oauth) instead.
</Info>

<Warning>
  **Self-hosted MCP Gateway only.** OAuth in SCM currently works only with self-hosted (enterprise) MCP Gateway deployments. It is not available on the cloud-managed gateway.
</Warning>

***

## Overview

CAS bridges the MCP Gateway's OAuth flow with Palo Alto Networks' centralized authentication. Instead of users logging in with standard credentials, they authenticate through their organisation's identity provider (Entra ID, Okta, or on-prem Active Directory) via CAS.

### How It Works

```mermaid theme={"system"}
sequenceDiagram
    participant Client as MCP Client
    participant Gateway as AI Gateway<br/>(Data Plane)
    participant CP as AI Gateway<br/>(Control Plane)
    participant CAS as CAS (Palo Alto)
    participant IdP as Identity Provider

    Client->>Gateway: Connect to MCP server
    Gateway->>CP: Initiate OAuth flow
    CP->>CAS: Redirect user to CAS login
    CAS->>IdP: Authenticate via org IdP
    IdP-->>CAS: Identity verified
    CAS-->>CP: User authenticated
    CP-->>Gateway: Authorization code
    Gateway-->>Client: Access token issued
```

***

## Prerequisites

Before CAS authentication works for your MCP Gateway:

1. **CIE Directory Sync configured** — Users must be provisioned into workspaces via [CIE Directory Sync](/docs/aigw/product/enterprise-offering/org-management/directory-sync/cie-directory-sync). CAS authenticates users, but CIE is what provisions them into the system. Without CIE sync, authenticated users cannot be resolved.

2. **Authentication Profile selected** — An Auth Profile must be selected in the CIE Directory Sync configuration. This profile determines which identity provider is used for the CAS login flow. Auth Profiles are managed in the [CIE Authentication Profiles](https://docs.paloaltonetworks.com/identity/cloud-identity-engine/authenticate-users-with-the-cloud-identity-engine) console.

<Warning>
  CAS relies on CIE for user provisioning. If CIE Directory Sync is not configured, or no group-workspace mappings exist, users will authenticate successfully with CAS but fail to resolve — resulting in an authorization error.

  See [CIE Directory Sync](/docs/aigw/product/enterprise-offering/org-management/directory-sync/cie-directory-sync) for setup instructions.
</Warning>

***

## Setup

CAS authentication is automatically enabled on the MCP Gateway — no gateway-side configuration is needed. The admin configures identity and access in **SCM** and **CIE** before users can connect.

<Steps>
  <Step title="Connect a directory in CIE">
    Open the **CIE Console** and add your identity provider (Entra ID, Okta, or on-prem Active Directory) as a connected directory. This is the source of truth for users and groups.

    See [Palo Alto CIE documentation](https://docs.paloaltonetworks.com/identity/cloud-identity-engine/authenticate-users-with-the-cloud-identity-engine) for provider-specific setup instructions.
  </Step>

  <Step title="Configure Directory Sync in SCM">
    Navigate to **AI Security** → **AI Gateway** → **Admin Settings** → **Authentication** → **Directory Sync**.

    1. Select the **Connected Directory** you added in the previous step.
    2. Choose the **User Identity Attribute** — either **UPN (User Principal Name)** or **Mail (Primary Email)**.
    3. Click **Save**.

    <Note>
      The User Identity Attribute must match the email attribute your identity provider returns during CAS authentication. If there is a mismatch, authenticated users cannot be resolved.
    </Note>

    See [CIE Directory Sync](/docs/aigw/product/enterprise-offering/org-management/directory-sync/cie-directory-sync) for a full walkthrough.
  </Step>

  <Step title="Select an Auth Profile">
    On the same Directory Sync page, open the **Auth Profile** dropdown and select the authentication profile that should handle MCP login flows.

    <img src="https://mintcdn.com/portkey-docs/f8okiWRcK1jxaVX5/images/cas-auth-profile.png?fit=max&auto=format&n=f8okiWRcK1jxaVX5&q=85&s=3faed2d3f7ff2b9e67a5211d5bde8463" alt="Directory Sync configuration — Auth Profile dropdown showing available authentication profiles" width="1024" height="539" data-path="images/cas-auth-profile.png" />

    Auth Profiles are synced from [Authentication Profiles](https://docs.paloaltonetworks.com/identity/cloud-identity-engine/authenticate-users-with-the-cloud-identity-engine) configured in CIE. The selected profile determines which identity provider users see on the CAS login page.

    <Warning>
      **Do not skip this step.** Without an Auth Profile selected, users will not be redirected to the CAS login page and authentication will fail silently. This is the most commonly missed configuration step.
    </Warning>
  </Step>

  <Step title="Map groups to workspaces">
    In the **Group Mappings** section, map CIE directory groups to AI Gateway workspaces. Each mapping is a 1:1 link — all members of a mapped group are automatically provisioned into the corresponding workspace.

    Users must belong to at least one mapped workspace to access MCP servers provisioned in that workspace.
  </Step>
</Steps>

***

## User Experience

### First-Time Connection

When a user connects an MCP client to the gateway for the first time, the MCP client opens a browser window and the CAS login page is shown.

**Step 1 — Authenticate with your identity provider**

The user enters their organisation credentials on the CAS Single Sign-on page. This page is hosted by Palo Alto Networks and connects to your configured identity provider.

<Note>
  The login page appearance may vary depending on your configured Authentication Profile and identity provider. The example below shows the default CAS login for a local directory. Organisations using external IdPs (e.g., Entra ID, Okta) will see their IdP's login page instead.
</Note>

<img src="https://mintcdn.com/portkey-docs/bUZUYHwB1wkpbS92/images/cas-login.png?fit=max&auto=format&n=bUZUYHwB1wkpbS92&q=85&s=7a8a9d2e9e7d4e1e712af17916b87cc5" alt="CAS Single Sign-on — sample login page for a local directory configuration" width="1024" height="555" data-path="images/cas-login.png" />

**Step 2 — Approve access to the MCP server**

After authentication, the user is shown a consent page. It displays the MCP server being requested, the workspace it belongs to, and the redirect destination. The user can approve or reject the request.

<Note>
  If you are a member of multiple workspaces where the MCP server is provisioned, a workspace dropdown will appear on the consent page. Select the workspace you want the access token to be scoped to.
</Note>

<img src="https://mintcdn.com/portkey-docs/bUZUYHwB1wkpbS92/images/cas-consent.png?fit=max&auto=format&n=bUZUYHwB1wkpbS92&q=85&s=ee553380bcc30752c522f2d53bfe2486" alt="Authorization Request — consent page showing the MCP server name, workspace selection, redirect destination, and approve/reject buttons" width="1024" height="553" data-path="images/cas-consent.png" />

Once approved, the browser redirects back to the MCP client with an access token. The client can now make MCP requests.

**Step 3 — Authorize the upstream MCP server (if required)**

If the upstream MCP server uses its own OAuth (for example, GitHub), one more consent page follows: the upstream service's own authorization screen. After approving it, the gateway stores the upstream tokens and refreshes them automatically.

Servers that authenticate with static credentials — headers, API keys, or client credentials configured by an admin — skip this step entirely. See [End-to-end example: GitHub MCP server](#end-to-end-example-github-mcp-server) for a full walkthrough including this step.

### Subsequent Connections

After the initial authentication, the MCP client uses refresh tokens to maintain access. Users are not prompted to log in again until the refresh token expires or is revoked. Approval is also remembered — subsequent connections to the same MCP server skip the consent page.

***

## End-to-end example: GitHub MCP server

This walkthrough connects the hosted **GitHub MCP server** as an upstream server behind MCP Gateway in SCM mode. It shows both authentication layers in action:

| Layer             | What happens                                     | Who authenticates          |
| ----------------- | ------------------------------------------------ | -------------------------- |
| **Gateway auth**  | User logs in via CAS and approves gateway access | User → CAS → org IdP       |
| **Upstream auth** | Gateway exchanges an OAuth token with GitHub     | Gateway → GitHub OAuth App |

<Note>
  GitHub does not support Dynamic Client Registration (DCR), so you must create an OAuth App manually and supply the credentials to the gateway. Servers that support DCR (e.g., Linear, Notion) skip Steps 1–2 entirely.
</Note>

<Steps>
  <Step title="Create a GitHub OAuth App">
    Go to **GitHub** → **Settings** → **Developer settings** → **OAuth Apps** → **New OAuth App**.

    | Field                         | Value                                                                          |
    | ----------------------------- | ------------------------------------------------------------------------------ |
    | **Application name**          | A name your users will recognise (e.g., `AIGW MCP`)                            |
    | **Homepage URL**              | Your SCM tenant URL (e.g., `https://stratacloudmanager.paloaltonetworks.com/`) |
    | **Redirect URI**              | `<YOUR_MCP_GATEWAY_URL>/oauth/upstream-callback`                               |
    | **Expire user access tokens** | Enabled — issues a `refresh_token` so the gateway can refresh access silently  |

    Click **Register application**.

    <img src="https://mintcdn.com/portkey-docs/ofgw7Kad1Xo4zs6H/images/cas-github-oauth-app.png?fit=max&auto=format&n=ofgw7Kad1Xo4zs6H&q=85&s=f1c28aa500812e5494f960456978a274" alt="Registering the GitHub OAuth App with the MCP Gateway upstream callback as the redirect URI" width="2862" height="1642" data-path="images/cas-github-oauth-app.png" />

    <Warning>
      The redirect URI must match your gateway's public URL exactly, including scheme and port. A mismatch causes a `redirect_uri_mismatch` error from GitHub during the upstream authorization step.
    </Warning>
  </Step>

  <Step title="Copy the client credentials">
    On the OAuth App page:

    1. Copy the **Client ID**
    2. Click **Generate a new client secret** and copy the **Client Secret**

    <Warning>
      GitHub shows the client secret only once. Store it securely before leaving the page.
    </Warning>
  </Step>

  <Step title="Add the MCP server in SCM">
    In Strata Cloud Manager, go to **AI Security** → **AI Gateway** → **Integrations** → **MCP Registry** → **Add MCP Server**.

    | Field                   | Value                                |
    | ----------------------- | ------------------------------------ |
    | **Name**                | `Github Auth` (or any display name)  |
    | **URL**                 | `https://api.githubcopilot.com/mcp/` |
    | **Server Type**         | Streamable HTTP                      |
    | **Authentication Type** | OAuth 2.1                            |

    <img src="https://mintcdn.com/portkey-docs/ofgw7Kad1Xo4zs6H/images/cas-scm-add-mcp-server.png?fit=max&auto=format&n=ofgw7Kad1Xo4zs6H&q=85&s=5b238797181e5d290a6d0b5c1580c519" alt="Add MCP Server form in SCM with the GitHub MCP endpoint and Streamable HTTP server type" width="2876" height="1644" data-path="images/cas-scm-add-mcp-server.png" />

    In the **OAuth Metadata** field, paste the credentials from Step 2:

    ```json theme={"system"}
    {
      "client_id": "your_github_oauth_client_id",
      "client_secret": "your_github_oauth_client_secret",
      "token_endpoint_auth_method": "client_secret_post"
    }
    ```

    <Note>
      `token_endpoint_auth_method` must be `client_secret_post`. GitHub does not accept HTTP Basic authentication (`client_secret_basic`) on its token endpoint, so omitting this field results in a token exchange failure.
    </Note>
  </Step>

  <Step title="Provision workspaces and create the server">
    Click **Next: Choose Workspace**, select the workspaces that should have access to this server, then create the MCP server.

    <Tip>
      If you provision the server to more than one workspace, users who belong to multiple workspaces will see a workspace selector on the consent page in Step 7.
    </Tip>
  </Step>

  <Step title="Copy the MCP URL and connect your client">
    Go to **AI Gateway** → **Catalogs**, open the server you just created, and copy its **MCP URL**.

    Add the URL to your MCP client and click **Connect**:

    ```json theme={"system"}
    {
      "mcpServers": {
        "github": {
          "url": "<YOUR_MCP_SERVER_URL>"
        }
      }
    }
    ```

    No credentials go in the client config — the gateway handles both auth layers.
  </Step>

  <Step title="Sign in with CAS">
    The client opens a browser and redirects you to the CAS **Single Sign-on** page. Enter your organisation credentials and click **Login**.

    <img src="https://mintcdn.com/portkey-docs/bUZUYHwB1wkpbS92/images/cas-login.png?fit=max&auto=format&n=bUZUYHwB1wkpbS92&q=85&s=7a8a9d2e9e7d4e1e712af17916b87cc5" alt="CAS Single Sign-on page — sample login for a local directory configuration" width="1024" height="555" data-path="images/cas-login.png" />

    <Note>
      The login page appearance depends on your configured Authentication Profile. Organisations using an external IdP (Entra ID, Okta) see their own IdP login page instead.
    </Note>
  </Step>

  <Step title="Approve gateway access">
    The AI Gateway consent page opens, showing the MCP client requesting access and the redirect destination. If the server is provisioned to multiple workspaces, pick the workspace to scope the token to, then click **Approve**.

    <img src="https://mintcdn.com/portkey-docs/bUZUYHwB1wkpbS92/images/cas-consent.png?fit=max&auto=format&n=bUZUYHwB1wkpbS92&q=85&s=ee553380bcc30752c522f2d53bfe2486" alt="AI Gateway Authorization Request page with workspace selection and approve/reject buttons" width="1024" height="553" data-path="images/cas-consent.png" />
  </Step>

  <Step title="Authorize GitHub (upstream)">
    Because this is the first time you are using the GitHub MCP server, you are redirected to GitHub's own authorization page. Review the requested scopes and organisation access, then click **Authorize**.

    <img src="https://mintcdn.com/portkey-docs/ofgw7Kad1Xo4zs6H/images/cas-github-consent.png?fit=max&auto=format&n=ofgw7Kad1Xo4zs6H&q=85&s=409d247e403de817b6bf2083355bbf7b" alt="GitHub authorization page granting the OAuth App access to repositories, gists, and organisation data" width="2866" height="1662" data-path="images/cas-github-consent.png" />

    <Note>
      Organisation-owned resources may show **Disallowed by org owner** with a **Request** button. A GitHub organisation owner must approve the OAuth App before those repositories become available through the gateway.
    </Note>
  </Step>

  <Step title="Connection established">
    The browser redirects back to your MCP client and the connection succeeds. GitHub tools are now listed and callable through the gateway, with every call logged and governed by AI Gateway policies.
  </Step>
</Steps>

### Troubleshooting this flow

| Issue                                                 | Cause                                                               | Resolution                                                                 |
| ----------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `redirect_uri_mismatch` from GitHub                   | Redirect URI in the OAuth App does not match the gateway URL        | Set it to exactly `<YOUR_MCP_GATEWAY_URL>/oauth/upstream-callback`         |
| Token exchange fails after GitHub authorize           | Wrong client authentication method                                  | Set `token_endpoint_auth_method` to `client_secret_post` in OAuth Metadata |
| GitHub consent page never appears                     | Upstream auth type not set to OAuth 2.1                             | Edit the integration and set **Authentication Type** to OAuth 2.1          |
| Repositories missing after authorize                  | Org has not approved the OAuth App                                  | Ask a GitHub org owner to approve the app under **Third-party access**     |
| Re-prompted for GitHub authorization on every connect | `Expire user access tokens` disabled, so no refresh token is issued | Recreate/update the OAuth App with token expiry enabled                    |

***

## Comparison with Other Auth Methods

| Feature                | CAS (SCM)                | AI Gateway OAuth         | External OAuth           |
| ---------------------- | ------------------------ | ------------------------ | ------------------------ |
| **Identity provider**  | Palo Alto CAS → org IdP  | AI Gateway accounts      | Customer's IdP           |
| **User provisioning**  | Via CIE Directory Sync   | Self-service signup      | Manual or SCIM           |
| **Consent flow**       | Yes                      | Yes                      | Depends on IdP           |
| **Token management**   | Automatic                | Automatic                | Customer manages         |
| **MCP client support** | All standard MCP clients | All standard MCP clients | All standard MCP clients |

***

## Troubleshooting

| Issue                                              | Cause                             | Resolution                                                                                                                                             |
| -------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User authenticates but gets "authorization failed" | User not provisioned via CIE      | Configure [CIE Directory Sync](/docs/aigw/product/enterprise-offering/org-management/directory-sync/cie-directory-sync) and verify group-workspace mappings |
| "Email not found in claims" error                  | IdP not returning email attribute | Ensure the IdP includes the email claim. Verify the User Identity Attribute (UPN vs Mail) in CIE matches what the IdP returns                          |
| Consent page shows but redirect fails              | Browser blocking the redirect     | Check for browser extensions or corporate policies blocking redirects to custom URI schemes (`cursor://`, `vscode://`)                                 |
| Token refresh fails                                | Refresh token expired or revoked  | User must re-authenticate through the CAS flow                                                                                                         |

***

## Related

| Topic                                                                                                    | Description                                                            |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [CIE Directory Sync](/docs/aigw/product/enterprise-offering/org-management/directory-sync/cie-directory-sync) | Provision users from CIE into AI Gateway workspaces (required for CAS) |
| [Architecture](/docs/aigw/self-hosting/hybrid-deployments/architecture)                                       | Two-plane deployment architecture, identity flow and storage ownership |
| [OAuth](/docs/aigw/product/mcp-gateway/authentication/oauth)                                                  | AI Gateway's built-in OAuth for non-SCM deployments                    |
| [External OAuth](/docs/aigw/product/mcp-gateway/authentication/external-oauth)                                | Bring your own identity provider                                       |
| [GitHub MCP server](/docs/aigw/integrations/mcp-servers/github-mcp-server)                                    | Full tool reference for the GitHub MCP server                          |


## Related topics

- [OAuth](/docs/aigw/product/mcp-gateway/authentication/oauth.md)
- [OAuth Client Metadata](/docs/aigw/product/mcp-gateway/authentication/oauth-client-metadata.md)
- [Authentication](/docs/aigw/product/mcp-gateway/authentication.md)
- [MCP Advanced Configuration](/docs/aigw/product/mcp-gateway/advanced-configuration.md)
- [Add External MCP Servers](/docs/aigw/product/mcp-gateway/external-mcp-servers.md)