Enable SSO with OpenID Connect (OIDC)

Use this guide to enable Single Sign-On (SSO) to the Vectara SaaS deployment with any OpenID Connect (OIDC) identity provider, including Okta, Microsoft Entra ID (Azure AD), Google Workspace, Ping Identity, OneLogin, and Keycloak. The setup is the same for every provider: you register an OIDC application with your provider, share standard OIDC parameters with Vectara, register the callback URL that Vectara returns to you, tell Vectara which email domains route to the provider, and agree on how your provider's groups map to Vectara roles. Vectara implements the mapping on your behalf, so you do not write or maintain any mapping code.

You can connect more than one provider to the same Vectara account. For example, you can use Okta for external partners and Microsoft Entra ID for internal employees at the same time. Vectara routes each user to the right provider based on their email domain. Repeat the steps in this guide once per provider.

Overview

Setting up SSO involves a one-time setup phase and the runtime login flow.

Setup process (one-time, per provider)

1. Create an OIDC application with your identity provider, using the authorization code flow.
2. Share OIDC parameters with Vectara: client ID, client secret, issuer URL, requested scopes, and the email domains that route to this provider.
3. Register the callback URL that Vectara returns to you as an allowed redirect URI in your provider's application.
4. Agree on group mapping so Vectara can map your provider's groups to Vectara account and role permissions.

User login process (runtime)

1. Enter email - A user enters their email address on the Vectara Console sign-in page.
2. Provider discovery - Vectara matches the email domain to your configured provider and forwards the user to it.
3. Authenticate - The user signs in with your identity provider.
4. Token exchange - Your provider returns the user's identity, including the sub, email, and group claims.
5. Permission mapping - Vectara maps the claims to the user's account and role permissions.
6. Console access - The user enters the Console with the permissions their groups grant.

How Vectara brokers SSO

Vectara brokers OIDC SSO at a single callback URL. Your provider trusts that URL and never connects into your own network or infrastructure. Users do not pick a provider on the sign-in page. They enter their email address, and Vectara forwards them to the provider configured for their email domain. After a user authenticates, Vectara reads standard OIDC claims and a group claim from the ID token and resolves the user's Vectara account and roles from those claims. Account resolution is provider-agnostic: Vectara keys on the stable user identifier and the group claims, not on which provider authenticated. This is why a single Vectara account can use multiple providers at the same time.

note

This guide covers SSO for human users signing in to the Vectara Console. Machine-to-machine API access uses API keys or OAuth 2.0 client credentials and is configured separately. See Authentication methods.

Prerequisites

• Administrative access to your identity provider, with permission to create an OIDC application and assign users or groups to it.
• A secure channel agreed with Vectara to share the client secret. Do not send the client secret over email or chat.
• Your Vectara account ID (called customer_id in the API, a positive integer, for example 12345). Vectara provides this if you do not have it.
• The email domains your users sign in with (for example, acme.com), so Vectara can route them to this provider.
• The list of groups in your provider that should have access, and the access level (Admin or Developer) each group should receive.

What you provide to Vectara

Share the following from your provider's application. Send the client secret only through the agreed secure channel.

Parameter	Example value	Notes
Client ID	0oa1abcdEFGH2I3JK4l6	The OIDC application's client identifier
Client secret	******	Send through a secure channel, never by email or chat
Issuer URL	https://your-org.okta.com/oauth2/default	The provider's OIDC issuer. Vectara reads its discovery document at <issuer-url>/.well-known/openid-configuration to find all endpoints
Requested scopes	openid profile email groups	openid is required. Include email and a scope or claim that returns the user's groups
Group claim name	groups	The claim in the ID token that contains the user's groups. Confirm the exact name with your provider
Email domains	acme.com, partners.acme.com	The email domains that route to this provider. Used to forward users to the right provider after they enter their email

If you operate more than one provider, send one set of these parameters per provider, each with its own email domains.

What Vectara provides to you

• A callback (redirect) URL for your provider's application. It follows this pattern, where the domain is the Vectara-hosted identity domain for your account and <provider-id> is a short identifier Vectara assigns to your connection (for example, okta or entra):

  https://<vectara-auth-domain>/self-service/methods/oidc/callback/<provider-id>

  Vectara sends you the exact callback URL for your account and connection. Register it exactly as provided. Your provider only needs this URL added to its list of allowed redirect URIs.

• The completed mapping from your provider's groups to Vectara account and roles, implemented and maintained by Vectara.

caution

Use the exact callback URL Vectara sends you. Do not assume the domain or the provider ID. If the redirect URI registered in your provider does not match the string Vectara configured, the login fails with a redirect URI mismatch error.

Vectara permission model

Through SSO you grant each group an access level on a Vectara account. The two access levels are:

• Admin: full administrative access to the account, including managing users, corpora, and agents. Maps to the administrator API role.
• Developer: build and operate applications, including managing corpora and developing agents. Maps to the relevant scoped roles, such as corpus_developer and agent_developer.

Vectara maps each access level to the exact API, corpus, and agent roles that back it. Confirm the role set with Vectara when you fill out the worksheet, and see Role-based access control for the full list of roles and what each one grants.

A user can hold an access level on one or more accounts. Each group you map resolves to a specific account ID and access level.

How your groups drive permissions

Vectara reads two standard claims and one group claim from the ID token:

• sub: the stable, unique user identifier. Vectara uses this as the user's identity and does not change it if the user's email changes.
• email: the user's email address, used as the login and display identifier.
• A group claim (typically groups): an array of strings. Each string encodes which Vectara account and role the user receives.

Vectara turns the group strings into account and role grants. The exact group name format is something you and Vectara agree on so it fits the groups you already manage in your provider. A common convention encodes the access level and the Vectara account ID in the group name:

Acme-Vectara-<ACCESS_LEVEL>-<ACCOUNT_ID>

For example, with account ID 12345:

Provider group	Vectara account	Access level
Acme-Vectara-admin-12345	12345	Admin
Acme-Vectara-developer-12345	12345	Developer

You do not have to adopt this exact format. If you already organize access with existing groups, send Vectara the group names and the account and access level each one should grant, and Vectara writes the mapping to match. Groups that do not match the agreed format are ignored, so unrelated groups in the same claim are safe.

Minimum claims

The ID token must include:

• sub
• email
• The agreed group claim, with at least one group that maps to a Vectara role

If a user authenticates successfully but has no group that maps to a Vectara role, the user is authenticated but has no Console access until a mapped group is assigned.

Group mapping worksheet

Provide this as a document or spreadsheet through your secure channel. Complete one worksheet per provider.

A) Connection details

• Connection name (for your reference, for example Acme Okta): __________
• Group claim name: __________ (for example, groups)
• Email domains that route to this provider: __________ (for example, acme.com, partners.acme.com)

Vectara assigns the provider ID used in the callback path and includes it in the callback URL it returns to you. You do not need to choose it.

B) Group-to-access-level mapping

Provider group	Vectara account ID	Access level
Acme-Vectara-admin-12345	12345	Admin
Acme-Vectara-developer-12345	12345	Developer
__________	__________	Admin / Developer

Configure your identity provider

These steps are the same for every OIDC provider. The labels differ by provider, so use the provider-specific notes that follow for exact menu names.

1. Create an OIDC application using the authorization code grant type.
2. Set the application type to a web or confidential client, so it can hold a client secret.
3. Add the Vectara-provided callback URL to the application's allowed redirect (sign-in redirect) URIs, exactly as provided.
4. Request the scopes openid, profile, email, and the scope or claim that returns the user's groups.
5. Configure the application to include the user's groups in the ID token under the agreed group claim name.
6. Assign the users and groups that should have access to the application.
7. Copy the client ID, client secret, and issuer URL, and send them to Vectara with the completed worksheet.

Okta

1. In the Okta Admin Console, go to Applications > Applications > Create App Integration.
2. Choose OIDC - OpenID Connect, then Web Application.
3. Under Sign-in redirect URIs, add the Vectara-provided callback URL.
4. Under Assignments, assign the relevant users or groups.
5. To return groups, add a groups claim to the ID token under Sign On > OpenID Connect ID Token, and set a filter that matches the groups you map to Vectara roles.
6. Copy the Client ID, Client secret, and your Issuer URL (under Security > API > Authorization Servers) and send them to Vectara.

Microsoft Entra ID (Azure AD)

1. In the Microsoft Entra admin center, go to App registrations > New registration.
2. Under Redirect URI, select Web and enter the Vectara-provided callback URL.
3. Under Certificates & secrets, create a New client secret and copy its value immediately.
4. Under Token configuration, add a groups claim and choose which groups to emit (for example, Groups assigned to the application).
5. Under API permissions, ensure openid, profile, and email are granted.
6. Send Vectara the Application (client) ID, the client secret, and the issuer URL https://login.microsoftonline.com/<tenant-id>/v2.0.

note

Microsoft Entra ID can emit group object IDs (GUIDs) rather than group display names in the groups claim, depending on your configuration. Tell Vectara which form your tokens use so the mapping matches. If you use group IDs, include the ID and the intended account and role for each in the worksheet.

Other OIDC providers

For Google Workspace, Ping Identity, OneLogin, Keycloak, or another OIDC provider, follow the same pattern: create an authorization code web application, register the Vectara callback URL, request openid profile email plus a groups scope or claim, and send Vectara the client ID, client secret, and issuer URL. Confirm the exact group claim name your provider uses, because it varies.

Verify the connection

After Vectara confirms the connection is configured:

1. Open the Vectara Console sign-in page and enter an email address on one of the domains that route to your provider.
2. Confirm you are forwarded to your identity provider and can authenticate.
3. Confirm you return to the Console and see the corpora and features your role grants.

If a user signs in but lands without access, confirm the user is in a group that maps to a Vectara role and that the group is present in the ID token. If a user is not forwarded to your provider, confirm their email domain is one of the domains you sent to Vectara for this connection.

Support

Send Vectara the OIDC parameters, the email domains, and the completed group mapping worksheet through your secure channel. Vectara assigns the provider ID, returns the callback URL, configures the connection and group mapping, and tells you when the connection is ready to test. To add another provider later, repeat the steps in this guide and Vectara provisions a new connection with its own email domains.

Related pages

• Authentication methods
• Choose an authentication method
• Role-based access control