> 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/organizations/sso-configurations/auth0.md).

# Auth0 (SAML / OIDC)

Configure SSO with Auth0 using SAML or OIDC protocols.

This guide explains how to configure SSO integration between Organizations and Auth0. After configuring Auth0, return to the [Organizations SSO Configuration Guide](/caf-docs/user-guide/organizations/sso-configurations.md) to complete the setup.

{% hint style="info" %}
**Before you begin:** Open **Authentication** → **SSO** in Organizations and copy the **Entity ID** and **ACS URL** (SAML) or **Redirect URI** (OIDC) as described in [Step 2 of the SSO Configuration Guide](/caf-docs/user-guide/organizations/sso-configurations.md#step-2-enable-sso-and-configure-the-provider).
{% endhint %}

***

## Prerequisites

* Administrator access to Auth0
* Super Admin access to Organizations

***

## Choose the Protocol

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

## SAML Configuration

### Create Application in Auth0

1. Access the [Auth0 Dashboard](https://manage.auth0.com)
2. Navigate to **Applications** → **Applications**
3. Click **Create Application**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-9f6b906735bebbf15ea4d303bec0eca78c32563c%2Fauth0-create-application.jpg?alt=media" alt="Auth0 - Create Application"></div>

4. Configure the **Name** (e.g., "Certta")
5. Select **Regular Web Applications** and click **Create**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-6f0480ecc05cba8c27436f3cf578e8bac97046c9%2Fauth0-select-app-type.jpg?alt=media" alt="Auth0 - Select application type"></div>

### Enable SAML

1. In the created application, access the **Addons** tab
2. Locate **SAML2 Web App** and click to enable
3. Click on **SAML2 Web App** after enabling

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-f9c4b2fa110092db74dabaf82bee0048e7da6644%2Fauth0-addons-saml.jpg?alt=media" alt="Auth0 - Addons SAML"></div>

4. In the **Settings** tab, in the **Application Callback URL** field, paste the **ACS URL** from Organizations

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-cc9f93e0c558c3cf6f95a835390beaff128eb2b0%2Fauth0-saml-settings-json.jpg?alt=media" alt="Auth0 - SAML Settings JSON"></div>

5. In the JSON editor, set the **audience** to the Organizations **Entity ID** and configure attribute mappings:

```json
{
  "audience": "Identifier URL",
  "mappings": {
    "email": "email",
    "name": "name",
    "given_name": "given_name",
    "family_name": "family_name"
  },
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ]
}
```

6. Scroll to the end of the **Settings** tab and click **Save**

### Configure groups for SAML (optional)

To use **Group assignment rules** in Organizations, add a `groups` entry to the **mappings** object in the SAML2 Web App JSON. The source value depends on how groups are exposed in your Auth0 tenant (for example, directory groups from an Enterprise Connection).

On the **Attribute mapping** tab in Organizations, set **Groups** to `groups`.

### Get Metadata URL

1. Access the **Usage** tab
2. Locate the **Identity Provider Login URL**
3. Build the **Metadata URL** by adding `/metadata` before the client ID:

| Field                           | Format                                             |
| ------------------------------- | -------------------------------------------------- |
| **Identity Provider Login URL** | `https://{your-domain}/samlp/{client-id}`          |
| **Metadata URL**                | `https://{your-domain}/samlp/metadata/{client-id}` |

{% hint style="info" %}
**Example:** If the Identity Provider Login URL is `https://dev-abc123.us.auth0.com/samlp/xyz789`, the Metadata URL will be `https://dev-abc123.us.auth0.com/samlp/metadata/xyz789`.
{% endhint %}

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-1b27f70a83fea1b54af7a5872d481f0c3dd292d7%2Fauth0-saml-metadata-url.jpg?alt=media" alt="Auth0 - SAML Metadata URL"></div>
{% endtab %}

{% tab title="OIDC" %}

## OIDC Configuration

### Create Application in Auth0

1. Access the [Auth0 Dashboard](https://manage.auth0.com)
2. Navigate to **Applications** → **Applications**
3. Click **Create Application**
4. Configure the **Name** (for example, `Certta`)
5. Select **Regular Web Applications** and click **Create**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-9f6b906735bebbf15ea4d303bec0eca78c32563c%2Fauth0-create-application.jpg?alt=media" alt="Auth0 - Create Application"></div>

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-6f0480ecc05cba8c27436f3cf578e8bac97046c9%2Fauth0-select-app-type.jpg?alt=media" alt="Auth0 - Select application type"></div>

### Configure Application Settings

In the application's **Settings** tab, configure:

| Auth0 Field               | Value                                                |
| ------------------------- | ---------------------------------------------------- |
| **Allowed Callback URLs** | Paste the **Redirect URI** copied from Organizations |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-d2df0a9ad2c08ee5bfc59d99acb3afca33a641e0%2Fauth0-oidc-settings.jpg?alt=media" alt="Auth0 - Application Settings"></div>

Click **Save**.

### Get Credentials

In the same **Settings** tab, copy the following information:

| Auth0 Field       | Use in Organizations as     |
| ----------------- | --------------------------- |
| **Domain**        | Use to build the Issuer URL |
| **Client ID**     | Client ID                   |
| **Client Secret** | Client Secret               |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-1efd1f7f0108c79e6b0f37fa19a7b5e7275db26b%2Fauth0-oidc-credentials.jpg?alt=media" alt="Auth0 - Client Credentials"></div>

### Get Issuer URL

The Auth0 Issuer URL follows the format:

```
https://{your-domain}/
```

### Configure groups for OIDC (optional)

To use **Group assignment rules** based on IdP groups:

1. Navigate to **Actions** → **Library** → **Build Custom**
2. Create a **Post Login** Action that adds a `groups` claim to the ID token (source depends on your Auth0 roles, Authorization Groups, or upstream IdP attributes)
3. Deploy the Action and add it to the Login flow for this application
4. In Organizations, add `groups` to **Authorization scopes** on the **SSO** tab and map **Groups** on the **Attribute mapping** tab to `groups`

See [Auth0 Actions documentation](https://auth0.com/docs/customize/actions) for claim customization patterns.
{% endtab %}
{% endtabs %}

***

## Enable Connections and Users

In Auth0, user access to the application is controlled by enabled **Connections**. A Connection is the source of user identity (internal database, social login, corporate directory, etc.).

### Enable Connections in the Application

1. In the created application, access the **Connections** tab
2. Enable the connections where your users are registered

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-d18e3dbf9e88f57385971188d0b653821fa89134%2Fauth0-connections.jpg?alt=media" alt="Auth0 - Connections"></div>

| Connection Type | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| **Database**    | Users registered directly in Auth0 (e.g., `Username-Password-Authentication`) |
| **Social**      | Login via social providers (Google, Microsoft, etc.)                          |
| **Enterprise**  | Corporate connections (SAML, OIDC, Azure AD, etc.)                            |

{% hint style="warning" %}
**Important:** If the Connection where the user is registered is not enabled for the application, the user will not be able to log in.
{% endhint %}

***

## Next Steps

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

1. [Configure attribute mapping](/caf-docs/user-guide/organizations/sso-configurations.md#step-3-configure-attribute-mapping)
2. [Configure group assignment rules](/caf-docs/user-guide/organizations/sso-configurations.md#step-4-configure-group-assignment-rules)
3. [Save and test](/caf-docs/user-guide/organizations/sso-configurations.md#step-5-save-and-test)

***

## Troubleshooting

| Problem                | Probable Cause              | Solution                                                                                             |
| ---------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- |
| Callback URL error     | URL does not match          | Verify **Allowed Callback URLs** (OIDC) or **Application Callback URL** (SAML) matches Organizations |
| Invalid token          | Incorrect Client Secret     | Regenerate the Client Secret in Auth0 and update it in Organizations                                 |
| Groups not received    | Groups claim not configured | Add `groups` to SAML mappings or configure a Post Login Action for OIDC                              |
| Invalid SAML assertion | Incorrect audience          | Verify that the **audience** in the addon JSON matches the Organizations **Entity ID**               |
| User not found         | Connection not enabled      | Check the enabled connections in the **Connections** tab                                             |

***

## References

* [Auth0 Documentation - SAML](https://auth0.com/docs/authenticate/protocols/saml)
* [Auth0 Documentation - OIDC](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol)
* [Configure Actions](https://auth0.com/docs/customize/actions)
* [Add custom claims](https://auth0.com/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)


---

# 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/organizations/sso-configurations/auth0.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.