Okta SSO configuration for MCP

This article explains how to configure Okta as your Single Sign-On (SSO) provider for the Cequence AI Gateway using OAuth 2.1 authentication. You'll learn how to create an Okta application and integrate it with the Cequence AI Gateway.

Configuration scope and reusability

Single application, multiple MCP servers: You need to create only one Okta application that can authenticate users across all your MCP servers. The same client ID and secret can be reused for multiple MCP servers within your organization, simplifying management and reducing configuration overhead.

When to create separate applications: Consider creating separate Okta applications only if you need different access controls, user assignments, or security policies for different groups of MCP servers.

Prerequisites

Before starting, ensure you have:

• Okta admin console access with application management permissions
• Your application's redirect URI: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
• Basic understanding of OAuth 2.1 and OpenID Connect

Create your Okta application in the Cequence AI Gateway

Creating an Okta application establishes the OAuth 2.1 connection between your identity provider and the Cequence AI Gateway. This process involves three main steps: accessing the admin console, creating the integration, and selecting the appropriate method for web-based authentication.

Access the Okta admin console

1. Navigate to your Okta domain: https://[your-domain].okta.com
2. Select Admin in the top right corner
3. Sign in with your administrator credentials

Create the Okta application integration

1. In the Okta Admin Console, select Applications from the left sidebar
2. Select Applications in the submenu
3. Select Create App Integration

Select integration method

1. Choose OIDC - OpenID Connect for OAuth 2.1 integration
2. Select Web Application as your application type
3. Select Next

Configure the Okta application settings

Application settings define how your Okta integration behaves and what permissions the integration requires. In this step you'll configure the following elements:

• Basic information
• Grant types for OAuth flows
• Redirect URIs for authentication callbacks
• Initial user access controls

Basic information

Configure these required settings:

Setting	Value	Notes
App integration name	Cequence AI Gateway	Use a descriptive name for your organization
App logo	Upload your logo (optional)	PNG or JPG format

Grant types

Select these grant types:

• Authorization Code (required for OAuth 2.1)
• Refresh Token (recommended for session management)

Redirect URIs

Add the Cequence AI Gateway callback URL.

https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

note

Important considerations:

• The URL must match exactly, including protocol and path
• No trailing slashes unless required
• Multiple URLs can be added for different environments

User assignments

Choose your access control approach:

• Controlled access: Assign specific users or groups (recommended for production)
• Allow everyone in your organization: All users can access
• Skip group assignment for now: Configure later

Select Save to create the application.

Get the Okta application credentials

After creating your application, Okta generates the credentials and endpoints needed to configure your MCP servers. You'll need to collect the client credentials, note the OAuth 2.1 endpoint URLs, and verify that required scopes are available for user authentication.

Client information

Field	Purpose	Action
Client ID	Public identifier	Copy for MCP server configuration
Client Secret	Private authentication key	Store securely

note

Security note: Never expose your client secret in client-side code or version control. Store it securely in your server configuration.

OAuth 2.1 endpoints

Your Okta endpoints follow this format:

Endpoint	URL
Authorization URL	https://[your-domain].okta.com/oauth2/default/v1/authorize
Token URL	https://[your-domain].okta.com/oauth2/default/v1/token

Confirm required scopes

Your Okta application requires these scopes to access authentication information. Typically a new Okta application, like the one created in this procedure, has those scopes set by default. Confirm that your application has these scopes granted before you continue.

1. In your Okta application, go to the Okta API Scopes tab
2. Confirm these scopes are granted:
   • openid
   • email
   • profile
3. If any are missing, select Grant next to each required scope

Assign users and groups

User and group assignments in Okta determine who can authenticate through your application to access MCP servers. Perform these actions on the Okta Admin Console. Without proper assignments, users will receive authentication errors when attempting to access MCP servers, even if those servers are visible in the AI Gateway dashboard.

Assign individual users

1. Navigate to the Assignments tab in your application
2. Select Assign → Assign to People
3. Search for users by name or email
4. Select Assign next to each user
5. Configure user-specific settings if needed
6. Select Save and Go Back, then Done

Assign groups

1. Select Assign → Assign to Groups
2. Select the appropriate groups
3. Select Assign for each group
4. Select Done

Configure MCP servers

Use the Okta credentials to configure authentication across all your MCP servers that need SSO access.

OAuth 2.1 configuration

The Cequence AI Gateway wizard for creating a new MCP server or editing an existing MCP server includes an Authentication step. When the wizard is at the Authentication step, select OAuth 2.1 as the authentication type and select +Add New OAuth 2.1 Client Credentials to add a new OAuth token. Fill in the fields with the following information:

Parameter	Value
clientId	Your client ID
clientSecret	Your client secret
authorizationUrl	https://[your-domain].okta.com/oauth2/default/v1/authorize
tokenUrl	https://[your-domain].okta.com/oauth2/default/v1/token
redirectUri	https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
scopes	["email", "profile", "openid"]

Configuration reuse: The same client ID, client secret, and endpoint URLs can be used across multiple MCP servers, reducing complexity and maintenance overhead.

The Getting Started section provides complete information on creating MCP servers on the Cequence AI Gateway.

Test your configuration

Testing ensures your Okta integration works correctly before deploying to production. You'll verify the complete authentication flow and troubleshoot any common configuration issues that might prevent successful user authentication.

Verify the OAuth flow

1. Initiate authentication from your MCP client
2. Verify redirection to Okta's login page
3. Complete authentication
4. Verify successful redirect to the callback URL
5. Verify the MCP server receives and processes the authorization code

Common troubleshooting

Problem	Solution
Redirect URI mismatch	Verify the URI in Okta matches your MCP configuration exactly
Invalid client credentials	Double-check that client ID and secret are copied correctly
User not authorized	Review user and group assignments in Okta
Scope errors	Confirm all required scopes are enabled

Security best practices

Implementing proper security measures protects your OAuth integration and user data. Security best practices focus on three key areas: managing credentials securely, controlling user access appropriately, and monitoring authentication activity for potential threats.

Credential management

• Rotate client secrets regularly
• Update all MCP servers when secrets change
• Use secure secret management tools

Access control

• Apply least privilege principles
• Use groups for easier user management
• Regular review access assignments

Monitoring

• Enable Multi-Factor Authentication (MFA) in Okta
• Monitor Okta access logs
• Set up alerts for suspicious activities
• Review authentication patterns regularly

Advanced configuration

Advanced configuration options enable you to customize your Okta integration beyond the default settings. You can use custom authorization servers for specific organizational requirements or adjust token lifetimes to meet your security policies.

Custom authorization servers

When using a custom authorization server, instead of the default:

1. Navigate to Security → API in the Okta Admin Console
2. Select your custom authorization server
3. Update your MCP configuration with the custom endpoints:

   https://[your-domain].okta.com/oauth2/[server-id]/v1/authorize
   https://[your-domain].okta.com/oauth2/[server-id]/v1/token

Token lifetime management

Adjust token lifetimes based on security requirements:

1. Go to Security → API → Authorization Servers
2. Select your authorization server
3. Select the Access Policies tab
4. Edit policy rules to modify token lifetimes

Additional resources

• Okta Developer Documentation
• OAuth 2.1 Specification
• OpenID Connect Specification
• Cequence AI Gateway Documentation

Next steps

After successful Okta SSO configuration:

1. Test integration with representative users
2. Configure additional Okta security policies
3. Implement monitoring and alerting
4. Document your configuration for team reference
5. Consider automated user provisioning for larger deployments