> 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/generic.md).

# Generic Provider (SAML / OIDC)

This guide explains how to configure SSO integration between Trust and any identity provider compatible with `SAML 2.0` or `OpenID Connect` (`OIDC`). Use this guide for providers such as Google Workspace, Keycloak, OneLogin, among others.

{% hint style="info" %}
**Before you begin:** Access Trust and copy the **Identifier** and **Reply URL** fields as described in [Step 2 of the SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md#passo-2-selecionar-protocolo-e-obter-dados).
{% endhint %}

***

## Prerequisites

* Administrator access to the identity provider
* Administrator access to Trust
* Provider compatible with `SAML 2.0` or `OpenID Connect` / `OAuth 2.0`
* Verified corporate email domain

***

## Choose the Protocol

{% tabs %}
{% tab title="SAML" %}

### SAML Configuration

#### Create Application in the Provider

Access your identity provider's admin panel and create a new `SAML 2.0` application. The steps vary depending on the provider, but generally include:

1. Create new SAML application / integration
2. Select **SAML 2.0** type
3. Configure the **ACS URL** (Trust reply URL)
4. Configure the **Entity ID** (Trust identifier)

#### Configure SAML Settings

Configure the following fields in the provider:

| Provider Field                   | Value                               |
| -------------------------------- | ----------------------------------- |
| **ACS URL / Single Sign-On URL** | Paste the **Reply URL** from Trust  |
| **Entity ID / Audience URI**     | Paste the **Identifier** from Trust |

#### Configure Attribute Statements

Configure the attributes that will be sent to Trust:

| Name          | Value (example)    |
| ------------- | ------------------ |
| `email`       | `user.email`       |
| `name`        | `user.displayName` |
| `given_name`  | `user.firstName`   |
| `family_name` | `user.lastName`    |

#### Configure Group Attribute Statements (Optional)

If you want to use custom group mapping:

| Name     | Value                                   |
| -------- | --------------------------------------- |
| `groups` | User groups (format varies by provider) |

#### Get Metadata URL

After creating the application, copy the provider's **Metadata URL**. The URL generally follows a format similar to:

```
https://{your-provider}/app/{app-id}/sso/saml/metadata
```

{% hint style="info" %}
**Tip:** Some providers allow you to download the metadata XML file. In this case, you can host the file or use the direct download URL.
{% endhint %}

{% hint style="warning" %}
**Important:** Consult your provider's documentation to confirm the exact names of SAML attributes.
{% endhint %}
{% endtab %}

{% tab title="OIDC" %}

### OIDC Configuration

#### Create Application in the Provider

Access your identity provider's admin panel and create a new `OIDC` / `OAuth 2.0` application. The steps vary depending on the provider, but generally include:

1. Create new application / client
2. Select **Web Application** or **Server-side** type
3. Configure **Grant Type**: Authorization Code
4. Enter the **Redirect URI** (Trust reply URL)

#### Get Provider Credentials

After creating the application, copy the following information:

| Provider Field    | Description                            |
| ----------------- | -------------------------------------- |
| **Client ID**     | Unique application identifier          |
| **Client Secret** | Secret key for authentication          |
| **Issuer URL**    | Provider base URL (discovery endpoint) |

{% hint style="info" %}
**Tip:** The `Issuer URL` can usually be found at the provider's `/.well-known/openid-configuration` endpoint.
{% endhint %}

{% hint style="warning" %}
**Important:** Consult your provider's documentation to confirm the exact names of claims.
{% endhint %}
{% endtab %}
{% endtabs %}

***

## Next Steps

After configuring the provider, return to the [Trust SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md) to:

1. [Configure Properties and Scopes](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-2-select-protocol-and-obtain-data)
2. [Configure Permission Groups](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-3-configure-permission-groups)
3. [Configure Attribute Statements](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-4-configure-attribute-statements)
4. [Configure Domains](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-5-configure-domains)
5. [Save and Test](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-6-save-and-test)

***

## 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 the 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                                             |
| CORS error                 | Provider blocks requests                         | Configure allowed origins in the provider                                    |

***

## References

* [OpenID Connect Specification](https://openid.net/connect/)
* [OAuth 2.0 RFC](https://datatracker.ietf.org/doc/html/rfc6749)
* [SAML 2.0 Specification](https://docs.oasis-open.org/security/saml/v2.0/)


---

# 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/generic.md?ask=<question>&goal=<endgoal>
```

`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.