Configure API Manager SSO

This topic describes how to configure API Manager single sign-on (SSO). It consists of the following:

Prerequisites

To configure API Manager SSO:

  • You must have a third-party IdP installed and running.
  • 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 Manager 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.xml, ensure that the SSO user only ever belongs to one organization.

API Manager implementation behavior

When using API Manager 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 following API Manager SSO login URL:
 https://FQDN:PORT/api/portal/v1.3/sso/login/
  • FQDN is the FQDN of the machine where API Gateway is running, and PORT is the API Manager listening port (for example, https://gateway.example.com:8075/api/portal/v1.3/sso/login/).
  • If a user has already authenticated using SSO (for example, by previously logging in to Decision Insight), they must still use the SSO login URL for API Manager. If they are already authenticated, they are automatically redirected to the API Manager home page at https://FQDN:PORT/home and presented with a view appropriate to their API Manager role.
  • The mapping of user roles between the IdP and API Manager must be configured manually. For more information, see Configure API Manager SSO.
  • If the IdP does not return any role, a user is assigned the default role of User (API consumer) in API Manager. For more information on API Manager roles, see Manage users.

Configuration files

To configure API Manager 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.xml

This file defines 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 Step 2 – Create a service-provider.xml file.

A keystore (for example sso.jks)

This is the truststore generated by an administrator and referenced in service-provider.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 in a load balanced environment.

Sample files

The API Gateway installation includes sample files to help you configure API Manager SSO. These are located in the following folder:

INSTALL_DIR/apigateway/samples/sso

The following sample files are included:

  • ShibbolethIDP folder – This folder contains sample Shibboleth configuration files to help you configure Shibboleth as an IdP. These configuration files are part of the Shibboleth installation and can be found in the respective Shibboleth installation folders. For more information on Shibboleth, see the Shibboleth documentation.
    This folder also contains the following sample files for API Manager:
    • service-provider.xml – A sample file where the IdP is specified by file using idp.xml.
    • idp.xml
  • keycloak folder - This folder contains a sample service-provider.xml file that uses a URL to specify the IdP, in this case Keycloak. For more information, see Specify the IdP by URL. The folder also contains a sample service-provider-apiportal.xml for configuring API Portal SSO. For more details, see Configure API Portal for single sign-on in the API Portal Administrator Guide.

Step 1 – Set up a keystore

To set up a keystore containing a key pair, you can use the Java keytool utility. For more information on the keytool commands and options, see the Java keytool documentation.

Follow these steps:

  1. Change directory to your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf).
  2. Execute keytool to create a keystore. For example, the following command generates a keystore with the alias ssokey in the file sso.jks:
keytool -genkey -alias ssokey -keyalg RSA -keystore sso.jks -keysize 2048
Tip   The values ssokey and sso.jks are used in the sample files included in the API Gateway installation. You can use different values when generating the keystore, however, if you do this you must update the sample files with the new values.

This certificate is used to configure your IdP. For more information, see Manage IdP certificates.

Step 2 – Create a service-provider.xml file

To create a service-provider.xml file you can use either of the sample files included in the API Gateway installation.

  1. In the ServiceProvider section, update the keystore, keystorePassphrase, and keyAlias fields with the correct values for your keystore.
   <ServiceProvider
      ...
      keystore="conf/KEYSTORE_FILE"
      keystorePassphrase="KEYSTORE_PASSPHRASE"
      keyAlias="KEY_ALIAS"
      ...
   </ServiceProvider> 
  1. For example, if you generated a keystore called sso.jks with a passphrase abc123 and an alias called ssokey, the settings in service-provider.xml would be as follows:
   <ServiceProvider
      ...
      keystore="conf/sso.jks"
      keystorePassphrase="abc123"
      keyAlias="ssokey"
      ...
   </ServiceProvider> 
  1. 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.
  2. In the SamlIdentityProvider section, set the metadataUrl field as detailed in Step 3 – Specify the IdP.

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

Step 3 – 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.xml refers to this file on disk.

To specify the IdP by file, follow these steps:

  1. Set the metadataUrl field of the SamlIdentityProvider section of the service-provider.xml file to the value ./idp.xml.
  2. The following example shows a sample extract from the service-provider.xml file for Shibboleth. The metadataUrl refers to the file idp.xml.
   <SamlIdentityProvider
      entityId="https://axwayidp.localdomain/idp/shibboleth"
      metadataUrl="./idp.xml"
      ...
   </SamlIdentityProvider>
  1. Create an idp.xml file in the API Gateway instance folder using the template provided in INSTALL_DIR/apigateway/samples/sso/ShibbolethIDP/idp.xml.
  2. In the idp.xml file:
    • Replace the place holder CHANGE THIS : Replace this text with your IDP_CERTIFICATE with the certificate of your IdP that is used for signing SAML tokens.
    • Replace all instances of the placeholders <IDP_FQDN>:<IDP_SOAP_PORT> and <IDP_FQDN>:<IDP_HTTP_PORT> with the fully qualified domain name and port of your IdP.

Specify the IdP by URL

In this case, the IdP file is not stored locally. Instead, the service-provider.xml file refers to it by URL.

To use this method, set the metadataURL field to the metadata URL of the IdP in the SamlIdentityProvider section of the service-provider.xml file. The following example shows an extract from a service-provider.xml file for a Keycloak IdP. The metadataUrl refers to a URL.

   <SamlIdentityProvider
      entityId="https://YourkeycloakIDPServerFQDN:8443/auth/realms/Axway"
      metadataUrl="https://YourkeycloakIDPServerFQDN:8443/auth/realms/Axway/protocol/saml/descriptor"
      ...          
   </SamlIdentityProvider>

A sample of a service-provider.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.

Step 4 – Configure SSO in Policy Studio

Perform the following steps in Policy Studio:

  1. Open the configuration of your API Manager-enabled API Gateway instance. For example, select File > New Project from an API Gateway instance.
  2. Navigate to Environment Configuration > Listeners > API Gateway > API Portal > Paths in the Policy Studio tree.
  3. Click Add > Static File Provider.
  4. Set Relative Path to /sso-login-failed and File to $VDISTDIR/webapps/apiportal/login.html.
  5. Enter the following values to the additional headers table, and then click OK:
  6. HTTP Header Value
    Content-Security-Policy frame-ancestors 'none'
    X-Frame-Options DENY
  7. Edit each of the servlets (API Portal v1.2 (‘v1.2’) and API Portal v1.3 (‘v1.3’)) as follows:
    • Edit the property jersey.config.server.provider.classnames. In the Value field add the class name com.vordel.common.apiserver.filter.SSOBindingFeature to the existing comma-separated list of class names.
    • Add a new property. In the Name field enter the name CsrfProtectionFilterFactory.refererWhitelist and in the Value field enter the URL of the IdP (for example, https://sample_idp_host:8443).
  8. Servlet configuration for SAML SSO
  9. Deploy the configuration to the API Manager-enabled API Gateway instance.

Step 5 – Configure SAML endpoint URLs

After configuring the SSO, you must define the SAML endpoint of API Manager 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://<your API Manager host FQDN>:8075/api/portal/v1.3/sso/login/post
    • logout-service-post-binding-url: https://<your API Manager host FQDN>:8075/api/portal/v1.3/sso/logout/post
    • Logout Service Redirect Binding URL: https://<your API Manager host FQDN>:8075/api/portal/v1.3/sso/logout/post

    An example screenshot on configuring the endpoints

If you are also configuring SSO for API Portal, you must configure the endpoint URLs separately for both API Manager and API Portal. For more details, see Configure API Portal for single sign-on in the API Portal Administrator Guide

Manage IdP certificates

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. To configure the IdP, you must import the public key to the IdP.

First, export the public key of the keystore you created in Step 1 – Set up a keystore. For example, use one of the following commands to export it using Java keytool.

This example exports it to publickey.txt:

keytool -list -rfc -keystore sso.jks -alias ssokey > publickey.txt

This example exports it to publickey.cer:

keytool -export -keystore sso.jks -alias ssokey -file publickey.cer

Next, import the public key to your 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. By default, the domain name is set to the API Gateway host name.

For example, it the host name is apigateway.wks.us.axway.int, the domain name in the cookie contains the substring apigateway.wks.us.axway.int.

If the API Gateway is hidden behind a load balancer, the cookie domain name might need to change as the client's browser is not aware of the internal API Gateway host name and therefore might not accept this cookie.

The following example shows how to change the default domain name to a sample domain name such as axway.int:

  1. Create a file called jvm.xml in the folder INSTALL_DIR/apigateway/conf (if it does not already exist).
  2. Add the following setting:
<ConfigurationFragment>
<VMArg name="-Dcom.axway.sso.domain.name=axway.int" />
</ConfigurationFragment>
  1. This setting assigns the value axway.int to the VMArg called com.axway.sso.domain.name.
Note   Do not prefix the domain name with a period (for example, do not use the value .axway.int).
  1. Restart the API Gateway.

Related Links