> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-docs/user-guide/trust-platform/sso-configurations.md).
# SSO Configuration
The **SSO Configuration** screen allows you to configure the Single Sign-On process for Trust users. With SSO enabled, users can access the platform using their corporate identity provider credentials, without needing to create a specific password for Trust.
{% hint style="warning" %}
**Important:** Trust only supports Service Provider-initiated (SP-initiated) login flow. This means users must access Trust directly and enter their email to be redirected to the identity provider. Identity Provider-initiated (IdP-initiated) login, where users access the application directly through the provider's portal, is not supported.
{% endhint %}
***
## Supported Providers
Trust supports integration with most identity providers compatible with `SAML 2.0` or `OpenID Connect` (`OIDC`).
We provide detailed guides for the most commonly used providers:
| Provider | Protocol | Documentation |
| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
| Microsoft Entra ID (Azure AD) | `SAML` | [Configure Microsoft Entra ID](/caf-docs/user-guide/trust-platform/sso-configurations/microsoft-entra-id.md) |
| Okta | `SAML` / `OIDC` | [Configure Okta](/caf-docs/user-guide/trust-platform/sso-configurations/okta.md) |
| Auth0 | `SAML` / `OIDC` | [Configure Auth0](/caf-docs/user-guide/trust-platform/sso-configurations/auth0.md) |
| Google Workspace | `SAML` | [Configure Google Workspace](/caf-docs/user-guide/trust-platform/sso-configurations/google.md) |
For other providers, use the [Generic Provider Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations/generic.md).
***
## Authentication Protocols
Trust supports two authentication protocols:
{% tabs %}
{% tab title="SAML" %}
**Security Assertion Markup Language**
* `XML`-based protocol for exchanging authentication data
* Widely used in corporate environments
* Requires configuration of the identity provider's `Metadata URL`
{% endtab %}
{% tab title="OIDC" %}
**OpenID Connect**
* Modern protocol based on `OAuth 2.0`
* Uses `JWT` tokens for authentication
* Requires configuration of `Client ID`, `Client Secret`, and `Issuer URL`
{% endtab %}
{% endtabs %}
***
## Step 1: Access SSO Configuration
To access the SSO configuration screen in Trust:
1. Access Trust with an administrator account
2. Click on **Security Center**
3. Access **Sessions and Login**
4. Enable **SSO Settings**
## Step 2: Select Protocol and Obtain Data
Select the authentication protocol and copy the data generated by Trust.
{% tabs %}
{% tab title="SAML" %}
#### SAML Configuration
Copy the following fields from Trust to configure in the provider:
| Trust Field | Use in Provider as | Action |
| -------------- | ---------------------------- | ------ |
| **Identifier** | Entity ID / Audience URI | Copy |
| **Reply URL** | ACS URL / Single Sign-On URL | Copy |
Configure the application in your identity provider:
* [Microsoft Entra ID (Azure AD)](/caf-docs/user-guide/trust-platform/sso-configurations/microsoft-entra-id.md)
* [Okta](/caf-docs/user-guide/trust-platform/sso-configurations/okta.md)
* [Auth0](/caf-docs/user-guide/trust-platform/sso-configurations/auth0.md)
* [Google](/caf-docs/user-guide/trust-platform/sso-configurations/google.md) |
* [Generic Provider](/caf-docs/user-guide/trust-platform/sso-configurations/generic.md)
After configuring the provider, fill in Trust:
| Trust Field | Value |
| ---------------- | --------------------------------------- |
| **Metadata URL** | Metadata URL obtained from the provider |
{% hint style="info" %}
The **Metadata URL** contains all the necessary information for Trust to communicate with the provider, including certificates and endpoints.
{% endhint %}
{% endtab %}
{% tab title="OIDC" %}
#### OIDC Configuration
Copy the following fields from Trust to configure in the provider:
| Trust Field | Use in Provider as | Action |
| -------------- | --------------------------- | ------ |
| **Identifier** | Client ID Reference | Copy |
| **Reply URL** | Redirect URI / Callback URL | Copy |
Configure the application in your identity provider:
* [Okta](/caf-docs/user-guide/trust-platform/sso-configurations/okta.md)
* [Auth0](/caf-docs/user-guide/trust-platform/sso-configurations/auth0.md)
* [Generic Provider](/caf-docs/user-guide/trust-platform/sso-configurations/generic.md)
After configuring the provider, fill in Trust:
| Trust Field | Value |
| ----------------- | ---------------------------------------------------------------- |
| **Client ID** | Client ID obtained from the provider |
| **Client Secret** | Secret key obtained from the provider |
| **HTTP Method** | `GET` (default) or `POST` (according to provider) |
| **Issuer URL** | Issuer URL obtained from the provider |
| **Scopes** | `openid email profile` (add `groups` if Custom mode is selected) |
### About Scopes
Scopes define which information will be shared by the provider. Configure according to your needs:
| Scope | Description |
| --------- | --------------------------------------------------------- |
| `openid` | Required for `OIDC`. Returns the user ID. |
| `email` | Returns the user's email address. |
| `profile` | Returns profile information (name, surname, etc.). |
| `groups` | Returns the user's groups (if supported by the provider). |
{% hint style="info" %}
Separate scopes with a space. Example: `openid email profile`
{% endhint %}
{% hint style="warning" %}
**Custom Group Mapping:** If you plan to use **Custom** mode for permission group mapping, add the `groups` scope to the configuration. Example: `openid email profile groups`
{% endhint %}
***
{% endtab %}
{% endtabs %}
***
## Step 3: Configure Permission Groups
Define how to assign permission groups to users accessing Trust via SSO.
### Permission Mode
| Option | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manual** | All users who belong to the selected group will log in via SSO. This validation is done only on first access. |
| **Synchronized** | On each SSO access, the provider groups are synchronously linked to Trust. Unmapped groups will be directed to the fallback permission group. |
### Fields
| Field | Required | Description |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| **Default permission group** | Yes | Permission group assigned to new SSO users. In custom mode, works as a fallback for users without mapped groups. |
### Group Mapping (Custom Mode)
When **Custom** mode is selected, configure the mapping between identity provider groups and Trust groups.
| Field | Description |
| ------------------ | ---------------------------------------------------------------------- |
| **Provider group** | Group name as defined in the identity provider (e.g., Azure AD, Okta). |
| **Trust group** | Corresponding permission group in the Trust platform. |
### Group Attribute Statement
When **Custom** mode is selected, also configure the groups attribute in **Attribute Statements**:
| Trust Field | Description |
| ----------- | -------------------------------------------------------------------------------- |
| **Groups** | Name of the attribute containing the user's group list in the identity provider. |
{% hint style="warning" %}
**Important:** It is not possible to register two identical provider groups.
{% endhint %}
***
## Step 4: Configure Attribute Statements
Configure the mapping between attributes returned by the identity provider and the fields expected by Trust. Attribute names must exactly match the provider's `claims`/`assertions`.
### User Attributes
| Trust Field | Required | Description |
| --------------- | -------- | ---------------------------------------------------------- |
| **E-mail** | Yes | Name of the attribute containing the user's email address. |
| **Name** | Yes | Name of the attribute containing the user's full name. |
| **Given Name** | Yes | Name of the attribute containing the user's first name. |
| **Family Name** | Yes | Name of the attribute containing the user's last name. |
{% hint style="info" %}
Consult your provider's specific documentation to confirm the exact attribute names.
{% endhint %}
***
## Step 5: Configure Domains
Configure the email domains that will be directed to SSO authentication.
### DNS Verification Record
To ensure the security and authenticity of your SSO configuration, Trust requires DNS verification for the registered domains. This process confirms that you have administrative control over the domain.
#### How to Configure
1. Copy the value from the **DNS Verification Record** field in Trust
2. Access your DNS provider's management panel (e.g., Cloudflare, Route 53, GoDaddy)
3. Add a new `TXT` record with the copied value
4. Return to Trust and click **Save configurations**
| DNS Field | Value |
| ----------------- | ------------------------------------------ |
| **Type** | `TXT` |
| **Name/Host** | `@` or your domain root |
| **Value/Content** | The value copied from Trust |
| **TTL** | `3600` (1 hour) or your provider's default |
{% hint style="info" %}
**DNS Propagation:** DNS changes may take between 15 minutes and 48 hours to propagate globally. If verification fails, wait a few minutes and try saving again.
{% endhint %}
{% hint style="info" %}
**Tip:** Use tools like [DNS Checker](https://dnschecker.org/) or [MX Toolbox](https://mxtoolbox.com/TXTLookup.aspx) to verify if your DNS record has propagated correctly.
{% endhint %}
| Field | Required | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| **Domains** | Yes | List of email domains allowed for SSO authentication. Users with emails from these domains will be redirected to SSO. |
### Domain Rules
* At least one domain must be entered
* Format must be valid (e.g., `company.com`, `company.com.br`)
* Multiple domains can be added
* Domains are separated by comma or Enter
{% hint style="info" %}
**Example:** `caf.io`
{% endhint %}
***
## Step 6: Save and Test
1. Click **Save** to activate the SSO configuration
2. Open an incognito browser window
3. Access Trust and enter an email from the configured domain
4. You will be redirected to the provider's login screen
5. After authenticating, you will return to Trust authenticated
{% hint style="success" %}
**Done!** SSO integration is configured.
{% endhint %}
***
## Validations and Error Messages
| Situation | Message |
| ------------------------- | -------------------------------------------------------------- |
| No domain entered | "At least one domain must be filled in" |
| Domain in invalid format | "Invalid domain" |
| Invalid URL | "Invalid URL" |
| Required field not filled | "\[Field name] is required" |
| Duplicate provider group | "It is not possible to register two identical provider groups" |
| No mapping in custom mode | "At least one custom group mapping must be configured" |
***
## Troubleshooting
| Problem | Probable Cause | Solution |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
| Redirect error | URI does not match | Verify that the reply URL is identical in both systems |
| Invalid token (OIDC) | Incorrect Client Secret | Verify or regenerate the Client Secret |
| Invalid certificate (SAML) | Expired certificate | Update the certificate in the provider and the metadata URL in Trust |
| Claims not received | Insufficient scopes or attributes not configured | Add the necessary scopes (OIDC) or configure Attribute Statements (SAML) |
| Invalid issuer | Incorrect URL | Verify the Issuer URL at the `/.well-known/openid-configuration` endpoint |
| Signature error (SAML) | Outdated metadata | Update the Metadata URL in Trust |
***
## Glossary
| Term | Definition |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| **SSO** | Single Sign-On - Allows users to access multiple applications with a single authentication. |
| **SAML** | Security Assertion Markup Language - Standard protocol for exchanging authentication data. |
| **OIDC** | OpenID Connect - Identity layer built on top of the `OAuth 2.0` protocol. |
| **IDP** | Identity Provider - Service that stores and verifies user identity. |
| **Metadata URL** | URL containing the `XML` file with `SAML` identity provider configurations. |
| **Issuer URL** | Base URL of the `OIDC` provider that issues and validates tokens. |
| **Scopes** | Permissions requested during authentication that define which information will be shared. |
| **Claims / Assertions** | Statements about the user returned by the identity provider after successful authentication. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.caf.io/caf-docs/user-guide/trust-platform/sso-configurations.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.