Okta

Connect Okta to sign users in with Okta credentials and exchange tokens so MCP tools call downstream APIs under each user's identity.

Set up sign-in first. Continue with token exchange only if MCP tools need to call downstream APIs as each person.

Register the Okta Application

Use the published Okta Integration Network (OIN) app or create a custom OIDC integration.

Option A: Install from Okta Integration Network (Recommended)

1. In the Okta Admin Console, go to Applications → Applications → Browse App Catalog.
2. Search for Archestra and click Add integration.
3. Under General Settings, enter your bare Archestra domain without protocol (e.g. archestra.example.com).
4. Assign the users or groups allowed to access Archestra.
5. On the Sign On tab, copy the Client ID and Client Secret.
6. Disable DPoP: in General → Client Credentials, ensure Require Demonstrating Proof of Possession (DPoP) is disabled.

Option B: Create a Custom OIDC Integration

1. Go to Applications → Applications → Create App Integration.
2. Select OIDC - OpenID Connect and Web Application.
3. Set Sign-in redirect URIs to:
   https://<archestra-domain>/api/auth/sso/callback/Okta
4. Set Sign-out redirect URIs to:
   https://<archestra-domain>/auth/sign-in
5. Under Assignments, assign allowed users or groups, save, and copy the Client ID and Client Secret.

Configure SSO in Archestra

1. In Archestra, go to Settings → Identity Providers and click Enable on Okta.
2. Set Issuer to your Okta organization URL (e.g. https://example.okta.com).
3. Paste the Client ID and Client Secret.
4. Leave Discovery Endpoint empty (Archestra discovers OIDC metadata automatically).
5. Click Create Provider.

Test sign-in in an incognito browser window.

Map Roles and Sync Teams

Configure claim mapping to assign roles and teams on sign-in:

• Role Mapping: In Okta, include the groups claim in ID tokens. In Archestra, create rules matching groups like Archestra_Admins to target roles. See Role Mapping.
• Team Sync: Link Archestra teams to Okta group names in Settings → Teams. See Team Sync.

Configure Okta for Token Exchange

To call downstream APIs as the calling user, configure Okta to accept signed token-exchange requests:

1. Generate a PKCS#8 RSA keypair.
2. In the Okta Admin Console, open your Archestra application's General settings.
3. Under Client Authentication, select Public Key / Private Key and add your public key. Save the assigned Key ID (kid).
4. Enable the token-exchange grant type: urn:ietf:params:oauth:grant-type:token-exchange.
5. In your authorization server policies, allow the Archestra app to request tokens for downstream API audiences.

Enable Token Exchange in Archestra

1. In Settings → Identity Providers, click Edit on Okta, and open Tool Authentication.
2. Set Exchange Token Endpoint to https://<org>.okta.com/oauth2/v1/token.
3. Set Exchange Client Authentication to Private key JWT.
4. Enter your Signing Key ID and paste your Private Key PEM.
5. Set User's Token to Exchange to ID token.
6. Click Update Provider.

Use It in an MCP Server

Pick IdP token exchange on the server, choose Okta as the Identity Provider, and set Managed Resource Identifier to the downstream audience, such as api://internal-service. See IdP Token Exchange.

Troubleshooting