When to Use External Auth
- You enabled Public Access on an agent and chose Signed-in users only.
- You want only verified users from your identity provider (for example Microsoft Entra ID or any OpenID Connect provider) to chat.
- You want each user’s conversations saved to their personal Library.
You select a configured sign-in system per agent in the agent’s General settings. See Agent Management.
How It Works
Configurations are immutable and versioned:- Saving changes never edits an existing version — it creates a new version and re-points the active one.
- You can roll back or fast-forward by activating any previous version.
- Secrets (such as a static public key) are write-only: they must be re-entered when creating a new version.
Creating a Sign-in System
1
Open External Auth Setup
Go to Settings and open External Auth Config (also reachable via Configure External Auth Setup from an agent’s General tab).
2
Create a new setup
Click New Setup and provide:
- Name: A recognizable label (e.g. “Acme SSO (Entra ID)”). This name appears in the agent’s public chatbot settings.
- Description (optional): Who signs in with this provider and where it’s used.
3
Add a configuration version
With the setup selected, click Add Configuration and choose a Validation Type (see below).
4
Save
Click Save New Version. The new version becomes the active configuration immediately.
The setup shows an active version label and the validation type you selected.
Validation Types
Choose how tokens are verified. Only the fields relevant to the selected type are shown.- OIDC Discovery
- JWKS URL
- Public Key URL
- Static Public Key
Uses the provider’s well-known discovery document to locate signing keys automatically.
url
required
The OpenID configuration endpoint, e.g.
https://issuer/.well-known/openid-configuration.Common Fields
These optional fields apply to every validation type:string
Expected
iss claim. When set, tokens with a different issuer are rejected.string
Expected
aud claim. When set, tokens with a different audience are rejected.Advanced Settings
string
default:"sub"
The claim used to identify the user (for example
sub or email).array
Comma-separated list of accepted signing algorithms (for example
RS256). Sensible defaults are applied per validation type.array
Comma-separated claims (other than the user identifier) that MUST be present in the token for validation to succeed (for example
email, roles).Managing Versions
- Version History lists every saved configuration with its validation type, creation time, and author.
- The active version is highlighted and is the one used to validate tokens.
- Open a version to view its details and Activate it to roll back or fast-forward.
Activating an older version takes effect immediately for all agents using this setup.
Testing a Configuration
Before relying on a configuration, validate a real token against it.
1
Select a version
Choose which version to test against (the active one is marked).
2
Paste a JWT
Paste a token issued by your identity provider.
3
Run the test
Click Test Token. The result shows whether the token is valid, any validation errors, the resolved user identifier, and the decoded claims.
A valid token returns “Token is valid” with the expected user identifier.
Connecting to an Agent
1
Open the agent's General settings
In Agent Management, open Settings and go to the General tab.
2
Enable public access
Turn on Public Access and provide an Allowed Origin URL.
3
Require sign-in
Under Who can use the chatbot?, choose Signed-in users only.
4
Select the sign-in system
Pick the External Auth configuration you created from the Sign-in system dropdown, then save.
See Agent Management → General for the agent-side configuration.
Deleting a Setup
Deleting a setup removes it and all of its config versions. Agents using it will no longer be able to authenticate external tokens.What’s Next?
Agent Management
Configure public access and sign-in per agent
Settings
Manage API keys and OAuth integrations
Chatbot Integration
Embed an agent in your website
REST API Tutorial
Connect your agents to applications