SSO

SSO support for enterprises

Portkey Control plane supports following authentication protocols for enterprise customers.

1. OIDC (OpenID Connect)
2. SAML 2.0 (Security Assertion Markup Language)

Below are the steps to integrate your identity provider with our system.

Auto-Provisioning: First-time SSO users are automatically provisioned to your organization when they log in. If a user has a pending invite, it will be automatically accepted during their first SSO login.

Table of Contents

• OIDC Integration
• SAML Integration

OIDC Integration

For OIDC integration, we require the following information from your identity provider:

Required Information

• Issuer URL: The URL of your identity provider’s OIDC authorization endpoint. Wellknown OIDC configuration should be available at this URL.
• Client ID: The client ID provided by your identity provider.
• Client Secret Key: The client secret provided by your identity provider.

Setup Steps

Following scopes are required for Portkey to work with OIDC:

• openid
• profile
• email
• offline_access

For airgapped deployments, you can configure additional custom OIDC scopes by setting the OIDC_CUSTOM_SCOPES environment variable (comma-separated list) on the backend service.

General

• Create an OIDC application in your identity provider.
• Once the application is created, please note the following details:
  • Issuer URL
  • Client Id
  • Client Secret
• Update the above details in Portkey Control Plane in Admin Settings > Authentication Settings > OIDC.

Okta

• Go to Applications tab on Okta dashboard and create a new app integration.
• Select OIDC - OpenID Connect as the signin method.
• Select Application Type as Web Application
• On the next step, fill in the required fields. The signin redirect URI should be https://app.portkey.ai/v2/auth/callback and the Grant Type should have Authorization code and Refresh Token as checked
• Create Application
• After the application is created, go to the General section of the application.
• Click on the edit button for the General Settings section.
• Select Either Okta or app for the Login initiated by field.
• Add https://app.portkey.ai/v2/auth/callback as the initiate login URI
• Go to the Sign On section and click on Edit. Select Okta Url as the issuer and save the updated details
• Once everything is setup please note the following details
  • Issuer URL will be the Issuer from above step
  • Client Id would be same as Audience/ Client ID
  • Client Secret is needed for Web App based flow. It can be found under General > Client Credentials > Client Secrets in your Okta App.
• Update the above details in Portkey Control Plane in Admin Settings > Authentication Settings > OIDC

Azure AD

• Sign in to the Azure portal.
• Search for and select Azure Active Directory.
• Under Manage, select App registrations.
• Select New registration.
• Enter a name.
• Select one of the Supported account types that best reflects your organization requirements.
• Under Redirect URI,
  • Select Web as the platform
  • Enter https://app.portkey.ai/v2/auth/callback as redirect url
• Click on Register
• Once saved, go to Certificates & secrets
  • Click on Client Secrets
  • Click on New client secret
  • Use appropriate settings according to your organization
  • Click on Add
• Once everything is set up. Please go to Overview
  • Click on Endpoints and note the OpenID Connect metadata document url
  • Please note the Application (client) ID from Essentials
  • Please note the Client Secret from Certificates & secrets
• Update the above details in Portkey Control Plane in Admin Settings > Authentication Settings > OIDC

SAML Integration

For SAML integration, we require the following information from your identity provider:

Required Information

Either of the following information is required:

• Provider Metadata URL: The URL from your identity provider containing the metadata, including SAML configuration details.
• Provider Metadata XML: The XML metadata of your identity provider.

Setup Steps

General

• Create an SAML application in your identity provider.
• Once the application is created, please note the following details:
  • Provider Metadata URL
  • Provider Metadata XML
• Update the above details in Portkey Control Plane in Admin Settings > Authentication Settings > SAML.

Okta

• Go to Applications tab on okta dashboard and create a new app integration.
• Select SAML 2.0 as the signin method.
• In Configure SAML, update
  • Single sign-on URL with Saml redirect url. You can find the Saml redirect url from the Admin Settings > Authentication Settings > SAML Redirect/Consumer Service URL from Portkey Control Plane.
  • Audience URI (SP Entity ID) with SAML Entity ID from Portkey Control Plane.
• Create Application
• Once everything is set up, please note the following details
  • Sign On tab > SAML 2.0 tab > Metadata details > Metadata URL
• Update the above details in Portkey Control Plane in Admin Settings > Authentication Settings > SAML

Azure AD

• Sign in to the Azure portal.
• Search for and select Azure Active Directory.
• Under Manage, select App registrations.
• Select New registration.
• Enter a name.
• Select one of the Supported account types that best reflects your organization requirements.
• Under Redirect URI,
  • Select Web as the platform
  • Enter the SAML Redirect/Consumer Service URL from Portkey Control Plane as redirect url
• Select Register.
• Select Endpoints at the top of the page.
• Find the Federation metadata document URL and select the copy icon.
• In the left side panel, select Expose an API.
• To the right of Application ID URI, select Add.
  • Enter SAML Entity ID from Portkey Control Plane as the App ID URI.
• Select Save.
• Once everything is set up, please note the following details
  • Copy the Federation metadata document URL and paste it in Portkey Control Plane in Admin Settings > Authentication Settings > SAML > Provider Metadata URL

---

Allowed Domains

In Admin Settings > Authentication Settings, you can configure Allowed Domains to restrict which email domains are permitted to authenticate with your organization. You can add one or more domains (e.g., example.com) to control access.

Subdomain Support

You can enable the allow_subdomains flag on a root domain to automatically allow authentication from all subdomains under that root domain.

For example, if you add example.com as an allowed domain and enable allow_subdomains, users with emails from any subdomain like dev.example.com, team.example.com, or us.example.com will also be allowed to authenticate.

The allow_subdomains flag can only be enabled on root domains. If you attempt to enable it on a subdomain (e.g., dev.example.com), the operation will fail and return an error. Always set this flag on the root domain instead.

Configuration	allow_subdomains	Allowed Emails
example.com	Disabled	Only *@example.com
example.com	Enabled	*@example.com, *@dev.example.com, *@team.example.com, etc.
dev.example.com	Enabled	Error — flag only works on root domains
dev.example.com	Disabled	Only *@dev.example.com