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

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

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

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 section below for detailed instructions for specific IdPs.

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

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

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

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 section for detailed instructions.

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 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 works the same way as role mapping but assigns permission policies 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

Keycloak

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	IdP Claim	API7 Field
username	preferred_username	username
email	email	email
name	name	name

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

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. In API7, use the mapping rule: Attribute $.groups[*], Operation Contains String, Value admin.

Microsoft Entra ID (Azure AD)

IdP Setup

1. In the Azure portal, 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	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

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

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	IdP Claim	API7 Field
username	name	username
email	email	email
name	name	name

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

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

• SSO with SAML
• SSO with LDAP
• SSO Overview (Enterprise Feature)
• Roles and Permission Policies
• Role-Based Access Control