---
description: Connect your company's identity provider to Actian AI Analyst over SAML or OIDC, prove a sign-in works, offer SSO by email domain, require SSO, and provision members with JIT membership or SCIM.
---

# Enterprise SSO (SAML and OIDC)

Enterprise SSO lets people sign in to your organization through your company's identity provider (IdP), such as Okta, Microsoft Entra ID or Cloudflare Access. Each organization can have one Enterprise SSO connection, using either OIDC or SAML.

!!! info "Availability"
    - **Who can do this:** members with the **Manage organization** capability (for the organization). The **Administrator** preset includes it.
    - **Plan:** included only in plans that enable Enterprise SSO.
    - **Deployment:** Actian SaaS and self-managed deployments. Some features work differently on Keycloak deployments (see [Keycloak deployments](#keycloak-deployments)).

Adding a connection doesn't change how anyone signs in yet. Password, Google and Microsoft sign-in keep working until you turn on [Require SSO](#require-sso). The recommended order is:

1. [Set up the connection](#set-up-enterprise-sso) and prove that a sign-in works.
2. Optionally, [add email domains](#email-domains) so people on your domains are offered SSO when they sign in.
3. Choose [how people become members](#provisioning).
4. When you're confident, [turn on Require SSO](#require-sso).

On this page, **Keycloak deployments** means self-managed deployments where people sign in through Keycloak. This is the default for self-managed deployments, and it is always the case on air-gapped deployments. Actian SaaS, and self-managed deployments that don't sign people in through Keycloak, have every feature described here. If you're not sure which applies to you, ask your operator.

## Before you start

You need:

- the **Manage organization** capability in AI Analyst
- permission to create an application (some providers call it a client, app or integration) in your identity provider
- a test account in your identity provider that is assigned to the new application

## Set up Enterprise SSO

Go to **Settings** → **Administration** → **Security**. In the **Enterprise SSO** section, click **Set up SSO**. The **Set up Enterprise SSO** wizard opens with five steps: **Protocol**, **Register**, **Provider details**, **Verify** and **Provisioning**.

<!-- screenshot: sign-in-sso-sso-wizard-protocol -->

You can leave at any time with **Exit wizard** and go back with **Back**. The wizard remembers where you are from what you've saved, so reloading the page, or returning from your identity provider, brings you back to the right step. **Verify** becomes available once you've saved provider details, and **Provisioning** once a sign-in is verified.

### Step 1: Choose a protocol

Choose the protocol your identity provider uses, then click **Continue**. Both are supported. If your provider offers a choice, pick OIDC.

| Protocol | What you'll paste later | Examples |
| --- | --- | --- |
| **OIDC** (Modern) | A discovery URL and client credentials | Okta, Microsoft Entra ID, Cloudflare Access, Google Workspace |
| **SAML** (Legacy) | A metadata URL | Shibboleth, AD FS, PingFederate, and older Okta or Entra ID apps |

### Step 2: Register AI Analyst in your identity provider

The wizard shows the values your identity provider needs. Create the application in your identity provider and copy each value into it with its **Copy** button:

| Value | OIDC | SAML |
| --- | --- | --- |
| **Application name** | `Actian AI Analyst` | `Actian AI Analyst` |
| **Redirect URI** | Yes | — |
| **Scopes** | `openid profile email` | — |
| **ACS URL** | — | Yes |
| **Entity ID** | — | Yes |

Always copy the **Redirect URI**, **ACS URL** and **Entity ID** from the wizard. They are specific to your organization, so don't build them by hand.

Assign your test account (and anyone else who should sign in) to the application in your identity provider. Then click **I've registered it**.

### Step 3: Paste your provider's details

Enter the details from the application you just created, then click **Save and continue**:

- **OIDC:** **Discovery URL** (some providers call it the configuration endpoint; it usually ends in `/.well-known/openid-configuration`), **Client ID** and **Client secret**. All three are required.
- **SAML:** **Metadata URL**, the URL of the metadata document from your identity provider.

When you save, AI Analyst creates the connection. If saving fails, you see "We couldn't create the Enterprise SSO connection. Please try again."

Once a connection exists, this step also shows the **Email domains** panel. You can add domains now or later. Pending domains don't hold up the rest of the setup.

### Step 4: Verify that sign-in works

Before you can require SSO, you prove that a real sign-in through your identity provider works.

1. Click **Test SSO login**. You're sent to your identity provider in the same browser tab.
2. Sign in with an account that is assigned to the application.
3. You're returned to the wizard. When the test passes, you see "SSO sign-in verified." and **Verified as** followed by the email address you signed in with.

The test login:

- doesn't add that account to **Members**, change any access settings or replace your own session. It's only a test.
- does create a sign-in account for that identity on your organization's SSO connection.
- must be finished within 10 minutes, by the same administrator who started it.
- is rate limited. If you start many tests in a short time, you see "Too many tests. Wait a few minutes and try again."

If the test fails, the message tells you what went wrong. See [Troubleshooting](#troubleshooting). Fix the problem, then click **Retry test**.

On Keycloak deployments there is no test login. See [Keycloak deployments](#keycloak-deployments).

### Step 5: Provisioning and enforcement

The last step brings together the settings that decide who gets in:

- **Require SSO**: whether Enterprise SSO is the only way to sign in. See [Require SSO](#require-sso).
- **Automatically add members on first sign in**, **Capabilities to give new users** and, where available, **SCIM provisioning**. See [Provisioning](#provisioning).

These settings save as soon as you change them. Click **Finish** to close the wizard. You can change all of them later on the **Security** page.

## Check the connection status

After setup, the **Enterprise SSO** section of **Settings** → **Administration** → **Security** shows:

- **Protocol**: OIDC or SAML
- **Identity provider**: your identity provider's host name
- a verification badge, and **Verified as** with the email address that proved the connection

<!-- screenshot: sign-in-sso-sso-status -->

| Badge | Meaning | What to do |
| --- | --- | --- |
| **Verified** | A sign-in through the current connection details has been proven. | Nothing. |
| **Not verified** | No sign-in has been proven yet. | Click **Re-verify** and run a test login. |
| **Needs re-verifying** | The provider details changed after the last successful test. | Click **Re-verify** and run a test login. |
| **Last test failed** | The most recent test login didn't succeed. | Read the error, fix it, then click **Re-verify**. |

**Change provider details** reopens the wizard. **Re-verify** opens the **Verify** step. It isn't shown while the connection is verified.

### Change provider details

Change the details when you rotate a certificate or client secret, or move to a new metadata or discovery URL:

1. Click **Change provider details**.
2. On **Provider details**, enter the new values and click **Save and continue**.
3. Run **Test SSO login** again.

Saving new details marks the connection **Needs re-verifying**. If **Require SSO** is on, it stays on, so saving new provider details doesn't turn password, Google or Microsoft sign-in back on.

### Switch between SAML and OIDC

You can't switch an existing connection to the other protocol. If you try, saving fails with "We couldn't create the Enterprise SSO connection. Please try again." To change protocol, [remove the connection](#remove-the-connection) and set it up again with the new protocol.

## Email domains

Email domains let AI Analyst recognize your people at sign-in. When someone enters an email address on one of your verified domains, the sign-in page shows a **Continue with … SSO** button with your organization's name, and notes that your organization signs in with single sign-on for that email domain.

An email domain is an offer, not a requirement. Other sign-in methods stay available under **Other ways to sign in**. Only [Require SSO](#require-sso) turns them off.

!!! info "Availability"
    - **Who can do this:** members with the **Manage organization** capability (for the organization).
    - **Plan:** included only in plans that enable Enterprise SSO.
    - **Deployment:** Actian SaaS and self-managed deployments that don't sign people in through Keycloak. Not available on Keycloak deployments.

You can add domains only after the Enterprise SSO connection exists. They appear in the **Enterprise SSO** section of the **Security** page and on the wizard's **Provider details** step.

<!-- screenshot: sign-in-sso-sso-email-domains -->

### Add and verify a domain

1. Under **Email domains**, enter your domain (for example `acme.com`) and click **Add domain**.
2. The domain appears under **Awaiting DNS proof**, with a **TXT host** and **TXT value**. It isn't offered at sign-in yet.
3. In your DNS provider, publish a TXT record using that host and value.
4. Back in AI Analyst, click **Run DNS check**.

When the record is found and matches, you see "Domain verified. People with this email domain are now offered your identity provider at sign-in." The domain moves to **Offered at sign-in**.

AI Analyst checks the record only when you click **Run DNS check**. Nothing verifies the domain in the background. If the record can't be found yet, publish it, then run the check again.

Things to know:

- **Exact match only.** Verifying `acme.com` doesn't cover `mail.acme.com`. Add and verify each domain separately.
- **One organization per domain.** A verified domain can belong to only one organization.
- **Refused domains.** Public email providers such as Gmail or Outlook, known disposable email domains, shared hosting domains, and domains you've already added can't be added.
- **Members.** Verified domains also decide who you can add ahead of time on **Members**. People on a verified domain are added straight away and get access the first time they sign in with SSO, without an invitation email. See [Provisioning](#provisioning).

### Remove a domain

Click **Remove** next to the domain. Removing a domain under **Offered at sign-in** stops the sign-in offer immediately. It doesn't change Require SSO. Removing a domain under **Awaiting DNS proof** deletes it.

## Require SSO

When **Require SSO** is on, Enterprise SSO is the only way to sign in to this organization. Password, Google and Microsoft sign-in are turned off for it. It is off by default.

Require SSO applies to this organization only. If someone also belongs to another organization, their password, Google or Microsoft sign-in keeps working there.

### Turn on Require SSO

You can turn on Require SSO only when:

- the Enterprise SSO connection exists, and
- a sign-in through its current details has been verified, and
- on Keycloak deployments, the organization has no [Sign-up domains](security.md#sign-up-domains).

Until a sign-in is verified, the switch is unavailable and reads "Test an SSO login first. Require SSO stays off until a sign-in is proven."

1. Go to **Settings** → **Administration** → **Security**, or the wizard's **Provisioning** step.
2. Turn on **Require SSO**.
3. Read the **Make SSO the only way in?** dialog: "Password, Google, and Microsoft sign-in stop working for this organization immediately. Anyone without an account in your identity provider loses access until you add them there." It also reminds you which email address proved SSO works.
4. Click **Require SSO**.

The change applies immediately. There is no **Save** button for this switch.

!!! warning
    Before you turn on Require SSO, make sure everyone who needs access, including other administrators, has an account in your identity provider and is assigned to the application.

### Turn off Require SSO

Switch **Require SSO** off. No confirmation is needed, and password, Google and Microsoft sign-in work again for the organization. Turning Require SSO off is always possible, even if your plan no longer includes Enterprise SSO.

### What changes to the connection do

Changing provider details leaves Require SSO on. Removing the connection turns it off first, so the organization is never left without a way to sign in.

## Provisioning

**Provisioning** decides how people who sign in through Enterprise SSO become members of your organization. Someone who signs in through SSO gets access in one of these ways:

| How | What happens |
| --- | --- |
| **Automatically add members on first sign in** is on | They become a member the first time they sign in through Enterprise SSO. |
| An administrator added them ahead of time on **Members** | They get the access they were given the first time they sign in with SSO. |
| An administrator invited them | They join with the invitation's capabilities. |

Anyone else who signs in through your identity provider sees **Ask your administrator for access**: "You signed in through your organization's identity provider, but you don't have access to it in Actian AI Analyst yet. Ask an administrator to add you, then sign in again."

### Automatically add members on first sign in

This switch is also called JIT (just-in-time) membership. When it is on, people become members the first time they sign in through Enterprise SSO. It is off by default on a new connection. It saves as soon as you change it.

While **SCIM provisioning** is on, JIT membership is always on and its switch is unavailable.

### Capabilities to give new users

**Capabilities to give new users** is the Default preset for people who join through JIT membership. It is applied once, the first time a new member signs in, when no invitation has already set their capabilities. Changing it doesn't affect existing members. You can change it only while JIT membership is on.

If your identity provider assigns a preset to a person, that preset takes precedence over this default. When **SCIM provisioning** is on, **Members** shows a banner saying that changes made there are re-applied at the member's next sign-in, so check it before you edit someone's access.

| Preset | What it gives |
| --- | --- |
| **Viewer** (default) | **Chat** in the organization's default Workspace |
| **Editor** | **Edit** in the organization's default Workspace (Edit includes Chat) |
| **Administrator** | **Manage members and access**, **Manage billing**, **Manage organization** and **Manage inference** for the organization, plus **Manage members** and **Edit** in the default Workspace |
| **Billing contact** | **Manage billing** only |

Presets give access to the organization's default Workspace only. To give access to other Workspaces, change the member's access on [Members](members.md) after they join.

### SCIM provisioning

With **SCIM provisioning**, your identity provider creates, blocks and deletes people's sign-in accounts for your organization.

!!! info "Availability"
    - **Who can do this:** members with the **Manage organization** capability (for the organization).
    - **Plan:** included only in plans that enable Enterprise SSO.
    - **Deployment:** Actian SaaS and self-managed deployments that don't sign people in through Keycloak. Not available on Keycloak deployments.

To set it up:

1. In the **Provisioning** section, turn on **SCIM provisioning**. This also turns on JIT membership and keeps it on.
2. Copy the **SCIM endpoint** into your identity provider's SCIM settings.
3. Click **Generate token**, then copy the **SCIM token** into your identity provider. The token is shown only once: "Copy this token now. It will not be shown again."

SCIM manages sign-in accounts, not membership. People appear on **Members** only after their first Enterprise SSO sign-in.

### Seats

People who join through JIT membership or SCIM are admitted even when all of your Seats are taken. People added ahead of time on **Members** take up a Seat until their first sign-in.

### Removing access

To remove someone's access, set them to **No access** on [Members](members.md). This releases their Seat and revokes all of their login sessions, which signs them out of every organization they belong to. To stop them signing in through SSO at all, also remove or block them in your identity provider.

## Remove the connection

Removing the connection stops Enterprise SSO for your organization immediately.

1. Go to **Settings** → **Administration** → **Security**.
2. In **Danger zone**, click **Remove connection**.
3. In the **Remove this connection?** dialog, click **Remove Enterprise SSO**.

When you remove the connection, AI Analyst:

1. turns **Require SSO** off
2. deletes the connection and its verification
3. removes all of the organization's email domains, both pending and verified

Members keep their membership and capabilities. Members who also have their own password, Google or Microsoft sign-in can keep using it. People who have only ever signed in through Enterprise SSO have no other sign-in method for that account, so they can't sign in until they are given access another way.

!!! note
    Removing the connection needs a plan that includes Enterprise SSO. On Keycloak deployments, Sign-up domains aren't affected.

## If your plan no longer includes Enterprise SSO

- If **Require SSO** is on, the **Enterprise SSO** section stays visible so that you can turn Require SSO off. You can't change or remove the connection, or change other SSO settings.
- If **Require SSO** is off, the **Enterprise SSO** section is hidden.

## People who sign in through Enterprise SSO

- **One organization.** An Enterprise SSO sign-in belongs to exactly one organization. It can't be used to create or join another organization.
- **MFA.** Their identity provider handles multi-factor authentication. **Require MFA** doesn't apply to them, and on Actian SaaS the **Multi-factor authentication** section of their personal Security page is hidden. On Actian SaaS and other deployments that don't use Keycloak, the **MFA** column on **Members** shows **MFA via IdP** for them. On Keycloak deployments it shows **MFA on** or **MFA off**. See [Security](security.md#multi-factor-authentication).

## Keycloak deployments

On Keycloak deployments, Enterprise SSO works differently:

| Feature | On Keycloak deployments |
| --- | --- |
| Verification | There is no **Test SSO login**. The **Verify** step asks you to sign out, then sign in to the organization once through your identity provider. The first sign-in by any member through the identity provider after the details last changed counts as the verification. **Re-verify** isn't shown. |
| Require SSO switch | Until a sign-in is verified, the switch reads "Sign in once through your identity provider first. Require SSO stays off until a sign-in through it is proven." It can't be turned on while the organization has Sign-up domains ("Remove every Sign-up domain before turning on Require SSO."). |
| Require SSO enforcement | AI Analyst enforces it on every request. Anyone in the organization whose session didn't come through its identity provider sees **Sign in with single sign-on**: "This organization requires single sign-on. Sign out, then sign in again through your organization's identity provider." They click **Sign out** and sign in through the identity provider. |
| Email domains | Not available. |
| SCIM provisioning | Not available. |
| JIT membership | Always on, even though the switch is shown. Everyone who signs in through the identity provider becomes a member. They get the Default preset unless an invitation already set their capabilities. |
| Removing SSO members | Members who sign in through SSO can't be removed on **Members**. Set them to **No access**, or remove them in your identity provider. |

## Troubleshooting

| Message or symptom | Likely cause | What to do |
| --- | --- | --- |
| "Your identity provider refused the sign-in. Check that your account is assigned to the application." | The account you signed in with isn't assigned to the application in your identity provider. | Assign the account to the application, then click **Retry test**. |
| "The sign-in was cancelled before it finished. Test again when you're ready." | The sign-in was cancelled at the identity provider. Some identity providers also report an unassigned account this way. | Check that the account is assigned to the application, then click **Retry test**. |
| "That sign-in was not on this organization's SSO connection. Check the metadata you pasted." | The provider details point at a different application or connection. | Click **Change provider details**, paste the details from the application you registered for AI Analyst, and test again. |
| "Please try signing in again. The previous test has expired." | The test took longer than 10 minutes, couldn't be found, or was started by a different administrator. | Click **Retry test** and finish the sign-in within 10 minutes. |
| "Too many tests. Wait a few minutes and try again." | Too many test logins were started in a short time. | Wait a few minutes, then test again. |
| "Our SSO configuration rejected the sign-in. Please contact support." | A problem on the AI Analyst side, not in your identity provider. | Contact Actian support. |
| "We couldn't verify that sign-in. Please try again." | A general or temporary error. | Test again. If it keeps happening, contact Actian support. |
| "We couldn't create the Enterprise SSO connection. Please try again." | The details couldn't be saved, or you chose a different protocol from the existing connection. | Check the details and try again. To change protocol, [remove the connection](#remove-the-connection) first. |
| "The DNS TXT record wasn't found. Publish it, then run the check again." | The TXT record isn't published yet, doesn't match, or can't be read from DNS. | Check the **TXT host** and **TXT value** in your DNS provider, wait for the change to take effect, then click **Run DNS check** again. |
| "Another organization already uses this domain for SSO, so it can't be verified here." | The domain is already verified by another organization. | The domain stays pending. It can be verified here only after the other organization removes the domain or its SSO connection. |
| The **Require SSO** switch is unavailable. | No sign-in through the current details has been verified. | Run **Test SSO login** (or, on Keycloak deployments, sign in once through your identity provider). |
| A person sees **Ask your administrator for access** after signing in through SSO. | JIT membership is off and they weren't added on **Members** or invited. | Turn on **Automatically add members on first sign in**, or add them on [Members](members.md). |