> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Enterprise SSO authentication
> Configure enterprise Single Sign-On for Orq.ai using Okta or Microsoft Entra ID. Supports OIDC and SAML protocols for secure authentication.
Feature available with the [Enterprise Plan](https://orq.ai/solutions/enterprise)
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
Sign in to your **Okta Admin Console** and navigate to **Applications → Applications**.
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
```
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.
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
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`).
Navigate to **AI Studio** → **Organization** → **Auth**.
Enter the credentials you collected from Okta:
1. Select **OIDC** (selected by default)
2. Enter your **Client ID**
3. Enter your **Client Secret**
4. Enter your **Provider URL**
5. Enter your organization's email domain(s) in **Allowed domains** (e.g., `orq.ai`)
6. Click **Activate**
Your SSO is now configured! Users can sign in at:
```
https://my.orq.ai/{your-workspace-key}/login
```
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.
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**.
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**.
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.
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) |
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.
Navigate to **AI Studio** → **Organization** → **Auth**.
Enter the credentials you collected from Okta:
1. Select **SAML**
2. Enter your **Service Provider Entity ID** (from Step 1)
3. Enter your **Identity Provider Entity ID** (Issuer from Okta)
4. Enter your **Single Sign-On URL** (Sign on URL from Okta)
5. 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
6. Enter your organization's email domain(s) in **Allowed domains** (e.g., `orq.ai`)
7. Click **Activate**
Your SSO is now configured! Users can sign in at:
```
https://my.orq.ai/{your-workspace-key}/login
```
Sign in to the [Azure portal](https://entra.microsoft.com) and navigate to **Microsoft Entra ID → App registrations**.
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**.
**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.
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.
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.
Navigate to **AI Studio** → **Organization** → **Auth**.
Enter the credentials you collected from Azure:
1. Select **OIDC** (selected by default)
2. Enter your **Client ID**
3. Enter your **Client Secret**
4. Enter your **Provider URL**
5. Enter your organization's email domain(s) in **Allowed domains** (e.g., `acme.com`)
6. Click **Activate**
Your SSO is now configured! Users can sign in at:
```
https://my.orq.ai/{your-workspace-key}/login
```
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.
In the [Azure portal](https://entra.microsoft.com), 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**.
In the application, go to **Single sign-on** and select **SAML**.
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**.
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.
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.
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.
Navigate to **AI Studio** → **Organization** → **Auth**.
Enter the credentials you collected from Azure:
1. Select **SAML**
2. Enter your **Service Provider Entity ID** (from Step 1)
3. Enter your **Identity Provider Entity ID** (Microsoft Entra Identifier from Azure)
4. Enter your **Single Sign-On URL** (Login URL from Azure)
5. 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
6. Enter your organization's email domain(s) in **Allowed domains** (e.g., `orq.ai`)
7. Click **Activate**
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:
1. Test the configuration with a single user
2. Verify the user is created automatically in Orq.ai (if auto-provisioning is enabled)
3. Check that the user's profile information (name, email) is correct
## Troubleshooting
**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
**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.
**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.
**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
**Symptom:** SAML authentication suddenly stops working
**Solution:**
1. Download new certificate from your IdP
2. Update certificate in Orq.ai (AI Studio → Organization → Auth → Edit)
3. Click **Save Changes**
**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`).
**Symptom:** Authentication succeeds but user has no email
**Solution:** Orq.ai automatically requests the `User.Read` Microsoft Graph scope. Verify this permission is granted:
1. Go to API permissions in your app registration
2. Verify `User.Read` is present
3. Click "Grant admin consent" if needed
### Need Help?
Contact [support@orq.ai](mailto:support@orq.ai) with:
* Your workspace key
* Identity provider and protocol (e.g., "Okta SAML")
* Error message or screenshot