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.

Prerequisites

1. Obtain a user account with Super Admin role.

Integrate with SSO

API7 Enterprise supports Single Sign-On with 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

1. Select Organization from the top navigation bar, then choose Settings.
2. Click Add Login Option.
3. Fill in the Add Login Option form:
   1. Name: the unique login name, must be identical to users. For example Employee Account.
   2. Provider: choose LDAP.
   3. Host: the LDAP host domain. For example, ldap.example.com.
   4. Port: For example, 1563.
   5. Base Distinguished Name: For example, oc=users,dc=org,dc=example.
   6. 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.
   7. Bind Password: the LDAP bind password used to authenticate with the LDAP server.
   8. Identifier: the attribute used to identify LDAP users. For example, cn.
   9. Attributes Mapping: map API7 internal fields to related LDAP attributes to seamlessly integrate and synchronize data.
4. Click Add.

OIDC

1. Select Organization from the top navigation bar, then choose Settings.
2. Click Add Login Option.
3. Fill in the Add Login Option form:
   1. Name: the unique login name, must be identical to users. For example Employee Account.
   2. Provider: choose OIDC.
   3. Issuer: the identifier of the OpenID connect provider. For example, https://accounts.example.com.
   4. Client ID: the unique identifier of your application, assigned by the OIDC provider. For example, API7.
   5. Client Secret: secret key used for authentication, assigned by the OIDC provider.
   6. Request Scope: Access tokens often possess different scopes, which limit their usage. For example, profile,email.
   7. Root URL: the URL used to access API7 for generating callback URL. For example, https://auth.example.com/oidc.
   8. SSL verify: default value is open.
4. Click Add.

SAML

1. Select Organization from the top navigation bar, then choose Settings.
2. Click Add Login Option.
3. Fill in the Add Login Option form:
   1. Name: the unique login name, must be identical to users. For example Employee Account.
   2. Provider: choose SAML.
   3. 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.
   4. Service Provider Root URL: the entity that requests authentication and authorization from the Identity Provider (IdP).For example, https://sp.example.com.
   5. 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.

Use Cases

Login with SSO

Once you have configured the Login Options, external users will be able to directly log in to the API7 Dashboard without the need for signing up.

1. Visit the API7 Dashboard at http://localhost:7080.
2. Choose from the login option name, for example Login with Employee Account.
3. Enter your username and password.
4. Click Login.

Delete Imported Users

If you delete a user with SSO login options in Users, it only means that the user will lose all their roles. However, they can still log in to the API7 Dashboard as a new user. To completely block their access to the API7 Dashboard, you must delete them from the original system.

Sync User Data from IdP

SCIM (System for Cross-domain Identity Management) is a protocol that can be used to synchronize user and group information from the original Identity Provider (IdP) to API7 Enterprise. This can eliminate the need to manually manage user and group information in multiple systems, which can save time and reduce 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. Click Enable of SCIM Provisioning.
3. Copy the API7 SCIM Endpoint URL and SCIM Token.
4. Configure Your IdP (if it supports SCIM):

• Log in to your IdP administration console.
• Locate the SCIM configuration settings (these may vary depending on your IdP).
• Paste the copied API7 SCIM Endpoint URL and SCIM Token into the appropriate fields.
• Save your configuration changes and configure them on your IdP side (make sure your IdP supports SCIM protocol).

Assign Roles for Imported Users

Without Setting Role Mapping

All newly imported users will be assigned the Viewer role by default until the Super Admin assigns them different roles.

Set Role Mapping

Imported users are automatically assigned roles based on relevant attributes from their original system (title, position, department, etc.). These roles are synchronized and refreshed upon login for seamless access. Role mapping of a login option can involve multiple rules that work together to determine user access. If the user does not match any of the rules, the user will be assigned the Viewer role by default.

info

Enabling role mapping for a login option in API7 disables manual role assignment for all associated users. This ensures consistent role management and avoids potential conflicts.

1. Select Organization from the top navigation bar, then choose Settings.
2. Choose the login option by click its name.
3. Click Enable of Role Mapping.
4. Fill in the Enable Role Mapping form:
   • Internal Role: For example, Super Admin.
   • Role Attribute: For example, Position.
   • Operation: For example, =.
   • Role Value: For example, Team Leader.
5. Click Enable.

Now all user with Position = Team Leader from IdP will gain Super Admin role, while other users will gain the default Viewer role, because they did not match the rule. If a user's position in the IdP transitions from "Team Leader" to "Team Member, their role in API7 will automatically update to "Viewer" upon their next login.

Delete a Login Option

danger

Deleting a login option will result in the removal of all users associated with it.

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.
5. Double confirm.