# SSO with OIDC

This guide walks you through configuring Single Sign-On (SSO) for the API7 Dashboard using the OpenID Connect (OIDC) protocol. OIDC SSO allows users to authenticate with their existing corporate credentials, eliminating the need for separate dashboard accounts.

## How It Works[​](#how-it-works "Direct link to How It Works")

<!-- -->

1. The user selects the OIDC login option on the dashboard login page.
2. The browser redirects to the IdP authorization endpoint.
3. After authentication, the IdP redirects back to the dashboard with an authorization code.
4. The dashboard exchanges the code for tokens, retrieves user information, and creates or updates the user account.
5. If role and permission boundary mappings are configured, they are applied on each login.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before you begin, ensure you have:

* A running API7 Gateway deployment with dashboard access.

* An OIDC-compliant identity provider (e.g., Keycloak, Microsoft Entra ID, Auth0, Okta).

* The following information from your IdP:

  <!-- -->

  * **Issuer URL**: The OIDC discovery endpoint (without `/.well-known/openid-configuration`).
  * **Client ID**: The application identifier registered in the IdP.
  * **Client Secret**: The application secret.

## Step 1: Register API7 Dashboard in Your IdP[​](#step-1-register-api7-dashboard-in-your-idp "Direct link to Step 1: Register API7 Dashboard in Your IdP")

Register the API7 Dashboard as an OIDC client application in your identity provider:

1. Create a new application with the **Authorization Code** grant type (also called "standard flow" or "confidential client").

2. Set the redirect URI to: `https://<DASHBOARD_URL>/api/oidc/<LOGIN_OPTION_ID>/callback`.

   note

   The `LOGIN_OPTION_ID` is generated after creating the login option in API7 (Step 2). You may need to return to your IdP to update the redirect URI after completing Step 2.

3. Record the **Client ID**, **Client Secret**, and **Issuer URL** for the next step.

See the [Provider-Specific Configuration](#provider-specific-configuration) section below for detailed instructions for specific IdPs.

## Step 2: Create an OIDC Login Option[​](#step-2-create-an-oidc-login-option "Direct link to Step 2: Create an OIDC Login Option")

1. In the API7 Dashboard, navigate to **Organization > Settings**.
2. Click **Add Login Option**.
3. Fill in the configuration:

| Field                  | Description                                                                     | Example                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Name**               | Display name shown on the login page as "Login with {Name}"                     | `Corporate SSO`                                                                             |
| **Provider**           | Select `OIDC`                                                                   | —                                                                                           |
| **Issuer**             | Issuer URL of your OIDC provider (without `/.well-known/openid-configuration`)  | `https://idp.example.com/realms/my-realm`                                                   |
| **Client ID**          | Application identifier from your IdP                                            | `api7-dashboard`                                                                            |
| **Client Secret**      | Application secret from your IdP                                                | `********`                                                                                  |
| **Request Scope**      | Space-separated list of scopes. `openid` is required.                           | `openid profile email`                                                                      |
| **Root URL**           | URL users use to access the dashboard. Must match the protocol, host, and port. | `https://dashboard.example.com`                                                             |
| **SSL Verify**         | Whether to verify the IdP's TLS certificate                                     | `true`                                                                                      |
| **Logout URL**         | IdP's `end_session_endpoint` URL, optionally with `post_logout_redirect_uri`    | `https://idp.example.com/.../logout?post_logout_redirect_uri=https://dashboard.example.com` |
| **Attributes Mapping** | Map IdP claims to API7 user fields: `username`, `email`, `name`                 | `preferred_username`, `email`, `name`                                                       |

4. Click **Add**.

After creation, the login option displays its **Callback URL**. Copy this URL and register it as a redirect URI in your IdP (if not already done in Step 1).

## Step 3: Verify SSO Login[​](#step-3-verify-sso-login "Direct link to Step 3: Verify SSO Login")

1. Sign out of the API7 Dashboard.
2. On the login page, you should see a new option: **Login with {Name}**.
3. Click it to authenticate through your IdP.
4. After successful authentication, you are redirected back to the dashboard.

The SSO user appears under **Organization > Users**. By default, the user has no roles assigned and cannot manage resources until you configure role mapping or manually assign a role.

important

Deleting a user in the Dashboard removes their roles and permission boundaries, but the user can still log in again as a new user. To fully revoke access, remove the user from the IdP.

## Configure Role Mapping[​](#configure-role-mapping "Direct link to Configure Role Mapping")

Role mapping automatically assigns API7 roles to SSO users based on attributes from the identity provider. This eliminates manual role assignment and keeps permissions synchronized.

info

Automatic role mappings take precedence over manual role assignments. When mappings are active, any manual changes are overwritten on the user's next login.

### Step 1: Expose Role Attributes in Your IdP[​](#step-1-expose-role-attributes-in-your-idp "Direct link to Step 1: Expose Role Attributes in Your IdP")

Configure your IdP to include role-related attributes in the user info or token claims. The approach varies by IdP:

* **User attribute**: Add an attribute (e.g., `position: admin`) directly to the user profile.
* **Group membership**: Add the user to a group (e.g., `api7-admins`) and expose group memberships as a claim.

See the [Provider-Specific Configuration](#provider-specific-configuration) section for detailed instructions.

### Step 2: Enable Role Mapping in API7[​](#step-2-enable-role-mapping-in-api7 "Direct link to Step 2: Enable Role Mapping in API7")

1. In the API7 Dashboard, navigate to **Organization > Settings**.
2. Select your OIDC login option.
3. Enable **Role Mapping**.
4. Configure the mapping rule:

| Field              | Description                                                                                                | Example                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Internal Role**  | The API7 role to assign                                                                                    | `Super Admin`              |
| **Role Attribute** | [JSONPath](https://goessner.net/articles/JsonPath) to the IdP attribute                                    | `$.position` or `$.groups` |
| **Operation**      | Comparison method: `Exact Match`, `Contains String`, `Exact Match in Array`, or `Contains String in Array` | `Exact Match`              |
| **Role Value**     | Expected attribute value                                                                                   | `admin`                    |

5. Click **Enable**.

Users with matching attributes are automatically assigned the specified role on their next login.

### Permission Boundary Mapping[​](#permission-boundary-mapping "Direct link to Permission Boundary Mapping")

Permission boundary mapping works the same way as role mapping but assigns [permission policies](https://docs.api7.ai/api7-gateway/security-and-compliance/permission-policies-and-boundaries.md) as boundaries instead of attaching roles. Enable **Permission Boundary Mapping** in the login option settings and configure the mapping rules with the same attribute-matching approach.

## Provider-Specific Configuration[​](#provider-specific-configuration "Direct link to Provider-Specific Configuration")

### Keycloak[​](#keycloak "Direct link to Keycloak")

#### IdP Setup[​](#idp-setup "Direct link to IdP Setup")

1. Create a **realm** (e.g., `my-realm`).

2. Create a **client** (e.g., `api7-dashboard`):

   <!-- -->

   * Enable **client authentication** (confidential access type).
   * Enable **standard flow** (authorization code grant).
   * Set the redirect URI to `https://<DASHBOARD_URL>/api/oidc/<LOGIN_OPTION_ID>/callback`.

3. In the client **Credentials** tab, copy the **Client Secret**.

4. Create **users** with passwords as needed.

5. In **Realm Settings**, find the **OpenID Connect Discovery** link and record:

   <!-- -->

   * The `issuer` URL (e.g., `https://keycloak.example.com/realms/my-realm`).
   * The `end_session_endpoint` URL for the Logout URL.

#### Attribute Mapping Configuration[​](#attribute-mapping-configuration "Direct link to Attribute Mapping Configuration")

| Attribute Mapping | IdP Claim            | API7 Field |
| ----------------- | -------------------- | ---------- |
| username          | `preferred_username` | `username` |
| email             | `email`              | `email`    |
| name              | `name`               | `name`     |

#### Role Mapping via User Attribute[​](#role-mapping-via-user-attribute "Direct link to Role Mapping via User Attribute")

1. Enable **Unmanaged Attributes** in **Realm Settings**.

2. Navigate to the user's **Attributes** tab and add a key-value pair (e.g., `position: admin`).

3. In **Client Scopes**, select the scope included in your **Request Scope** (e.g., `profile`).

4. Add a **User Attribute** mapper:

   <!-- -->

   * **User Attribute**: `position`
   * **Token Claim Name**: `position`

5. In API7, use the mapping rule: Attribute `$.position`, Operation `Exact Match`, Value `admin`.

#### Role Mapping via Group Membership[​](#role-mapping-via-group-membership "Direct link to Role Mapping via Group Membership")

1. Create a **group** (e.g., `admin`) and add users to it.
2. In **Client Scopes**, add a **Group Membership** mapper:
   <!-- -->
   * **Token Claim Name**: `groups`
3. Inspect the `groups` claim in an ID token and copy the exact value for the group. In API7, use the mapping rule: Attribute `$.groups`, Operation `Exact Match in Array`, Value `/admin` (or the exact value from the token if it differs).

### Microsoft Entra ID (Azure AD)[​](#microsoft-entra-id-azure-ad "Direct link to Microsoft Entra ID (Azure AD)")

#### IdP Setup[​](#idp-setup-1 "Direct link to IdP Setup")

1. In the [Azure portal](https://portal.azure.com/), go to **Microsoft Entra ID > App registrations** and register a new application.
2. Under **Certificates & secrets**, create a new client secret and save it.
3. Find the **OpenID Connect metadata document** URL under **Endpoints**. Extract the issuer URL (e.g., `https://login.microsoftonline.com/{tenant-id}/v2.0`).
4. Under **Authentication**, add the redirect URI: `https://<DASHBOARD_URL>/api/oidc/<LOGIN_OPTION_ID>/callback`.

#### Attribute Mapping Configuration[​](#attribute-mapping-configuration-1 "Direct link to Attribute Mapping Configuration")

| Attribute Mapping | IdP Claim            | API7 Field |
| ----------------- | -------------------- | ---------- |
| username          | `preferred_username` | `username` |
| email             | `email`              | `email`    |
| name              | `name`               | `name`     |

note

The issuer URL should not include `/.well-known/openid-configuration`.

#### Role Mapping[​](#role-mapping "Direct link to Role Mapping")

1. Under **App roles**, create roles (e.g., `SuperAdmin`).
2. Under **Enterprise applications**, assign the role to users.
3. In API7, use the mapping rule: Attribute `$.roles`, Operation `Exact Match in Array`, Value `SuperAdmin`.

### Auth0[​](#auth0 "Direct link to Auth0")

#### IdP Setup[​](#idp-setup-2 "Direct link to IdP Setup")

1. Under **Applications**, create a **Regular Web Application**.

2. Record the **Client ID**, **Client Secret**, and **Domain** (issuer).

3. The issuer URL is `https://<DOMAIN>/` (include the trailing slash).

4. Under the application **Settings** tab:

   <!-- -->

   * Add the callback URL to **Allowed Callback URLs**.
   * Add the dashboard URL to **Allowed Logout URLs** and **Allowed Web Origins**.

5. Review the discovery document at `https://<DOMAIN>/.well-known/openid-configuration` for the `end_session_endpoint`.

#### Attribute Mapping Configuration[​](#attribute-mapping-configuration-2 "Direct link to Attribute Mapping Configuration")

| Attribute Mapping | IdP Claim | API7 Field |
| ----------------- | --------- | ---------- |
| username          | `name`    | `username` |
| email             | `email`   | `email`    |
| name              | `name`    | `name`     |

#### Role Mapping[​](#role-mapping-1 "Direct link to Role Mapping")

Auth0 requires a post-login Action to include roles in the token claims:

1. Under **User Management > Roles**, create a role (e.g., `admin`) and assign users.
2. Under **Actions > Triggers**, create a `post-login` action:

```
exports.onExecutePostLogin = async (event, api) => {

  const roles = (event.authorization && event.authorization.roles) || [];

  const claimName = "https://dashboard.example.com/roles";

  api.idToken.setCustomClaim(claimName, roles);

  api.accessToken.setCustomClaim(claimName, roles);

};
```

3. Attach the action to the **Post Login** trigger.
4. In API7, use the mapping rule: Attribute `$['https://dashboard.example.com/roles']`, Operation `Exact Match in Array`, Value `admin`.

## Delete a Login Option[​](#delete-a-login-option "Direct link to Delete a Login Option")

warning

Deleting a login option removes all dashboard users associated with that option.

1. Navigate to **Organization > Users** and verify which users are associated with this login option.
2. Navigate to **Organization > Settings**.
3. Click **Delete** on the login option.

note

At least one login option must remain enabled at all times. You cannot delete or disable the last remaining enabled login option.

## Additional Resources[​](#additional-resources "Direct link to Additional Resources")

* [SSO with SAML](https://docs.api7.ai/api7-gateway/security-and-compliance/sso-saml.md)
* [SSO with LDAP](https://docs.api7.ai/api7-gateway/security-and-compliance/sso-ldap.md)
* [SSO Overview (Enterprise Feature)](https://docs.api7.ai/api7-gateway/enterprise-features/dashboard-sso.md)
* [Roles and Permission Policies](https://docs.api7.ai/api7-gateway/security-and-compliance/role-based-access-control.md)
* [Role-Based Access Control](https://docs.api7.ai/api7-gateway/security-and-compliance/role-based-access-control.md)