Dashboard SSO using SAML

Single Sign-On (SSO) allows users to access multiple applications using a single set of credentials, streamlining the authentication process. In API7 Enterprise, SSO supports multiple protocols and provides the capability to manage users by importing them from existing identity providers.

This guide walks you through configuring Single Sign-On (SSO) for the API7 Enterprise Dashboard using Microsoft Entra ID (Azure AD) as the identity provider via the SAML protocol, and setting up role and permission boundary mappings for imported users.

Set Up SSO Integration

This section guides you through configuring Single Sign-On (SSO) for the API7 Enterprise Dashboard using Microsoft Entra ID (Azure AD) as the identity provider.

Configure Microsoft Entra ID

This section describes example configuration in Microsoft Entra ID (Azure AD). If you are using a different identity provider (IdP), refer to your IdP's documentation and adjust the configuration accordingly.

1. In Azure Portal, navigate to Microsoft Entra ID.
2. Create an enterprise application. Select the option to create your own application:
   1. Fill in the name of the app, for example API7.
   2. Select the Integrate any other application you don't find in the gallery (Non-gallery) option.
3. In the application, select the users and groups tab to add all necessary users and groups. Only the users and groups added can log into API7 via SSO.
4. In the application, navigate to the single sign-on tab and enable SAML. After SAML is enabled, find the following information for your app:
   1. App Federation Metadata URL: The URL that exposes SAML configuration details, for example, https://login.microsoftonline.com/<TENANT_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>.
   2. Claim Names: Unique identifiers for user attributes in a SAML token, used to map identity provider data to corresponding fields in the service provider. Find the claim names for username and email, for example, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name and http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
5. Complete the Create a Dashboard Login Option instructions below, as the subsequent configurations require information from API7.
6. In the application, navigate to the single sign-on tab and edit the Basic SAML Configuration:
   1. Identifier (Entity ID): A unique identifier used to represent a specific entity in a SAML federation. This identifier must be unique and consistent between API7 and the IdP. It is recommended to use the API7 Dashboard URL, for example, https://dashboard.your-company.com, although any unique string can be used.
   2. Reply URL (Assertion Consumer Service URL): The endpoint on the Service Provider where the Identity Provider sends the SAML authentication response after a user successfully signs in, for example, https://dashboard.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs.

The configuration is now complete. You should now be able to log in to API7 Dashboard with the new login option.

Create a Dashboard Login Option

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 SAML.
• Identity Provider Metadata URL: The identity provider metadata URL, for example, https://login.microsoftonline.com/<TENANT_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>.
• Service Provider Root URL: The root URL of your Service Provider. Typically, it is the API7 Dashboard address, for example, https://dashboard.your-company.com.
• Entity ID: A unique identifier used to represent a specific entity in a SAML federation. This identifier must be unique and consistent between API7 and the IdP. It is recommended to use the API7 Dashboard URL, for example, https://dashboard.your-company.com, although any unique string can be used.
• Attributes Mapping: API7 user fields mapping to SAML claims. For example:
  • 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
• Terminates IdP Session on Logout: You can optionally enable terminating IdP session on logout.

4. Click Add.
5. In the new SAML login option, find the Service Provider ACS URL, for example, https://dashboard.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs.
6. Return to the Configure Microsoft Entra ID above, step 6.

If all the above steps are completed, 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, log in as the admin user, 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 and permission boundaries 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 User Roles and Permissions

When automatic mappings are enabled, 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.

info

If you prefer to manually update roles and permission boundaries for users (best suited for ad-hoc adjustments), see Update a User Role and Set Permission Boundary.

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.

Configure Microsoft Entra ID

Role and permission boundary mappings rely on values configured in the IdP and passed to API7 Enterprise. The same IdP configuration applies when setting up mappings for roles and permission boundaries.

For instance, to assign an attribute to a user in Microsoft Entra ID, you can configure it either user attribute or via group membership. This section describes example configuration in Microsoft Entra ID (Azure AD). If you are using a different identity provider (IdP), refer to your IdP's documentation and adjust the configuration accordingly.

tip

In a production environment, it is recommended to implement fine-grained permission controls. For example, you can create detailed permissions in API7 and bind them to a role, then use the API7 Login Options settings to explicitly map each Microsoft Entra ID user to the corresponding API7 role. Finally, assign the appropriate role to each user in Microsoft Entra ID to ensure proper access control.

Configure as a User Attribute

1. In Microsoft Entra ID, go to Users and add admin as the job title for users who should later have the API7 admin role.
2. In your enterprise application, navigate to the single sign-on tab and edit the Attributes & Claims.
3. Select Add new claim. Configure the name as position, select Attribute as the source, and use user.jobtitle as the Source attribute.

This assigns the position attribute with the value admin in the SAML assertion for these users. In API7 Dashboard, you can use position, Exact Match, admin mapping rule. See Configure Mappings in Dashboard for configuration steps.

Configure via Group Membership

1. In Microsoft Entra ID, go to Groups and create a new security group called admin. Note down the group ID, for example, 40cec5d2-72f2-43f5-b096-b4189012a386.
2. Add users to the group. Members in this group should later have the API7 admin role.
3. In your enterprise application, navigate to the single sign-on tab and edit the Attributes & Claims.
4. Select Add a group claim. Select Security groups as the type of groups, and use Group ID as the Source attribute.

This creates a new claim with the name http://schemas.microsoft.com/ws/2008/06/identity/claims/groups.

In API7 Dashboard, you can use http://schemas.microsoft.com/ws/2008/06/identity/claims/groups, Exact Match in Array, 40cec5d2-72f2-43f5-b096-b4189012a386 mapping rule. See Configure Mappings in Dashboard for configuration steps.

Configure Mappings in Dashboard

This section describes how to configure role and permission boundary mappings in the API7 Enterprise Dashboard to define how user attributes from the identity provider are translated into access controls.

Enable Role Mappings

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. The attribute should correspond to an attribute in the SAML assertion, for example, position.
• 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.

Enable Permission Boundary Mappings

1. Select Organization from the top navigation bar, then choose Settings.
2. Select the previously created 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. The attribute should correspond to an attribute in the SAML assertion, for example, position.
• 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 any users are still using this login option. If so, notify them before making any changes.
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