Configure API Portal single sign-on
8 minute read
Prerequisites
- 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:
INSTALL_DIR/apigateway/groups/group-2/instance-1/conf
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 inservice-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 atINSTALL_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:
INSTALL_DIR/apigateway/samples/sso`
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:
INSTALL_DIR/apigateway/samples/sso/keycloak/service-provider-apiportal.xml
The sample file contains useful information about what sections you must change to match your environment.
Note
Do not change any settings with paths containing/sso
, unless otherwise instructed.
-
To enable reverse proxying, check the following:
excludeHostInEndpointURICheck
is set totrue
.relaxedEndpointURICheckHostDetails
is not present, or if present, is set to your API Portal host (https://<FQDN>:<port>
).
-
In the
ServiceProvider
section, update thekeystore
,keystorePassphrase
, andkeyAlias
fields with the correct values for your keystore.For example, if you generated a keystore called
sso.jks
with a passphraseabc123
and an alias calledssokey
, the settings are as follows:<ServiceProvider ... keystore="conf/sso.jks" keystorePassphrase="abc123" keyAlias="ssokey" ... </ServiceProvider>
-
In the
SamlIdentityProvider
section, update theMappings
section with the mapping of IdP attributes to API Manager attributes. For more information on the mapping syntax, see Mapping syntax. -
In the
SamlIdentityProvider
section, change references tokeycloak.int.acme.com:8443
to the FQDN and port of your IdP. -
In the
SamlIdentityProvider
section, set themetadataUrl
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:
-
In the
SamlIdentityProvider
section, set themetadataUrl
field to the value./idp.xml
.The following example shows a sample extract from the
service-provider-apiportal.xml
file for Keycloak. ThemetadataUrl
refers to the fileidp.xml
:<SamlIdentityProvider entityId="https://keycloak.int.acme.com:8443/auth/realms/Axway" metadataUrl="./idp.xml" ... </SamlIdentityProvider>
-
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 theidp.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.
- For Shibbloteh, use the template provided in
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.
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
logout-service-post-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
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
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.
Configure the SSO cookie domain name
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.
- In the Joomla! Administrator Interface (JAI), click Components > API Portal > Single-Sign-On.
- Click Yes to enable SSO login.
- In SSO Client Entity ID, enter the
entityId
you defined for API Portal inservice-provider-apiportal.xml
. - In SSO Whitelist, enter the host name or IP address of your IdP to allow requests to the IdP (for example,
keycloak.lab.dubl.axway.int
). If you do not add your IdP to this field, all requests to your IdP will be rejected by API Portal. - 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:
- In JAI, click Components > API Portal > Single-Sign-On.
- In SSO Path, replace the default value
/sso
with the new path (for example,/newpath
results in a new SSO login URL ofhttps://<FQDN>:<port>/newpath
. - Click Save.