Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

Feature available with the Enterprise Plan Connect an identity provider to Orq.ai to allow the team to sign in using their existing credentials. Any identity provider that supports OIDC or SAML 2.0 is compatible.

Choose a Protocol

Two protocols are available:

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.

Configure SSO in Orq.ai

Navigate to Auth settings

Navigate to Settings → Auth in the AI Gateway sidebar

Orq.ai Authentication settings page showing available SSO provider options, each with a Configure button.

Only one SSO connection can be active at a time. To switch providers, disconnect the current connection first.

Connect a provider

Click Add SSO Connection, select the protocol, and follow the guide for the identity provider:

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 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: use as the Client ID in Orq.ai
Client secret: click Copy to clipboard and use 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

The Provider URL is the Okta domain’s authorization server issuer URL:

https://{yourOktaDomain}/oauth2/default

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

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.

Orq.ai Authentication settings page showing available SSO providers, each with a Configure button.

Enter the credentials collected from Okta:

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

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Okta OIDC.

Define the SP Entity ID

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

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

For example, if the 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; it is needed 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.

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 defined in Step 1
Name ID format: EmailAddress
Application username: Email

Create SAML Integration Step 2 showing Single sign-on URL and Audience URI fields.

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 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 a Show legacy configuration link appears, 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, then click Done.

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

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.Enter the credentials collected from Okta:

Select SAML
Enter the Service Provider Entity ID (from Step 1)
Enter the Identity Provider Entity ID (Issuer from Okta)
Enter the 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 the organization’s email domain(s) in Allowed domains (e.g., orq.ai)
Click Activate

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Okta SAML.

https://mintcdn.com/orqai/d-t0Z04KwFlGVsS1/images/logos/azure.svg?fit=max&auto=format&n=d-t0Z04KwFlGVsS1&q=85&s=aceb7fab6763d5b7ad595606503fe0a2

Microsoft Entra ID - Active Directory

OIDC
SAML

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

Configure the registration:

Name: Orq.ai (or preferred name)
Supported account types: select based on the 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 the 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 lost, generate a new secret.

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

Certificates and secrets page showing the newly created orq.ai SSO client secret with its expiry date.

Get the Provider URL

The Provider URL is the tenant’s issuer URL:

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

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

Azure orq.ai application overview showing the Directory (tenant) ID in the Essentials section.

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 the 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 Settings → Auth in the AI Gateway.Enter the credentials collected from Azure:

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

Configure Single Sign-On panel with OIDC selected for Microsoft Entra ID, showing fields for Client ID, Client Secret, Provider URL, and Allowed domains.

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Microsoft Entra ID OIDC.

Define the SP Entity ID

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

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

For example, if the 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; it is needed 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 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, collect these values:From the “Set up” section:

Login URL: use as the Single Sign-On URL in Orq.ai
Microsoft Entra Identifier: use 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.

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 the directory can authenticate. Assigning specific users or groups restricts access.

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.Enter the credentials collected from Azure:

Select SAML
Enter the Service Provider Entity ID (from Step 1)
Enter the Identity Provider Entity ID (Microsoft Entra Identifier from Azure)
Enter the 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 the organization’s email domain(s) in Allowed domains (e.g., orq.ai)
Click Activate

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Microsoft Entra ID SAML.

Keycloak

OIDC
SAML

Choose or create a realm

Log in to the Keycloak admin console. From the realm dropdown (top-left), select an existing realm or click Create realm. Note the realm name; it is needed for the Provider URL.

Keycloak may update their admin console interface over time. Refer to Keycloak’s official documentation if any steps differ.

Create a new client

In the chosen realm, navigate to Clients and click Create client.

Keycloak Clients page showing the list of clients with a Create client button.

Configure the General Settings:

Field	Value
Client type	`OpenID Connect`
Client ID	`orq-ai` (or preferred identifier)
Name	`orq.ai` (optional display name)

Click Next.

Keycloak Create client General Settings form showing Client type set to OpenID Connect and Client ID set to orq-ai.

Configure capability config

Enable the following:

Field	Value
Client authentication	`On`
Standard flow	`On`

Leave Direct access grants, Implicit flow, and Service accounts roles off unless the organization requires them. Click Next.

Keycloak capability config step showing Client authentication On and Standard flow On.

Configure login settings

Enter the following:

Field	Value
Valid redirect URIs	`https://my.orq.ai/v2/auth/sso/oidc/callback`
Web origins	`https://my.orq.ai`

Click Save.

Keycloak Login settings form showing Valid redirect URIs and Web origins fields configured for orq.ai.

Collect the Client Secret

Open the client just created, go to the Credentials tab, and copy the Client Secret.

Keycloak Credentials tab showing the Client Secret field with a Copy button.

Collect configuration values

The OIDC Issuer URL follows this pattern:

https://{your-keycloak-domain}/realms/{realm-name}

For example, with Keycloak at https://auth.example.com and realm orq-prod:

https://auth.example.com/realms/orq-prod

Verify the Provider URL by visiting {issuer-url}/.well-known/openid-configuration in a browser; it should return a JSON discovery document.

Field	Where to Find
Client ID	The Client ID entered in Step 2
Client Secret	Copied from the Credentials tab
Provider URL	`https://{your-keycloak-domain}/realms/{realm-name}`

Assign users

Any user in the realm can sign in by default. To restrict access, configure client-level roles and assign them:

Open the client → Roles tab → create roles as needed
Open Users → select user → Role mappings → assign the client roles

Keycloak user role mappings page showing client roles being assigned to a user.

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.

Select OIDC
Enter the Client ID
Enter the Client Secret
Enter the Provider URL (the Issuer URL from Keycloak)
Enter the organization’s email domain(s) in Allowed domains
Click Activate

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Keycloak OIDC.

Define the SP Entity ID

Choose a unique identifier for the SP Entity ID. It must match exactly in both Keycloak and Orq.ai. We recommend:

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

For example: urn:orq.ai:example-corp.

Write it down; it is needed in multiple steps.

Choose or create a realm

Log in to the Keycloak admin console. From the realm dropdown (top-left), select an existing realm or click Create realm. Note the realm name.

Keycloak may update their admin console interface over time. Refer to Keycloak’s official documentation if any steps differ.

Create a new SAML client

In the chosen realm, navigate to Clients and click Create client.

Keycloak Clients page showing the list of active clients with a Create client button, accessed the same way for SAML client creation.

Configure the General Settings:

Field	Value
Client type	`SAML`
Client ID	The SP Entity ID from Step 1 (e.g., `urn:orq.ai:example-corp`)
Name	`orq.ai` (optional display name)

Click Next.

Keycloak Create SAML client General Settings form showing Client type set to SAML and Client ID set to the SP Entity ID.

Configure login settings

Enter the following:

Field	Value
Valid redirect URIs	`https://my.orq.ai/v2/auth/sso/saml/callback`
Master SAML Processing URL	`https://my.orq.ai/v2/auth/sso/saml/callback`

Click Save.

Keycloak SAML client Login settings form showing Valid redirect URIs and Master SAML Processing URL.

Configure SAML signing

Open the client → Settings tab. Scroll to SAML capabilities and Signature and Encryption sections.Set the following:

Field	Value
Sign assertions	`On`
Sign documents	`On`
Name ID format	`email`

Click Save.

Keycloak SAML client Settings tab showing Sign assertions and Sign documents enabled.

Keycloak SAML client Settings tab showing Name ID format set to email.

Disable client signature requirement

Open the client → Keys tab.Under Signing keys config, set:

Field	Value
Client signature required	`Off`

Under Encryption keys config, confirm:

Field	Value
Encrypt assertions	`Off`

Keycloak SAML client Keys tab showing Client signature required set to Off and Encrypt assertions set to Off.

Client signature required defaults to On in Keycloak: turn it Off. Orq.ai does not sign outbound SAML AuthnRequests, so leaving this on causes Keycloak to reject every login attempt.Encrypt assertions must remain Off. Orq.ai does not decrypt assertions.

Configure SAML attribute mappers

A new Keycloak SAML client only sends the NameID and role list by default, not email, first name, or last name. Add mappers so Orq.ai can populate the user profile.

Open the client → Client scopes tab
Click the dedicated scope row (named {client-id}-dedicated)
Open the Mappers tab inside that scope

Option A (recommended): Add predefined X500 mappers

Click Add predefined mapper
Select these three rows:
- X500 email
- X500 givenName
- X500 surname
Click Add

Keycloak dedicated client scope Mappers tab showing X500 email, givenName, and surname mappers added.

Keycloak mapper detail showing X500 email mapper configured with SAML Attribute Name and NameFormat.

Option B: Configure custom mappers with simple namesClick Configure a new mapper, select User Property, and create three mappers:

Mapper	Property	SAML Attribute Name	NameFormat
`email`	`email`	`email`	`Basic`
`firstName`	`firstName`	`firstName`	`Basic`
`lastName`	`lastName`	`lastName`	`Basic`

Download the realm signing certificate

In the left navigation, click Realm settings
Open the Keys tab → Keys list sub-tab
Find the row where Algorithm = RS256, Type = RSA, Use = SIG
In the Public keys column, click Certificate
Copy the entire base64 value from the modal

Keycloak Realm settings Keys tab showing the RS256 SIG key row with a Certificate button.

Orq.ai accepts the certificate as raw base64 or PEM-wrapped with -----BEGIN CERTIFICATE----- / -----END CERTIFICATE----- markers. Pasting raw base64 directly works.

Collect configuration values

The SAML endpoints follow these patterns:

Field	Pattern
Identity Provider Entity ID	`https://{your-keycloak-domain}/realms/{realm-name}`
Single Sign-On URL	`https://{your-keycloak-domain}/realms/{realm-name}/protocol/saml`

For example with Keycloak at https://auth.example.com and realm orq-prod:

IdP Entity ID: https://auth.example.com/realms/orq-prod
SSO URL: https://auth.example.com/realms/orq-prod/protocol/saml

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.

Select SAML
Enter the Service Provider Entity ID (from Step 1)
Enter the Identity Provider Entity ID
Enter the Single Sign-On URL
Paste the X.509 Certificate copied from Realm settings
Enter the organization’s email domain(s) in Allowed domains
Click Activate

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Keycloak SAML.

Authentik

OIDC
SAML

Create a new provider

Authentik Providers page showing the list of providers with a Create button.

Click Create, select OAuth2/OpenID Provider, and click Next.

Authentik provider type selection showing OAuth2/OpenID Provider highlighted.

Authentik may update their admin interface over time. Refer to Authentik’s official documentation if any steps differ.

Configure provider settings and collect credentials

Enter the following values:

Field	Value
Name	`orq.ai` (or preferred name)
Authorization flow	`default-provider-authorization-implicit-consent`
Client type	`Confidential`
Redirect URIs / Origins	`https://my.orq.ai/v2/auth/sso/oidc/callback` (Strict mode)

Authentik pre-generates the Client ID and Client Secret inside this form. Copy both values now; they are needed to configure Orq.ai in the final step.

Authentik OAuth2/OpenID provider configuration form showing the Client ID, Client Secret, and Redirect URI fields.

Click Finish.

Create an application

Navigate to Applications → Applications and click Create.

Authentik Applications page showing the list of applications with a Create button.

Enter the following:

Field	Value
Name	`orq.ai`
Slug	`orq-ai` (becomes part of the Issuer URL)
Provider	The OAuth2/OpenID provider created in Step 1

Click Create.

Authentik Create application form showing Name, Slug, and Provider fields.

Get the Provider URL

The OIDC Issuer URL follows this pattern:

https://{your-authentik-domain}/application/o/{application-slug}/

For example, with Authentik at https://auth.example.com and slug orq-ai:

https://auth.example.com/application/o/orq-ai/

The trailing slash on the Issuer URL is required. Authentik’s discovery endpoint fails without it.

Assign users

Open the application, go to the Policy / Group / User Bindings tab, and add a binding for the users or groups that should have access.

Authentik application Policy/Group/User Bindings tab showing a binding added for a user group.

If no bindings are configured, every authenticated Authentik user can access the application. If a binding excludes the user, Authentik shows Request has been denied. Unknown error on sign-in.

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.

Select OIDC
Enter the Client ID (copied in Step 2)
Enter the Client Secret (copied in Step 2)
Enter the Provider URL (the Issuer URL from Authentik, with trailing slash)
Enter the organization’s email domain(s) in Allowed domains
Click Activate

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Authentik OIDC.

Define the SP Entity ID

Choose a unique identifier for the SP Entity ID. It must match exactly in both Authentik and Orq.ai. Recommended format:

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

For example: urn:orq.ai:example-corp.

Write it down; it is needed in multiple steps.

Create a new SAML provider

Authentik Providers page listing active providers with a Create button, shown at the start of SAML provider setup.

Click Create, select SAML Provider, and click Next.

Authentik provider type selection showing SAML Provider highlighted.

Authentik may update their admin interface over time. Refer to Authentik’s official documentation if any steps differ.

Configure SAML provider settings

Fill in the main form fields:

Field	Value
Name	`orq.ai` (or preferred name)
Authorization flow	`default-provider-authorization-implicit-consent`
ACS URL	`https://my.orq.ai/v2/auth/sso/saml/callback`
Issuer	`authentik` (default) or a descriptive identifier
Service Provider Binding	`Post`
Audience	The SP Entity ID from Step 1 (e.g., `urn:orq.ai:example-corp`)

Expand Advanced protocol settings and configure:

Field	Value
Signing Certificate	`authentik Self-signed Certificate`
Sign assertions	`On`
Sign responses	`On`
Verification Certificate	Leave empty
Encryption Certificate	Leave empty

Sign assertions must be On. Even with the Signing Certificate pre-populated, Authentik will not sign assertions (and omits <md:KeyDescriptor> from metadata) unless this toggle is enabled. Orq.ai rejects unsigned assertions.

Authentik SAML provider configuration form showing ACS URL, Issuer, Audience, and signing settings.

Click Finish.

Create an application

Navigate to Applications → Applications and click Create.

Authentik Applications page listing active applications with a Create button, shown during SAML application creation.

Enter the following:

Field	Value
Name	`orq.ai`
Slug	`orq-ai-saml` (becomes part of the SSO URL)
Provider	The SAML provider created in Step 2

Click Create.

Authentik Create application form showing Name, Slug, and Provider fields linked to the SAML provider.

Collect the SSO URL and certificate

Open Applications → Providers and click the SAML provider. In the SAML Configuration section:

Copy the EntityID/Issuer: this is the Identity Provider Entity ID
Copy the SSO URL (Redirect): use the Redirect binding URL, not the Post one

The Redirect SSO URL follows this pattern:

https://{your-authentik-domain}/application/saml/{application-slug}/sso/binding/redirect/

Orq.ai issues the SAML AuthnRequest via HTTP-Redirect binding. Using the /binding/post/ endpoint results in Bad Request: The SAML request payload is missing. Always use the Redirect URL.

In the Related objects section, click Download signing certificate to save the PEM file.

Authentik SAML provider overview showing SAML Configuration section with EntityID, SSO URLs, and a Download signing certificate button.

The Download signing certificate button only appears after selecting a Signing Certificate and enabling Sign assertions in Step 3. If not visible, edit the provider and complete the Advanced protocol settings first.

Assign users

Open the application, go to the Policy / Group / User Bindings tab, and add a binding for the users or groups that should have access.

Authentik application Policy/Group/User Bindings tab showing a user group binding added for the SAML application.

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway.

Select SAML
Enter the Service Provider Entity ID (from Step 1)
Enter the Identity Provider Entity ID (the Issuer value from Authentik)
Enter the Single Sign-On URL (the Redirect-binding SSO URL)
Paste the certificate downloaded from Authentik
Enter the organization’s email domain(s) in Allowed domains
Click Activate

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

Test the login

SSO is now configured. Users can sign in at:

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

Orq.ai login page showing the Continue with SSO button after configuring Authentik SAML.

Other providers

OIDC
SAML

Orq.ai works with any standards-compliant OIDC 1.0 identity provider (Auth0, Google Workspace, JumpCloud, OneLogin, Ping Identity, Duo, Rippling, Authelia, Zitadel, and others).What Orq.ai requires from the IdPOrq.ai acts as an OIDC Relying Party using the Authorization Code flow:

Requirement	Value
Flow	Authorization Code (with or without PKCE)
Application type	Web application / Confidential client
Grant type	`authorization_code`
Token endpoint auth method	`client_secret_post` or `client_secret_basic`
Discovery	`{issuer}/.well-known/openid-configuration` must be reachable

In the IdP’s admin interface, register a new web application with:

Field	Value
Application type	Web application (confidential client)
Grant type / Flow	Authorization Code
Redirect URI	`https://my.orq.ai/v2/auth/sso/oidc/callback`
Post-logout redirect URI (optional)	`https://my.orq.ai`
Allowed scopes	`openid`, `email`, `profile`

Grant the IdP’s equivalent of admin consent if required.

Configure required claims

Orq.ai expects the ID token or /userinfo endpoint to return:

Claim	Required?	Description
`sub`	Required	Stable user identifier
`email`	Required	User’s email address
`email_verified`	Recommended	Marks the email as verified
`given_name`	Recommended	First name
`family_name`	Recommended	Last name
`name`	Recommended	Full display name

Most IdPs return these automatically when the profile and email scopes are granted. If the IdP requires manual claim mapping, map user-directory fields to the names above.

Collect configuration values

Field	Where to Find
Client ID	Provided by the IdP after registration
Client Secret	Generated by the IdP; copy immediately
Provider URL	Base URL whose `/.well-known/openid-configuration` returns the discovery document

Verify the Provider URL by visiting {issuer-url}/.well-known/openid-configuration in a browser. It must return a JSON document containing authorization_endpoint, token_endpoint, jwks_uri, and issuer. The issuer field in that JSON must match exactly the URL entered in Orq.ai.

Assign users

Use the IdP’s standard user/group assignment to grant access to the Orq.ai application.

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway:

Select OIDC
Enter the Client ID
Enter the Client Secret
Enter the Provider URL (the Issuer URL from the IdP)
Enter the organization’s email domain(s) in Allowed domains
Click Activate

Configure Single Sign-On panel with OIDC selected for a generic identity provider, showing fields for Client ID, Client Secret, Provider URL, and Allowed domains.

Test the login

Open a private browser window and navigate to https://my.orq.ai. The SSO login button will appear automatically.

Orq.ai login page showing the Continue with SSO button after configuring an OIDC provider.

Orq.ai works with any standards-compliant SAML 2.0 identity provider.What Orq.ai requires from the IdP

Requirement	Value
SP-initiated SSO	Required
AuthnRequest binding (SP → IdP)	HTTP-Redirect
Response binding (IdP → SP)	HTTP-POST to the ACS URL
NameID format	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
Assertion signing	Required: RSA-SHA256
AuthnRequest signing	Not required
Assertion encryption	Not supported; leave disabled

Define the SP Entity ID

Choose a unique identifier that must match exactly in both the IdP and Orq.ai. We recommend:

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

In the IdP’s admin interface, create a SAML 2.0 application with:

IdP Field (common names)	Value
Audience / SP Entity ID	The SP Entity ID from Step 1
ACS URL / Reply URL	`https://my.orq.ai/v2/auth/sso/saml/callback`
NameID format	`EmailAddress`
NameID source attribute	The user’s email address

Configure signing

Setting	Value
Sign assertion	On (required)
Signature algorithm	`RSA-SHA256`
Require signed AuthnRequest	Off
Encrypt assertion	Off

Configure attribute mappings

Orq.ai accepts a wide range of attribute name variants:

Canonical	Also accepted
`email`	`emailAddress`, `mail`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, `urn:oid:0.9.2342.19200300.100.1.3`
`firstName`	`givenName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`, `urn:oid:2.5.4.42`
`lastName`	`familyName`, `surname`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`, `urn:oid:2.5.4.4`

Many IdPs do not send name and email attributes by default. After registering the application, explicitly add attribute mappers / claim rules / attribute statements in the IdP before the assertion will contain anything Orq.ai can read.

Collect configuration values

orq.ai Field	Common IdP Label(s)
Identity Provider Entity ID	`Issuer`, `IdP Entity ID`, `Microsoft Entra Identifier`, `entityID`
Single Sign-On URL	`SSO URL`, `Sign-on URL`, `Login URL`, `SingleSignOnService Location`
X.509 Certificate	`Signing Certificate`, `Token Signing Certificate`, `Certificate (Base64)`

If the IdP provides a SAML metadata XML file or URL, the IdP Entity ID, SSO URL, and certificate are all embedded inside. Use the HTTP-Redirect binding URL for the SSO URL.

Configure in Orq.ai

Navigate to Settings → Auth in the AI Gateway:

Select SAML
Enter the Service Provider Entity ID
Enter the Identity Provider Entity ID
Enter the Single Sign-On URL (HTTP-Redirect endpoint)
Paste the X.509 Certificate
Enter the organization’s email domain(s) in Allowed domains
Click Activate

Configure Single Sign-On panel with SAML selected for a generic identity provider, showing fields for Service Provider Entity ID, Identity Provider Entity ID, Single Sign-On URL, X.509 Certificate, and Allowed domains.

Test the login

Open a private browser window and navigate to https://my.orq.ai. The SSO login button will appear automatically.

Orq.ai login page showing the Continue with SSO button after configuring a SAML provider.

Edit a connection

Click the menu on the active SSO connection
Click Edit
Update the desired fields
Click Save Changes

Orq.ai SSO configuration page showing the three-dot menu open on an active connection with an Edit option.

To switch protocols (OIDC to SAML or vice versa), Orq.ai confirms the switch and presents an empty form; the two configurations differ entirely. The active connection remains unchanged until Save Changes is clicked. Cancel to preserve the current configuration.

Orq.ai SSO edit dialog showing a confirmation prompt when switching from OIDC to SAML protocol.

The Certificate and Client Secret fields are blank in the edit form; they update only when a new value is provided and Save Changes is clicked.

Testing

Before rolling out to the entire organization:

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

Users sign in at:

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

Orq.ai login page showing a Continue with SSO provider button that loads when an active SSO connection is configured.

Troubleshooting

Redirect URI mismatch

Error: “redirect_uri_mismatch” or “Invalid redirect URI”Solution: Verify the callback URL in the 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 the IdP and Orq.ai configuration. It is case-sensitive.

Invalid client secret (OIDC)

Error: “invalid_client” or “unauthorized_client”Solution: Regenerate the client secret in the IdP and update it in Orq.ai. Copy the secret immediately after creation.

User not assigned

Symptom: User cannot 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
Keycloak: Open the client → Roles tab, create roles, and assign them to the user under Role mappings
Authentik: Open the application → Policy / Group / User Bindings and add a binding

Certificate expired (SAML)

Symptom: SAML authentication suddenly stops workingSolution:

Download a new certificate from the IdP
Update the certificate in Orq.ai (Settings → Auth → Edit in the AI Gateway)
Click Save Changes

Email domain not allowed

Error: “Email domain not allowed”Solution: Add the user’s email domain to Allowed domains in the 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 the app registration
Verify User.Read is present
Click “Grant admin consent” if needed

Invalid signature or login bounces back (Keycloak SAML)

Missing name or email in Orq.ai profile (Keycloak/Authentik SAML)

Symptom: User signs in but first name, last name, or email are missing in Orq.aiSolution: The SAML client has no attribute mappers. For Keycloak, add X500 predefined mappers to the dedicated client scope. For Authentik, ensure Sign assertions is On in the provider’s Advanced protocol settings.

SAML request payload missing (Authentik)

Error: “Bad Request: The SAML request payload is missing”Solution: The SSO URL points at /binding/post/. Switch to the /binding/redirect/ URL; Orq.ai sends AuthnRequests via HTTP-Redirect.

HTTP issuer rejected

Error: Issuer URL rejectedSolution: Orq.ai rejects http:// issuers in production. The identity provider must be served over HTTPS.

Need Help?

Contact support@orq.ai with:

Workspace key
Identity provider and protocol (e.g., “Keycloak SAML”)
Error message or screenshot

​Choose a Protocol

​Configure SSO in Orq.ai

​Navigate to Auth settings

​Connect a provider

​Edit a connection

​Testing

​Troubleshooting

​Need Help?

Choose a Protocol

Configure SSO in Orq.ai

Navigate to Auth settings

Connect a provider

Edit a connection

Testing

Troubleshooting

Need Help?