Configure API Manager single sign-on

Configure single sign-on for API Manager.

11 minute read

This topic details the steps you must follow to configure API Manager SSO. It also lists the prerequisites for configuring SSO, describes the configuration files used to configure SSO, and provides some usage guidelines.

Watch this video to see how to configure single sign-on based on the Keycloak example.

Prerequisites

Before you can start to configure API Manager SSO:

  • You must have a third-party IdP installed and running.

Configuration files

The following configuration files are used for API Manager SSO.

A keystore (for example sso.jks)

This file is the keystore generated by an administrator, and it is referenced in service-provider.xml.

  • Contains the key that the SSO agent uses to sign requests. The exported public key must be stored by the IdP.
  • Located in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf).
  • For more information, see Step 1 – Configure the IdP.

service-provider.xml

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.

idp.xml (optional)

  • Required only if you are specifying the IdP by file.
  • Located in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf).
  • For more information, see Specify the IdP by file.

jvm.xml (optional)

  • Used to configure the SSO cookie domain name and required only in a load-balanced environment.
  • Located in the folder INSTALL_DIR/apigateway/conf.

An optional trustore (for example trustStore.jks)

This file is an optional truststore that contains the required IdP server certificates, and it is referenced in service-provider.xml.

  • When specifying the IdP by URL this truststore is used to validate the IdP server certificate to download the required Metadata-Information, see Specify the IdP by URL.
  • Located in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf).
  • Add the server certificates into this trustore.

Sample files

You can use the sample files included in your API Gateway installation at:

INSTALL_DIR/apigateway/samples/sso

The following sample files are included:

  • ShibbolethIDP folder:
    • 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.
    • Sample service-provider.xml where the IdP is specified by file using idp.xml.
    • Sample idp.xml.
  • keycloak folder:
    • Sample service-provider.xml file that uses a URL to specify the IdP.
    • Sample service-provider-apiportal.xml for configuring API Portal SSO. For more details, see Configure API Portal single sign-on.

Usage guidelines

When configuring API Manager SSO, follow these guidelines.

Host names

Always use fully qualified domain names (FQDNs) for the host name. Avoid using IP addresses or localhost in the configuration.

User role mapping and API Manager organizations

You must manually configure the mapping of user roles between the IdP and API Manager in the file service-provider.xml. For more information, see Mapping syntax.

An SSO user is mapped to one of three SSO roles:

  • Administrator
  • Operator
  • User

The SSO role to API Manager role mapping is as follows:

SSO role API Manager role Notes
Administrator API administrator (for example, apiadmin) The API administrator does not belong to a specific organization
Operator Organization administrator The organization administrator belongs to a specific organization
User API consumer The API consumer belongs to a specific organization

The service-provider.xml mapping effectively maps a user to an organization. To authenticate a user successfully using SSO:

  • If the user’s role is User or Operator, the user must belong to a specific organization (at most one organization) and that organization must already exist in API Manager. An API Manager administrator user can add the organizations in advance. For more information on adding organizations, see Manage organizations.
  • If the user’s role is Administrator, that user does not need to belong to a specific organization.

For more information on API Manager roles, see API Manager access control.

SSO users and SSO login

The following restrictions apply to SSO users and SSO login:

  • 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 SSO login URL:

     https://FQDN:PORT/api/portal/v1.4/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.4/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.

Step 1 – Configure the IdP

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.

In this step you will create a keystore, export the public key of the keystore you created, and import it to your IdP.

First, use the Java keytool utility to set up a keystore containing a key pair:

  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 valid for 365 days (1 year):

    keytool -genkey -alias ssokey -keyalg RSA -keystore sso.jks -keysize 2048 -validity 365
    

Next, export the public key of the keystore you created. 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

Finally, import the public key to your IdP. Consult the documentation for your IdP for details.

Step 2 – Create the service-provider.xml file

In this step you will create a service-provider.xml file based on a sample file, and update it with the correct values for your keystore, your IdP, and the appropriate mappings for your IdP:

  1. Copy either of the service-provider.xml sample files included in the INSTALL_DIR/apigateway/samples/sso folder of your API Gateway installation to your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf). The sample file in the ShibbolethIDP folder specifies the IdP by file, and the sample in the keycloak folder specifies the IdP by URL.

  2. 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>
    
  3. 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>
    
  4. In the SamlIdentityProvider section, update the metadataUrl field as detailed in Specify the IdP by file or Specify the IdP by URL.

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

  6. Update any other fields as required. For more information on the elements in the service-provider.xml configuration file, see service-provider.xml configuration file reference.

Specify the IdP by file

To specify the IdP by file, follow these steps:

  1. Copy the idp.xml sample file included in the INSTALL_DIR/apigateway/samples/sso/ShibbolethIDP folder of your API Gateway installation to your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf).

  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.
  3. Set the metadataUrl field of the SamlIdentityProvider section of the service-provider.xml file to the value ./idp.xml. For example:

       <SamlIdentityProvider
          entityId="https://axwayidp.localdomain/idp/shibboleth"
          metadataUrl="./idp.xml"
          ...
       </SamlIdentityProvider>
    

Specify the IdP by URL

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

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

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.

Step 3 – 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.
  5. Ensure that the settings for this relative path match those for the /login-failed relative path, the only difference being the path name.
  6. Set File to $VDISTDIR/webapps/apiportal/login.html.
  7. Enter the following values to the additional headers table, and click OK:
    • Content-Security-Policy: frame-ancestors 'none'
    • X-Frame-Options: DENY
  8. Update the servlet to API Portal v1.4 ('v1.4').
    • 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).
  9. Deploy the configuration to the API Manager-enabled API Gateway instance.

Step 4 – Configure SAML endpoint URLs in the IdP

You must configure the SAML endpoints of API Manager in your IdP. Consult the documentation for your IdP for details. The following examples are for Keycloak IdP.

Keycloak field name API Manager endpoint URL
Assertion Consumer Service POST Binding URL https://<your_API Manager_host_FQDN>:8075/api/portal/v1.4/sso/login/post
Assertion Consumer Service Redirect Binding URL Leave this field blank
Logout Service POST Binding URL https://<your_API Manager_host_FQDN>:8075/api/portal/v1.4/sso/logout/post
Logout Service Redirect Binding URL https://<your_API Manager_host_FQDN>:8075/api/portal/v1.4/sso/logout/post
  • 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 single sign-on.
  • For API Manager endpoint URLs, use the version of the API as specified previously in the servlet properties.

This implementation of SSO uses a cookie, which is created on the API Gateway server and sent to the client’s browser. The cookie includes the domain name, which is set to the API Gateway host name by default. For example, if the host name is apigateway.wks.us.axway.int, the domain name in the cookie contains the substring apigateway.wks.us.axway.int.

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

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>
    

Step 6 – Configure the orgs2Role header using a policy (optional)

You can use the orgs2Role attribute to assign user membership to multiple API Manager organizations, or you can configure an API Gateway policy.

The policy is invoked at runtime after the SAML response from the identity provider is verified by the service provider (in this case, API Manager). The API Manager runtime will only accept the output of the policy if it is successful and it has the orgs2Role value set in the HTTP headers. To set the header, you can use existing API Gateway filters, for example Add HTTP Header Filter, or you can set the header programmatically.

The following message attributes are available to aid with the decision making process of setting the orgs2Roleheader:

  • user.email
  • user.telephone.number
  • user.department
  • user.description
  • user.userfullname
  • orgs2Role
  • authentication.subject.role
  • authentication.subject.id
  • authentication.organization.name

To configure a policy, 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 Server Settings > API Manager > Identity Provider in the Policy Studio tree.
  3. Choose the policy you want to invoke in the Single sign on policy (optional) field.

Example policy

  1. Use a switch filter to make a decision based on a message attribute.

    Single sign on processing policy

  2. Assign membership via the Add HTTP Header filter.

    Add orgs2Role header

Step 7 – Restart API Gateway

Finally, you must restart the Node Manager and the API Gateway instance to enable the changes in service-provider.xml and jvm.xml files to be applied. After the restart, your users will be able to log in to API Manager using SSO.