Configure API Portal SSO

This topic describes how to configure API Portal single sign-on (SSO).

The configuration steps are as follows:

  1. Set up a keystore
  2. Create a service-provider-apiportal.xml file
  3. Specify the IdP
  4. Configure SSO in Policy Studio
  5. Configure SAML endpoint URLs

In addition, there is some additional configuration you must complete before the SSO is operational. See Additional configuration in API Manager and API Gateway.

Prerequisites

To configure API Portal SSO:

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

API Portal implementation behavior

When using API Portal SSO, be aware of the following:

  • SSO authenticated users cannot change their own passwords.
  • To log in using SSO, users cannot use the standard login URL (https://<FQDN>:<port>). Instead, users must use the API Portal SSO login URL. The default URL is:
  •  https://<FQDN>:<port>/sso

    The <FQDN> is the FQDN of the machine where API Portal is running, and <port> is the API Portal listening port (for example, https://portal.example.com:8080/sso).

  • You can change the SSO URL in the Joomla! Admin Interface (JAI). For more details, see Enable SSO in API Portal.
  • If a user has already authenticated using SSO (for example, by previously logging in to API Manager or Decision Insight), they must still use the SSO login URL for API Portal. If they are already authenticated, they are automatically redirected to the API Portal home page.
  • The mapping of user roles between the IdP and API Portal must be configured manually. For more information, see Mapping syntax.

Configuration files

To configure API Portal SSO, create the following files in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf).

File name Description

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 in the folder INSTALL_DIR/apigateway/conf and can be used to configure the SSO cookie domain name. This file 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:

INSTALL_DIR/apigateway/samples/sso

For more details, see Configuration files in the API Manager User Guide

Set up a keystore

You must first set up a keystore containing a key pair to your API Gateway instance. For more details, see Set up a keystore in the API Manager User Guide.

Create a service-provider-apiportal.xml file

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

INSTALL_DIR/apigateway/samples/sso/keycloak/service-provider-apiportal.xml

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

Note   Do not change any settings with paths containing /sso, unless otherwise instructed.
  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>).

    For more details, see Configuration file elements.

  2. In the ServiceProvider section, update the keystore, keystorePassphrase, and keyAlias fields with the correct values for your keystore:
  3.    <ServiceProvider
          ...
          keystore="conf/<keystore file>"
          keystorePassphrase="<your keystore passphrase>"
          keyAlias="<key alias>"
          ...
       </ServiceProvider> 

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

       <ServiceProvider
          ...
          keystore="conf/sso.jks"
          keystorePassphrase="abc123"
          keyAlias="ssokey"
          ...
       </ServiceProvider> 
  4. 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.
  5. In the SamlIdentityProvider section, change references to keycloak.int.acme.com:8443 to the FQDN and port of your IdP.
  6. In the SamlIdentityProvider section, set the metadataUrl field as detailed in Specify the IdP, then save the configuration file.

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

Specify the IdP

There are two ways you can specify the IdP:

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 of to the value ./idp.xml.
  2. The following example shows a sample extract from the service-provider-apiportal.xml file for Keycloak. The metadataUrl refers to the file idp.xml:
  3.    <SamlIdentityProvider
          entityId="https://keycloak.int.acme.com:8443/auth/realms/Axway"
          metadataUrl="./idp.xml"
          ...
       </SamlIdentityProvider>
  4. 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 an utility such as Wget to save the content as a file.

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

For more details, see Set up a keystore in the API Manager User Guide.

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.

   <SamlIdentityProvider
      entityId="https://keycloak.int.acme.com:8443/auth/realms/Axway"
      metadataUrl="https://keycloak.int.acme.com:8443/auth/realms/Axway/protocol/saml/descriptor"
      ...          
   </SamlIdentityProvider>

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.
Tip   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 in the API Manager User Guide.

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. Depeding 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.

  1. Open your IdP client.
  2. Locate and set the following:
    • Assertion Consumer Service POST Binding URL: https://<API Portalhost FQDN>/api/portal/v1.3/sso/externallogin/post
    • logout-service-post-binding-url: https://<API Portal host FQDN>/api/portal/v1.3/sso/externallogout/post
    • Logout Service Redirect Binding URL: https://<API Portal host FQDN>/api/portal/v1.3/sso/externallogout/post

    An example screenshot 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 in the API Manager User Guide.

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 Manage IdP certificates in the API Manager User Guide.

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 in the API Manager User Guide.

Related Links