Configure API Portal single sign-on

Configure single sign-on (SSO) and enable it for your API Portal users.

8 minute read


  • You must have a third-party IdP installed and running.
  • The IdP posts SAML assertions to API Portal. When configuring the IDP for a new API Portal client, you must set the post back addresses to API Portal.
  • You must always use fully qualified domain names (FQDNs) for the host name. Avoid using IP addresses or localhost in the configuration.

The following prerequisites apply to organizations in API Manager:

  • Before a user can authenticate successfully using SSO, the API Portal organization associated with the SSO user must exist.
  • An API Manager administrator user can add the organizations in advance.
  • When configuring the file service-provider-apiportal.xml, ensure that the SSO user only ever belongs to one organization.

Configuration files

To configure API Portal SSO, create the following files in your API Gateway instance folder. For example:

  • service-provider-apiportal.xml: This file defines how API Portal interacts in the SSO, the Service Provider (SP), the SAML Identity Provider (IdP), and the mappings that can be made by the SAML IdP. In this case the SP is API Manager. For more information, see Create a service-provider-apiportal.xml file.
  • A keystore (for example, sso.jks): This is the truststore generated by an administrator and referenced in service-provider-apiportal.xml. It contains the key that the SSO agent uses to sign requests. The exported public key must be stored by the IdP. For more information, see Manage IdP certificates.
  • idp.xml (optional): This file is required if you are specifying the IdP by file. For more information, see Specify the IdP by file.
  • jvm.xml: This file is located at INSTALL_DIR/apigateway/conf, and can be used to configure the SSO cookie domain name. It is only required when using a load balancer. See Configure the SSO cookie domain name.

Your API Gateway installation includes sample files that may help you configure API Portal SSO. These are located in the following folder:


For more details, see API Manager configuration files.

Set up a keystore

Set up a keystore containing a key pair to your API Gateway instance. For more details, see Configure the IdP.

Create a service-provider-apiportal.xml file

To create a service-provider-apiportal.xml file to your API Gateway instance, use the following sample file included in the API Gateway installation:


The sample file contains useful information about what sections you must change to match your environment.

  1. To enable reverse proxying, check the following:

    • excludeHostInEndpointURICheck is set to true.
    • relaxedEndpointURICheckHostDetails is not present, or if present, is set to your API Portal host (https://<FQDN>:<port>).
  2. In the ServiceProvider section, update the keystore, keystorePassphrase, and keyAlias fields with the correct values for your keystore.

    For example, if you generated a keystore called sso.jks with a passphrase abc123 and an alias called ssokey, the settings are as follows:

  3. In the SamlIdentityProvider section, update the Mappings section with the mapping of IdP attributes to API Manager attributes. For more information on the mapping syntax, see Mapping syntax.

  4. In the SamlIdentityProvider section, change references to to the FQDN and port of your IdP.

  5. In the SamlIdentityProvider section, set the metadataUrl field as detailed in Specify the IdP by file or Specify the IdP by URL, and save the configuration file.

For more information on the elements in the service-provider-apiportal.xml configuration file, see configuration file reference.

Specify the IdP by file

When the IdP is specified by file, the idp.xml file must exist in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf). In this case, service-provider-apiportal.xml refers to this file on disk.

To specify the IdP by file in service-provider-apiportal.xml, follow these steps:

  1. In the SamlIdentityProvider section, set the metadataUrl field to the value ./idp.xml.

    The following example shows a sample extract from the service-provider-apiportal.xml file for Keycloak. The metadataUrl refers to the file idp.xml:

  2. Create an idp.xml file to your API Gateway instance folder using the following templates:

    • For Shibbloteh, use the template provided in INSTALL_DIR/apigateway/samples/sso/ShibbolethIDP/idp.xml.
    • For Keycloak, enter the URL of the Keycloak realm you are configuring (for example,https://<Keycloak FQDN>:<port>/auth/realms/<realm>) to your browser, and use the shown content as the template for the idp.xml. You can also use a utility such as Wget to save the content as a file.

    Replace the placeholders in the file with the details of your IdP.

Specify the IdP by URL

When the IdP is specified by URL, the IdP file is not stored locally. Instead, service-provider-apiportal.xml references it using a URL.

To specify the IdP by URL in service-provider-apiportal.xml, in the SamlIdentityProvider section, set the metadataURL field to the metadata URL of the IdP.

The following example shows an extract from a service-provider-apiportal.xml file for a Keycloak IdP. The metadataUrl refers to a URL.


A sample of a service-provider-apiportal.xml file that uses an IdP specified by URL is included in the INSTALL_DIR/apigateway/samples/sso/keycloak folder.

When specifying an IdP by URL, you might need to set up a truststore JKS file:

  • sso.jks – Contains the key used by the SSO agent to sign requests. This key needs to go to the IdP.
  • truststore.jks – This is a separate truststore that is used for HTTPS communication between the SSO agent and the IdP while retrieving metadata online.

You can use the same keystore for all of the operations.

Configure SSO in Policy Studio

After configuring and saving service-provider-apiportal.xml, you must configure the SSO connection between your API Gateway and API Portal. This configuration is the same as when configuring API Manager SSO. For more details, see Configure SSO in Policy Studio.

Configure SAML endpoint URLs

After configuring the SSO, you must define the SAML endpoint of API Portal in the IdP. This endpoint is the URL that receives SAML assertions from the IdP.

In the following example, the IdP is Keycloak. Depending on your IdP, the UI might be different, but you must define the endpoint URLs regardless of which IdP you use. For more details, see the documentation of your IdP.

Open your IdP client, locate and set the following:

Assertion Consumer Service POST Binding URL:

  • For versions earlier than API Portal 7.7 September: https://<API Portalhost FQDN>/api/portal/v1.3/sso/externallogin/post
  • For API Portal 7.7 September and later: https://<API Portalhost FQDN>/api/portal/v1.4/sso/externallogin/post


  • For versions earlier than API Portal 7.7 September: https://<API Portal host FQDN>/api/portal/v1.3/sso/externallogout/post
  • For API Portal 7.7 September and later: https://<API Portal host FQDN>/api/portal/v1.4/sso/externallogout/post

Logout Service Redirect Binding URL:

  • For versions earlier than API Portal 7.7 September: https://<API Portal host FQDN>/api/portal/v1.3/sso/externallogout/post
  • For API Portal 7.7 September and later: https://<API Portal host FQDN>/api/portal/v1.4/sso/externallogout/post

An example on configuring the endpoints

You must configure the endpoint URLs separately for both API Manager and API Portal. For more details, see Configure API Manager SSO.

Additional configuration in API Manager and API Gateway

Because API Portal is dependent of API Manager and API Gateway, you must configure some things outside API Portal. These configurations are the same when configuring API Manager SSO, so if you have already configured API Manager SSO, or are planning to do so, you do not have to repeat them separately for API Portal.

Manage IdP certificates

API Portal relies on API Manager to process the SAML assertions in the requests. API Manager uses a certificate to sign SAML requests. The IdP requires the public key to verify the validity and provenance of the SAML requests from API Manager, so you must import the public key to the IdP. For more details, see Configure the IdP.

This implementation of SSO uses a cookie, which is created on the API Gateway server and sent to the client’s browser. One property of this cookie is the domain name. The default domain name is the API Gateway host name.

If the API Gateway is hidden behind a load balancer, you might need to change the cookie domain name because the client’s browser is not aware of the internal API Gateway host name and therefore might not accept the cookie. For more details, see Configure the SSO cookie domain name.

Enable SSO in API Portal

After configuring service-provider-apiportal.xml and the single sign-on (SSO) connection in Policy Studio, enable SSO in API Portal.

  1. In the Joomla! Administrator Interface (JAI), click Components > API Portal > Single-Sign-On.
  2. Click Yes to enable SSO login.
  3. In SSO Client Entity ID, enter the entityId you defined for API Portal in service-provider-apiportal.xml.
  4. In SSO Whitelist, enter the host name or IP address of your IdP to allow requests to the IdP (for example, If you do not add your IdP to this field, all requests to your IdP will be rejected by API Portal.
  5. Click Save.

Change API Portal SSO login path

The default SSO login URL is https://<FQDN>:<port>/sso, where <FQDN> is the fully qualified domain name of the machine running API Portal, and <port> is the API Portal listening port. To modify the SSO login URL:

  1. In JAI, click Components > API Portal > Single-Sign-On.
  2. In SSO Path, replace the default value /sso with the new path (for example, /newpathresults in a new SSO login URL of https://<FQDN>:<port>/newpath.
  3. Click Save.