Log in to API7 Dashboard with SSO

Single Sign-On (SSO) allows users to log in once and access multiple systems without re-entering credentials. It improves efficiency, enhances user experience, and strengthens security by eliminating the need for multiple passwords.

In API7 Enterprise, you can use multiple login options simultaneously. It is possible to create users within API7 while also importing them from other existing systems.

Architecture

Take LDAP as an example:

1. User Login Request: Users enter their username and password when logging into API7 Enterprise.
2. LDAP Verification: API7 Enterprise transfers the credentials provided by the user to the LDAP server for verification.
3. Authentication: The LDAP server verifies whether the user's credentials match the user information stored in the LDAP directory.
4. Authorization: If verification is successful, the LDAP server returns authorization information to API7 Enterprise, and the system authorizes the user to access corresponding resources based on this information.
5. Accessing Resources: Users access API7 Enterprise with the verified identity without having to re-enter credentials.

Create a Login Option

API7 Enterprise supports Single Sign-On with the following implementations. Integrating API7 Enterprise with other user systems enables you to log your existing users into API7 Enterprise without signing up for a new API7 account.

LDAP

IdP Configuration

Coming soon.

API7 Dashboard Configuration

1. Select Organization from the top navigation bar, then choose Settings.
2. Click Add Login Option.
3. Fill in the configuration:

• Name: the unique login name. The name should be identifiable for users. For example, if you configure the name to be Employee Account, you will see Login with Employee Account option in the Dashboard login page.
• Provider: choose LDAP.
• Host: the LDAP host domain. For example, ldap.example.com.
• Port: For example, 389 (non-SSL) or 636 (SSL).
• Base Distinguished Name: For example, ou=users,dc=org,dc=example.
• Bind Distinguished Name: the LDAP Bind Distinguished Name (DN) used to perform LDAP search for the user. This LDAP Bind DN should have permissions to search for the user being authenticated. For example, cn=admin,dc=org,dc=example.
• Bind Password: the LDAP bind password used to authenticate with the LDAP server.
• Identifier: the attribute used to identify LDAP users. For example, cn.
• Attributes Mapping: map API7 internal fields to related LDAP attributes to seamlessly integrate and synchronize data.

4. Click Add.

OIDC

IdP Configuration

This section describes configuration in Keycloak 26.3.3. If you are using a different version of Keycloak or a different identity provider (IdP), adjust the configuration accordingly.

1. Create a realm, for example quickstart-realm.
2. Create a client, for example apisix-quickstart-client. In the client:
   1. Enable client authentication, which sets the access type to be confidential.
   2. Enable standard flow (authorization code grant).
   3. Configure the redirect URL, for example *.
   4. After creating the client, navigate to the Credentials tab and obtain the client secret. Record this value for later use.
3. Create a user. In the user:
   1. Create a user password.
   2. Configure the user email, first name, and last name as needed.
4. In the realm settings, find the link to the discovery document. In the discovery document, record these values for later use:
   1. The issuer URL, for example, http://192.168.10.101:8080/realms/quickstart-realm.
   2. The end_session_endpoint URL, for example, http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout.

API7 Dashboard Configuration

1. Select Organization from the top navigation bar, then choose Settings.
2. Click Add Login Option.
3. Fill in the configuration:

• Name: The unique login name. The name should be identifiable for users. For example, if you configure the name to be Employee Account, you will see Login with Employee Account option in the Dashboard login page.
• Provider: Choose OIDC.
• Issuer: The issuer URL of the OpenID Connect provider, for example, http://192.168.10.101:8080/realms/quickstart-realm.
• Client ID: The unique identifier of your application assigned by the OIDC provider, for example apisix-quickstart-client.
• Client Secret: Secret key used for authentication assigned by the OIDC provider.
• Request Scope: Scope values requested from the OIDC provider, which define the level of access and the claims included in the tokens. The openid scope is mandatory for all OIDC requests. Additional scopes can be included as needed, separated by spaces. For example, openid profile email.
• Root URL: The root address through which users access the API7 Dashboard, for example, https://dashboard.your-company.com. This URL must exactly match what users enter in their browsers, including the protocol (HTTP or HTTPS) and the port number if it differs from the standard ports (80 or 443).
  • The callback URL will be automatically generated as <Root_URL>/api/oidc/<LOGIN_OPTION_ID>/callback.
• SSL verify: Whether the OIDC provider’s SSL/TLS certificate should be validated.
• Logout URL: The URL that ends the user session and redirects them to the sign-in page. This should be the end_session_endpoint URL with the post_logout_redirect_uri query parameter set to the API7 Dashboard URL, for example http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout?post_logout_redirect_uri=https://dashboard.your-company.com.
• Attributes Mapping: API7 user fields mapping to OIDC claims.
  • username: preferred_username
  • email: email
  • name: name

4. Click Add.

SAML

IdP Configuration

Coming soon.

API7 Dashboard Configuration

1. Select Organization from the top navigation bar, then choose Settings.
2. Click Add Login Option.
3. Fill in the configuration:

• Name: the unique login name. The name should be identifiable for users. For example, if you configure the name to be Employee Account, you will see Login with Employee Account option in the Dashboard login.
• Provider: choose SAML.
• Identity Provider Metadata URL: URL used to obtain information about the Identity Provider, such as its public key, supported SAML versions, signature algorithms, etc. For example, https://idp.example.com/metadata.
• Service Provider Root URL: the entity that requests authentication and authorization from the Identity Provider (IdP). For example, https://sp.example.com.
• Entity ID: a unique identifier for the Service Provider (SP) or Identity Provider (IdP) entity. It typically serves as a globally unique identifier for the entity within the SAML federation. For example, https://sp.example.com/saml/metadata.

4. Click Add.

A new login option should now appear on the API7 Dashboard login page, allowing you to authenticate using the user created in your IdP. After the user signs in, navigate to Organization in the top navigation bar, then select Users to view the user.

Note that this user has no roles assigned yet, and therefore lacks permissions to manage resources in the Dashboard.

important

Deleting a user in the Dashboard removes all roles assigned in the API7 Dashboard, but the user can still log in as a new user. To fully revoke access to the API7 Dashboard, the user must be removed from the IdP.

Manage Roles and Permissions for IdP Users

To manage user roles and permission boundaries, you can use the API7 Dashboard to configure them manually or set up automatic mapping.

Manual Update

See update user role and set permission boundary for how to manually update roles and permission boundaries for users in API7 Dashboard.

caution

Manual changes in the Dashboard will be overridden when role mapping or permission boundary mapping are enabled. Manual configuration is best suited for ad-hoc adjustments.

Automatic Mapping

Imported users can be automatically assigned roles and permission boundaries based on attributes from their identity provider, such as title, position, or department. These roles and permission boundaries are synchronized each time the user logs in, ensuring consistent access. A login option’s mapping can include multiple rules that collectively determine a user’s access privileges.

important

Automatic mappings take precedence over manually modified roles and permission boundaries. When mappings are active, manual changes in the Dashboard will be overwritten the next time the user logs in.

IdP Configuration

Role and permission boundary mappings rely on values configured in the IdP and passed to API7 Enterprise. The configuration process is the same for both. Update example names and values as needed, depending on which you are configuring.

LDAP

Coming soon.

OIDC

This section describes configuration in Keycloak 26.3.3. If you are using a different version of Keycloak or a different identity provider (IdP), adjust the configuration accordingly.

To assign the position attribute with the value admin to a user in Keycloak, you can configure it either as a user attribute or via group membership.

Configure as a User Attribute

1. Enable Unmanaged Attributes from the Realm Settings.

2. Navigate to the user in Keycloak.

3. Go to the Attributes tab.

4. Add a new attribute, for example, with Key set to position and Value set to admin.

5. Navigate to Client Scopes and select a scope to which you want to add a mapper, for example, profile. Note that the selected scope should be configured in the API7 Dashboard Request Scope.

6. Add a mapper by configuration. Select User Attribute from the list, and fill in the configuration:

   • Name: Name of the mapper, for example, position.
   • User Attribute: Name of the user attribute, for example, position.
   • Token Claim Name: Name of the claim to insert into the token, for example, position.
   • By default, this attribute will be included in the UserInfo, which API7 Enterprise uses to obtain user attributes. For example:

   {
     "email":"johndoe@api7.ai",
     "email_verified":false,
     "name":"John Doe",
     "preferred_username":"johndoe",
     "sub":"b724c7ed-ad74-4330-9365-e599fdfbffcc",
     ...
     "position":"admin"
   }

In API7 Dashboard, you can use $.position, Exact Match, admin mapping rule. See the API7 Dashboard Configuration for configuration steps.

Configure via Group Membership

1. Navigate to Groups in Keycloak.

2. Create a new group, for example, admin.

3. Add the user to this group.

4. Navigate to Client Scopes and select a scope to which you want to add a mapper, for example, profile. Note that the selected scope should be configured in the API7 Dashboard Request Scope.

5. Add a mapper by configuration. Select Group Membership from the list, and fill in the configuration:

   • Name: Name of the mapper, for example, groups.
   • Token Claim Name: Name of the claim to insert into the token, for example, groups.
   • By default, this attribute will be included in the UserInfo, which API7 Enterprise uses to obtain user attributes. For example:

   {
     "email":"johndoe@api7.ai",
     "email_verified":false,
     "name":"John Doe",
     "preferred_username":"johndoe",
     "sub":"b724c7ed-ad74-4330-9365-e599fdfbffcc",
     ...
     "groups": ["/admin"]
   }

In API7 Dashboard, you can use $.groups[*], Contains String, admin as the mapping rule. See the API7 Dashboard Configuration for configuration steps.

SAML

Coming soon.

API7 Dashboard Configuration

Role Mapping

1. Select Organization from the top navigation bar, then choose Settings.
2. Select the login option.
3. Enable Role Mapping.
4. Fill in the configuration:

• Internal Role: The role in API7 Enterprise to assign. For example, Super Admin.
• Role Attribute: The JSONPath to the corresponding attribute in the IdP. For example, $.position.
  • In LDAP, the attribute should correspond to an attribute in the user entry.
  • In OIDC, the attribute should correspond to a claim in the UserInfo.
  • In SAML, the attribute should correspond to an attribute in the SAML assertion.
• Operation: The comparison method used to match the attribute value. For example, Exact Match.
• Role Value: The value of the IdP attribute. For example, admin.

5. Click Enable.

Now all users with the position attribute set to admin in the IdP will automatically be assigned the Super Admin role upon their next login.

Note that role mapping is dynamic. If a user's attribute changes in the IdP, their role will be automatically updated based on the role mapping rules the next time they log in to API7 Enterprise.

Permission Boundary Mapping

1. Select Organization from the top navigation bar, then choose Settings.
2. Choose the login option.
3. Enable Permission Boundary Mapping.
4. Fill in the configuration:

• Permission Policy: The permission policy to assign in API7 Enterprise. For example, you can create a policy such as Admin License Restricted, which grants full resource access while restricting license updates; and apply the policy to this field.
• Permission Boundary Attribute: The JSONPath to the corresponding attribute in the IdP. For example, $.position.
  • In LDAP, the attribute should correspond to an attribute in the user entry.
  • In OIDC, the attribute should correspond to a claim in the UserInfo.
  • In SAML, the attribute should correspond to an attribute in the SAML assertion.
• Operation: The comparison method used to match the attribute value. For example, Exact Match.
• Permission Boundary Value: The value of the IdP attribute. For example, admin.

5. Click Enable.

Now all users with the position attribute set to admin in the IdP will be automatically assigned the Admin License Restricted permission boundary upon their next login.

Note that permission boundary mapping is dynamic. If a user's attribute changes in the IdP, their permission boundary will be automatically updated based on the mapping rules the next time they log in to API7 Enterprise.

Synchronize User Data from IdP (SCIM)

SCIM (System for Cross-domain Identity Management) is a protocol that can be used to synchronize user and group information from an Identity Provider (IdP) to API7 Enterprise. This eliminates the need to manually manage users and groups across multiple systems, saving time and reducing the risk of errors.

With SCIM Provisioning, API7 Enterprise automatically synchronizes user data whenever a new user is registered or deleted in your IdP.

1. Select Organization from the top navigation bar, then choose Settings.
2. Enable SCIM Provisioning.
3. Copy the API7 SCIM Endpoint URL and SCIM Token.
4. Configure SCIM in your IdP, if supported.

Delete a Login Option

warning

Deleting a login option will remove all users associated with that option in API7 Dashboard.

1. Select Organization from the top navigation bar, then choose Users.
2. Check if there are any users still using this login option. If yes, notify them first.
3. Select Organization from the top navigation bar, then choose Settings.
4. Click Delete of the target login option.

Additional Resources

• Key Concepts
  • Roles and Permission Policies
• Getting Started
  • Create Custom Role
• Reference
  • Permission Policy Actions and Resources
  • Permission Policy Examples