Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

SSO is available on the Enterprise plan only. Contact us to upgrade.

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

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

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
```

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.

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

Client ID and Client Secret in General tab

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.

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

Done! Test your login

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

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

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.

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

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

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

Click Next, then Finish.

Configure attribute statements

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

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)

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

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

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.

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.

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.

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.

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.

Application overview showing Client ID and Tenant ID

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

Done! Test your login

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

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

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.

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.

Configure SAML

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

Select SAML as the single sign-on method

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.

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`

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

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.

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

Organization

Security and Access

Virtual Private Cloud

Enterprise Authentication | SSO Setup

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?

Organization

Security and Access

Virtual Private Cloud

​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?