Support Developer Portal SSO

API7 Developer Portal supports Single Sign-On (SSO) to provide a seamless and secure login experience. This enhances usability and security by allowing users to authenticate through your organization’s Identity Provider (IdP).

SSO is typically not recommended for public developers, as it would require them to have accounts within your organization’s IdP. The Developer Portal’s SSO configuration is separate from the API7 Dashboard SSO, which is used to log in and manage API7 Enterprise settings such as gateway configurations and API providers.

Create a Login Option

API7 Developer Portal supports Single Sign-On (SSO) using multiple protocols. By integrating with existing user systems, it allows internal developers to access API7 Developer Portal without creating a new account.

LDAP

IdP Configuration

Define the directory structure. Plan your Base DN and organizational units (OUs). For example:

# Base DN: dc=example,dc=com

# Root entry
dn: dc=example,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: Example Company
dc: example

# LDAP admin account (used as Bind DN)
dn: cn=read-only-admin,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: read-only-admin
sn: Admin
uid: read-only-admin
userPassword:: e1NTSEF9JGFsdGhvdmVyJGFsdGhvdmVy
mail: admin@example.com

# User accounts
dn: uid=alice,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
uid: alice
cn: Alice Johnson
sn: Johnson
mail: alice.johnson@example.com
telephoneNumber: 555-123-4567

dn: uid=bob,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
uid: bob
cn: Bob Smith
sn: Smith
mail: bob.smith@example.com
telephoneNumber: 555-234-5678

# Group entry
dn: ou=admins,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
ou: admins
cn: Admins
uniqueMember: uid=alice,dc=example,dc=com
uniqueMember: uid=bob,dc=example,dc=com

API7 Developer Portal 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: The LDAP server port, for example, 389 (non-SSL) or 636 (SSL).
• Base DN: The distinguished name that defines the root of the LDAP directory tree where user searches start, for example, dc=example,dc=com.
• Bind Distinguished Name: The distinguished name used to perform LDAP search for users, for example, cn=read-only-admin,dc=example,dc=com. This account must have permission to read or search for the users being authenticated.
• Bind Password: The credential used by the LDAP client to authenticate as the bind DN (user account) when connecting to the LDAP server.
• Identifier: The attribute used to identify LDAP users, for example, uid.
• Attributes Mapping: API7 user fields mapping to LDAP attributes. For example:
  • username: uid
  • email: mail
  • name: cn

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), refer to your IdP's documentation and 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 Developer Portal 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 Developer Portal, for example, https://api7-portal.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 Developer Portal URL, for example http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout?post_logout_redirect_uri=https://api7-portal.your-company.com.
• Attributes Mapping: API7 user fields mapping to OIDC claims. For example:
  • username: preferred_username
  • email: email
  • name: name

4. Click Add.

SAML

IdP Configuration

This section describes 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 API7 Developer Portal Configuration 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 Developer Portal URL, for example, https://api7-portal.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://api7-portal.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs.

The configuration is now complete. Developers should now be able to log in to API7 Developer Portal with the new login option.

API7 Developer Portal 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 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 Developer Portal address, for example, https://api7-portal.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 Developer Portal URL, for example, https://api7-portal.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://api7-portal.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs.
6. Return to the IdP Configuration above, step 6.

A new login option should now appear on the Developer Portal login page, allowing users to authenticate with the IdP.

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 Developer Portal. 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 Developer Portal 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 Developer Portal.

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
  • Developers