SSO with SAML

This guide walks you through configuring Single Sign-On (SSO) for the API7 Dashboard using the SAML 2.0 protocol. SAML SSO enables users to authenticate through your corporate identity provider (IdP) and access the dashboard without maintaining a separate account.

How It Works

1. The user selects the SAML login option on the dashboard login page.
2. The dashboard sends a SAML AuthnRequest to the IdP.
3. After authentication, the IdP POSTs a SAMLResponse to the dashboard's Assertion Consumer Service (ACS) URL.
4. The dashboard validates the SAML assertion, extracts user attributes, 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.
• A SAML 2.0-compliant identity provider (e.g., Microsoft Entra ID, Okta, Ping Identity).
• The following information from your IdP:
  • IdP Metadata URL: The URL that exposes the IdP's SAML metadata XML.
  • Attribute names: The claim names for username, email, and any role-related attributes.

Step 1: Create a SAML Login Option

Start by creating the login option in API7 to generate the Service Provider (SP) metadata URLs, which you will need to configure your IdP.

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 SAML
Provider	Select SAML	—
Identity Provider Metadata URL	URL to the IdP's SAML metadata XML	https://login.microsoftonline.com/{tenant}/federationmetadata/...
Service Provider Root URL	URL users use to access the dashboard	https://dashboard.example.com
Entity ID	Unique identifier for the SP in the SAML federation. Recommended: use the dashboard URL.	https://dashboard.example.com
Attributes Mapping	Map SAML assertion attributes to API7 user fields	See provider-specific sections below
Terminate IdP Session on Logout	Whether to redirect to the IdP for Single Logout (SLO)	false

4. Click Add.

After creation, the login option displays the following auto-generated URLs:

URL	Purpose
ACS URL	https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/acs — The endpoint where the IdP posts SAML responses
SLO URL	https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/slo — The endpoint for Single Logout callbacks
SP Metadata URL	https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/metadata — SP metadata XML for import into the IdP

note

API7 auto-generates a self-signed certificate and private key for SAML request signing if you do not provide your own. You can optionally supply a custom SP certificate and private key in the login option configuration.

Step 2: Configure Your IdP

Register the API7 Dashboard as a Service Provider in your identity provider using the ACS URL and Entity ID from Step 1.

See the Provider-Specific Configuration section below for detailed instructions.

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.

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 SAML assertion attributes. Configure your IdP to include role-related attributes in the SAML response, then set up mapping rules in API7.

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.

Enable Role Mapping

1. In the API7 Dashboard, navigate to Organization > Settings.
2. Select your SAML 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 SAML attribute	$.Role
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.

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

Microsoft Entra ID (Azure AD)

IdP Setup

1. In the Azure portal, navigate to Microsoft Entra ID > Enterprise applications.
2. Click New application > Create your own application:
   • Enter a name (e.g., API7 Dashboard).
   • Select Integrate any other application you don't find in the gallery (Non-gallery).
3. Under Users and groups, add the users and groups that should have SSO access to API7.
4. Under Single sign-on, select SAML and configure:
   • Identifier (Entity ID): Use the same value as the Entity ID in API7 (e.g., https://dashboard.example.com).
   • Reply URL (ACS URL): Use the ACS URL from API7 (e.g., https://dashboard.example.com/api/saml/<LOGIN_OPTION_ID>/acs).
5. In the SAML Signing Certificate section, find the App Federation Metadata URL and use it as the Identity Provider Metadata URL in API7.

Attribute Mapping Configuration

Azure AD uses full URI-style claim names by default:

API7 Field	SAML Claim Name
username	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Role Mapping

1. Under App roles, create roles (e.g., Admin).
2. Under Enterprise applications > Users and groups, assign the role to users.
3. In Azure, navigate to Single sign-on > Attributes & Claims and add a claim that includes the assigned role (e.g., claim name Role).
4. In API7, use the mapping rule: Attribute $.Role, Operation Exact Match, Value Admin.

Okta

IdP Setup

1. In the Okta Admin Console, navigate to Applications > Applications.
2. Click Create App Integration and select SAML 2.0.
3. Configure the SAML settings:
   • Single sign-on URL: Use the ACS URL from API7 (e.g., https://dashboard.example.com/api/saml/<LOGIN_OPTION_ID>/acs).
   • Audience URI (SP Entity ID): Use the same Entity ID as in API7 (e.g., https://dashboard.example.com).
   • Name ID format: EmailAddress or Unspecified.
4. Under Attribute Statements, configure:
   • username → user.login
   • email → user.email
   • name → user.firstName + " " + user.lastName
5. After creating the app, find the Identity Provider metadata URL under the Sign On tab.
6. Assign users to the application under the Assignments tab.

Attribute Mapping Configuration

API7 Field	SAML Attribute
username	username
email	email
name	name

Role Mapping

1. Under Attribute Statements, add a role attribute (e.g., mapped to a user profile attribute or group membership).
2. In API7, use the mapping rule: Attribute $.role, Operation Exact Match, 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 OIDC
• SSO with LDAP
• SSO Overview (Enterprise Feature)
• Roles and Permission Policies
• Role-Based Access Control