Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

Feature available with the Enterprise Plan Connect your identity provider to Orq.ai to allow your team to sign in using their existing credentials.

Choosing a Protocol

Two protocols are available for both providers:

OIDC: Modern, lightweight protocol based on OAuth 2.0. Recommended for most organizations for its quick setup and JSON-based authentication.
SAML: XML-based protocol recommended for enterprise environments requiring fine-grained control over security attributes and assertions.

Identity Providers

Okta

OIDC
SAML

Create an OIDC app in Okta

Okta Admin Console Applications page showing the list of active applications with a Create App Integration button.

Click Create App Integration, then select OIDC - OpenID Connect and Web Application, and click Next.

Create a new app integration dialog with OIDC-OpenID Connect selected as sign-in method and Web Application as application type.

Configure the application:

App integration name: Orq.ai (or your preferred name)
Grant type: Ensure Authorization Code is selected

Sign-in redirect URIs:

https://my.orq.ai/v2/auth/sso/oidc/callback

Sign-out redirect URIs (optional):
```
https://my.orq.ai
```

New Web App Integration page with App integration name set to orq.ai, sign-in redirect URI set to https://my.orq.ai/v2/auth/sso/oidc/callback, and sign-out redirect URI set to https://my.orq.ai.

New Web App Integration page showing the Assignments section with Skip group assignment for now selected and a Save button.

Assign users

Go to the Assignments tab and click Assign → Assign to People or Assign to Groups.Select the users or groups that should have access to Orq.ai, then click Done.

Okta orq.ai application Assignments tab with the Assign dropdown open, showing Assign to People and Assign to Groups options.

By default, no users are assigned to a new Okta app.

Gather credentials

From the application’s General tab, scroll down to the Client Credentials section.Copy these values:

Client ID: Copy this value - you’ll use it as the Client ID in Orq.ai
Client secret: Click Copy to clipboard - you’ll use it as the Client Secret in Orq.ai

Okta orq.ai application General tab showing Client Credentials with Client ID and a client secret listed under CLIENT SECRETS.

Get the Provider URL

Your Provider URL is your Okta domain’s authorization server issuer URL:

https://{yourOktaDomain}/oauth2/default

Find your Okta domain in the top-right corner of the Okta Admin Console (e.g. acme.okta.com).

Configure in Orq.ai

Navigate to AI Studio → Organization → Auth.

Orq.ai Authentication settings page showing Okta and Active Directory as available SSO providers, each with a Configure button.

Enter the credentials you collected from Okta:

Select OIDC (selected by default)
Enter your Client ID
Enter your Client Secret
Enter your Provider URL
Enter your organization’s email domain(s) in Allowed domains (e.g., orq.ai)
Click Activate

Config Okta Single Sign-On panel with OIDC selected, showing fields for Client ID, Client Secret code, Provider URL, and Allowed domains.

Done! Test your login

Your SSO is now configured! Users can sign in at:

https://my.orq.ai/{your-workspace-key}/login

Orq.ai login page with a Continue with Okta button for Single Sign-On.

Define your SP Entity ID

Choose a unique identifier for your Service Provider Entity ID. We recommend:

urn:orq.ai:{your-workspace-key}

For example, if your workspace key is acme-corp, use urn:orq.ai:acme-corp.

The SP Entity ID must match exactly in both Okta and Orq.ai. Write it down - you’ll need it in multiple steps.

Create a SAML app in Okta

In the Okta Admin Console, go to Applications → Applications.

Okta Admin Console Applications page showing the orq.ai app as active with Client ID 0oa100vajmcL1YV5W698.

Click Create App Integration, select SAML 2.0, and click Next.

Create a new app integration dialog with SAML 2.0 selected as the sign-in method.

Enter a name (e.g. Orq.ai SSO) and click Next.

Create SAML Integration wizard showing Step 1 General Settings with App name set to orq.ai.

Configure SAML settings

Under SAML Settings, enter:

Single sign-on URL:

https://my.orq.ai/v2/auth/sso/saml/callback

Audience URI (SP Entity ID): The SP Entity ID you defined in Step 1
Name ID format: EmailAddress
Application username: Email

Create SAML Integration Step 2 showing Single sign-on URL set to https://my.orq.ai/v2/auth/sso/saml/callback and Audience URI set to urn:orq.ai:your-workspace-key.

Click Next, then Finish.

Create SAML Integration Step 3 Feedback page with This is an internal app that we have created selected and a Finish button.

Configure attribute statements

Go to the Sign On tab and click Edit in the Settings section.

Okta Sign On tab showing Credentials Details with Application username format set to Email, an empty Attribute statements section, and a Show legacy configuration toggle.

Under Attribute Statements, add these mappings:

Name	Expression
`email`	`user.email`
`firstName`	`user.firstName`
`lastName`	`user.lastName`

If you see a Show legacy configuration link, click it and use the classic format with Name, Name format (Basic), and Value columns.

Click Save.

These attribute mappings are required for SAML to work correctly with Orq.ai.

Gather credentials

In the Sign On tab, under Settings, click Edit to reveal the Metadata details.Collect these values:

Okta Field	Use in Orq.ai as
Sign on URL	Single Sign-On URL
Issuer	Identity Provider Entity ID
Signing Certificate (X.509)	X.509 Certificate (download)

Okta SAML 2.0 Metadata details showing Metadata URL, Sign on URL, Sign out URL, Issuer, and Signing Certificate for the orq.ai application.

Assign users

Go to the Assignments tab and click Assign → Assign to People or Assign to Groups.Select the users or groups that should have access to Orq.ai, then click Done.

By default, no users are assigned to a new Okta app.

Configure in Orq.ai

Navigate to AI Studio → Organization → Auth.

Enter the credentials you collected from Okta:

Select SAML
Enter your Service Provider Entity ID (from Step 1)
Enter your Identity Provider Entity ID (Issuer from Okta)
Enter your Single Sign-On URL (Sign on URL from Okta)
For X.509 Certificate: Open the downloaded certificate file in a text editor, copy all content including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, and paste it here
Enter your organization’s email domain(s) in Allowed domains (e.g., orq.ai)
Click Activate

Config Okta Single Sign-On panel with SAML selected, showing fields for Service Provider Entity ID, Identity Provider Entity ID, Single Sign-On URL, X.509 Certificate, and Allowed domains.

Done! Test your login

Your SSO is now configured! Users can sign in at:

https://my.orq.ai/{your-workspace-key}/login

Microsoft Entra ID - Active Directory

OIDC
SAML

Register an application in Azure

Azure Default Directory App registrations page with no applications registered and a Register an application button.

Configure the registration:

Name: Orq.ai (or your preferred name)
Supported account types: Select based on your organization’s needs

Redirect URI: Select Web and enter:

https://my.orq.ai/v2/auth/sso/oidc/callback

Click Register.

Register an application page with Name set to orq.ai, single-tenant account type selected, and Redirect URI set to https://my.orq.ai/v2/auth/sso/oidc/callback.

Gather credentials

Get the Client ID:From the app registration Overview page, copy the Application (client) ID - this is your Client ID for Orq.ai.

Azure orq.ai application overview showing the Application ID and Tenant ID in the Essentials section.

Create a Client Secret:Go to Certificates & secrets → Client secrets → New client secret.Add a description (e.g., Orq.ai SSO), select an expiration period, and click Add.

Certificates and secrets page with the Add a client secret panel open, showing Description set to orq.ai SSO and Expires set to 730 days.

Copy the secret value immediately - Azure only displays it once. If you lose it, you’ll need to generate a new secret.

Copy the Value field - this is your Client Secret for Orq.ai.

Certificates and secrets page showing the newly created orq.ai SSO client secret with expiry 2/10/2028.

Get the Provider URL

Your Provider URL is your tenant’s issuer URL:

https://login.microsoftonline.com/{tenant-id}/v2.0

Replace {tenant-id} with your Directory (tenant) ID, found on the app registration overview page.

Configure API permissions

Go to API permissions and ensure these Microsoft Graph permissions are granted:

openid
email
profile

Click Grant admin consent if required by your organization.

Orq.ai automatically requests the User.Read scope to retrieve user email addresses when the standard OIDC email claim is not available.

Configure in Orq.ai

Navigate to AI Studio → Organization → Auth.

Enter the credentials you collected from Azure:

Select OIDC (selected by default)
Enter your Client ID
Enter your Client Secret
Enter your Provider URL
Enter your organization’s email domain(s) in Allowed domains (e.g., acme.com)
Click Activate

Azure OIDC configuration form with fields for Client ID, Client Secret, Provider URL, and Allowed domains.

Done! Test your login

Your SSO is now configured! Users can sign in at:

https://my.orq.ai/{your-workspace-key}/login

Orq.ai login page with a Continue with Microsoft button for Single Sign-On.

Define your SP Entity ID

Choose a unique identifier for your Service Provider Entity ID. We recommend:

urn:orq.ai:{your-workspace-key}

For example, if your workspace key is acme-corp, use urn:orq.ai:acme-corp.

The SP Entity ID must match exactly in both Azure and Orq.ai. Write it down - you’ll need it in multiple steps.

Create an enterprise application in Azure

In the Azure portal, go to Microsoft Entra ID → Enterprise applications → New application.

Azure Enterprise applications page showing no applications found with a New application button.

Click Create your own application, name it (e.g. Orq.ai SSO), select Integrate any other application you don’t find in the gallery (Non-gallery), and click Create.

Azure Browse Microsoft Entra App Gallery page with the Create your own application panel showing a Name field and integration type options.

Azure orq.ai Enterprise Application Overview showing Application ID, Object ID, and Getting Started steps for setup.

Configure SAML

In the application, go to Single sign-on and select SAML.

Azure Single sign-on method selection page for orq.ai showing options: Disabled, SAML, Password-based, and Linked.

Under Basic SAML Configuration, click Edit and set:

Identifier (Entity ID): The SP Entity ID you defined in Step 1

Reply URL (ACS URL):

https://my.orq.ai/v2/auth/sso/saml/callback

Sign on URL:

https://my.orq.ai/{your-workspace-key}/login

Click Save.

Azure SAML-based Sign-on page for orq.ai showing Basic SAML Configuration with Identifier, Reply URL, Sign on URL, and a token signing certificate.

Configure attributes and claims

Click Edit on Attributes & Claims.Verify or add these claim mappings:

Short name	Full claim URI	Source attribute
`emailaddress`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	`user.mail`
`givenname`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`	`user.givenname`
`surname`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`	`user.surname`

Manage claim page with Name set to emailaddress and Source attribute set to user.mail.

Manage claim page with Name set to givenname and Source attribute set to user.givenname.

Manage claim page with Name set to surname and Source attribute set to user.surname.

Attributes and Claims page showing the required Unique User Identifier claim and additional claims for emailaddress, givenname, and surname mapped to user attributes.

Orq.ai supports both standard attribute names and full Microsoft Entra ID claim URIs (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). The default Entra ID claim mappings work out of the box.

Gather credentials

On the SAML configuration page, scroll down to collect these values:From the “Set up” section:

Login URL: Copy this value - you’ll use it as the Single Sign-On URL in Orq.ai
Microsoft Entra Identifier: Copy this value - you’ll use it as the Identity Provider Entity ID in Orq.ai

From the “SAML Certificates” section:

Click Download next to Certificate (Base64) and save the file

Azure SAML-based Sign-on page showing SAML Certificates with the App Federation Metadata URL and Set up orq.ai section with Login URL and Microsoft Entra Identifier.

Keep these values handy. You’ll need all three to configure SSO in Orq.ai in the next step.

Assign users and groups

Go to Users and groups (left menu) and click Add user/group.Select the users or groups that should have access to Orq.ai, then click Assign.

Azure orq.ai Users and groups page showing no application assignments with an Add user/group button.

By default, any user in your directory can authenticate. Assigning specific users or groups restricts access.

Configure in Orq.ai

Navigate to AI Studio → Organization → Auth.

Enter the credentials you collected from Azure:

Select SAML
Enter your Service Provider Entity ID (from Step 1)
Enter your Identity Provider Entity ID (Microsoft Entra Identifier from Azure)
Enter your Single Sign-On URL (Login URL from Azure)
For X.509 Certificate: Open the downloaded certificate file in a text editor, copy all content including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, and paste it here
Enter your organization’s email domain(s) in Allowed domains (e.g., orq.ai)
Click Activate

Done! Test your login

Your SSO is now configured! Users can sign in at:

https://my.orq.ai/{your-workspace-key}/login

Testing

Before rolling out to your entire organization:

Test the configuration with a single user
Verify the user is created automatically in Orq.ai (if auto-provisioning is enabled)
Check that the user’s profile information (name, email) is correct

Troubleshooting

Redirect URI mismatch

Error: “redirect_uri_mismatch” or “Invalid redirect URI”Solution: Verify the callback URL in your IdP exactly matches:

OIDC: https://my.orq.ai/v2/auth/sso/oidc/callback
SAML: https://my.orq.ai/v2/auth/sso/saml/callback

Common mistakes: extra slash at end, http:// instead of https://, typo in URL

Entity ID mismatch (SAML)

Error: “Audience restriction” or “Invalid audience”Solution: Verify the SP Entity ID matches exactly in both your IdP and Orq.ai configuration. It’s case-sensitive.

Invalid client secret (OIDC)

Error: “invalid_client” or “unauthorized_client”Solution: Regenerate the client secret in your IdP and update it in Orq.ai. Make sure to copy the secret immediately after creation.

User not assigned

Symptom: User can’t see the app or gets “access denied”Solution:

Okta: Go to application → Assignments and assign the user or their group
Azure: Go to Enterprise application → Users and groups → Add user/group

Certificate expired (SAML)

Symptom: SAML authentication suddenly stops workingSolution:

Download new certificate from your IdP
Update certificate in Orq.ai (AI Studio → Organization → Auth → Edit)
Click Save Changes

Email domain not allowed

Error: “Email domain not allowed”Solution: Add the user’s email domain to “Allowed domains” in your Orq.ai SSO configuration. Separate multiple domains with commas (e.g., acme.com, acme.io).

Missing email claim (Azure OIDC)

Symptom: Authentication succeeds but user has no emailSolution: Orq.ai automatically requests the User.Read Microsoft Graph scope. Verify this permission is granted:

Go to API permissions in your app registration
Verify User.Read is present
Click “Grant admin consent” if needed

Need Help?

Contact support@orq.ai with:

Your workspace key
Identity provider and protocol (e.g., “Okta SAML”)
Error message or screenshot

Workspace

Billing

Access

Developers

Enterprise SSO authentication

Choosing a Protocol

Identity Providers

Create an OIDC app in Okta

Assign users

Gather credentials

Get the Provider URL

Configure in Orq.ai

Done! Test your login

Define your SP Entity ID

Create a SAML app in Okta

Configure SAML settings

Configure attribute statements

Gather credentials

Assign users

Configure in Orq.ai

Done! Test your login

Register an application in Azure

Gather credentials

Get the Provider URL

Configure API permissions

Configure in Orq.ai

Done! Test your login

Define your SP Entity ID

Create an enterprise application in Azure

Configure SAML

Configure attributes and claims

Gather credentials

Assign users and groups

Configure in Orq.ai

Done! Test your login

Testing

Troubleshooting

Need Help?

Workspace

Billing

Access

Developers

Documentation Index

​Choosing a Protocol

​Identity Providers

Create an OIDC app in Okta

Assign users

Gather credentials

Get the Provider URL

Configure in Orq.ai

Done! Test your login

Define your SP Entity ID

Create a SAML app in Okta

Configure SAML settings

Configure attribute statements

Gather credentials

Assign users

Configure in Orq.ai

Done! Test your login

Register an application in Azure

Gather credentials

Get the Provider URL

Configure API permissions

Configure in Orq.ai

Done! Test your login

Define your SP Entity ID

Create an enterprise application in Azure

Configure SAML

Configure attributes and claims

Gather credentials

Assign users and groups

Configure in Orq.ai

Done! Test your login

​Testing

​Troubleshooting

​Need Help?

Choosing a Protocol

Identity Providers

Testing

Troubleshooting

Need Help?