Single sign-on (SSO) allows users, who are authenticated against one application, gain access to multiple other related applications without having to repeatedly authenticate themselves. It also allows the web applications to gain access to a set of back-end services with the logged-in user's access rights, and the back-end services can authorize the user based on different claims like user role.
The Single sign-on with SAML 2.0 feature in the WSO2 API Manager is implemented according to the SAML 2.0 browser-based SSO support that is facilitated by WSO2 Identity Server (WSO2 IS). This feature is available in any WSO2 IS version from 4.1.0 onwards. We use WSO2 IS 5.1.0 in this guide. WSO2 Identity Server acts as an identity service provider of systems enabled with single sign-on, while the Web applications act as SSO service providers. Using this feature, you can configure SSO across the API Publisher and Store. After configuring, you can access the API Store or API Publisher in a single authentication attempt.
To learn more about single sign-on with WSO2 Identity Server, see SAML 2.0 Web SSO in the WSO2 Identity Server documentation.
The topics below explain the configurations:
Sharing the user store
For example, let's share a JDBC user store (MySQL) with both the WSO2 Identity Server and WSO2 API Manager as follows:
Download WSO2 API Manager 1.10.0 from here and unzip it.
<APIM_HOME>refers to the root folder where WSO2 APIM was unzipped.
Create a MySQL database (e.g.,
410_um_db) and run the
<APIM_HOME>/dbscripts/mysql.sqlscript on it to create the required tables.
If you are using a different database type, find the relevant script from the
<APIM_HOME>/repository/conf/datasources/master-datasources.xmlfile and add the datasource configuration for the database that you use for the shared user store and user management information. For example, you can share as single user store as follows. If you are sharing multiple datasources, you need to define a datasource for each of the user stores that you are working with, so that they can be shared.
Download WSO2 Identity Server (WSO2 IS) 5.1.0 from here and unzip it.
<IS_HOME>refers to the root folder where WSO2 IS was unzipped.
If you plan on using WSO2 IS as Key Manager as well, you can download the WSO2 Identity Server 5.1.0 as a Key Manager pack, which has Key Manager features pre-packaged with WSO2 IS, from here.
Add the same datasource configuration above to
Copy the database driver JAR file to the
dataSourceproperty points to the default H2 database. Change it to the jndiConfig name given above (i.e.,
jdbc/WSO2UMDB). This changes the datasource reference that is pointing to the default H2 database.
- Add the same configuration above to the
The Identity Server has an embedded LDAP user store by default. As this is enabled by default, follow the instructions in Internal JDBC User Store Configuration to disable the default LDAP and enable the JDBC user store instead.
Sharing the registry space
In a multi-tenanted environment, by default, the Identity Server uses the key store of the super tenant to sign SAML responses. The API Store and Publishers are already registered as SPs in the super tenant. However, if you want the Identity Server to use the registry key store of the tenant that the user belongs to, you can create a common registry database and mount it on both the IS and the APIM.
Create a MySQL database (e.g., registry) and run the
<IS_HOME>/dbscripts/mysql.sqlscript on it to create the required tables.
If you are using a different database type, find the relevant script from the
Add the following datasource configuration to both the
Create the registry mounts by inserting the following sections into the
When doing this change, do not replace the existing
wso2registry". Simply add the following configuration to the existing configurations.
Repeat the above step in the
<APIM_HOME>/repository/conf/registry.xmlfile as well.
Next, let us look at the SSO configurations.
Configuring WSO2 Identity Server as a SAML 2.0 SSO Identity Provider
Start the WSO2 Identity Server.
What is port offset?
The port offset feature allows you to run multiple WSO2 products, multiple instances of a WSO2 product, or multiple WSO2 product clusters on the same server or virtual machine (VM). The port offset defines the number by which all ports defined in the runtime, such as the HTTP/S ports, will be offset. For example, if the HTTPS port is defined as 9443 and the portOffset is 1, the effective HTTPS port will be 9444.
Sign in to the WSO2 IS Management Console UI (
If you use signin pages that are hosted externally to sign in to the Identity Server, give the absolute URLs of those login pages in the
application-authenticators.xmlfiles in the
- Select Add under Service Providers menu.
Give a service provider name and click Register.
In a multi tenanted environment, for all tenants to be able to log in to the APIM Web applications, do the following:
Click the SaaS Application option that appears after registering the service provider.
If not, only users in the current tenant domain (the one you are defining the service provider in) will be allowed to log in to the Web application and you have to register new service providers for all Web applications (API Store and API Publisher in this case) from each tenant space separately. For example, let's say you have three tenants as TA, TB and TC and you register the service provider in TA only. If you tick the SaaS Application option, all users in TA, TB, TC tenant domains will be able to log in. Else, only users in TA will be able to log in.
Add the following inside the
<SSOService>element in the
<IS_HOME>/repository/conf/identity/identity.xmlfile and restart the server.
If not, you get an exception as SAML response signature verification fails.
- Because the servers in a multi-tenanted environment interact with all tenants, all nodes should share the same user store. Therefore, make sure you have a shared registry (JDBC mount, WSO2 Governance Registry etc.) instance across all nodes.
You are navigated to the detailed configuration page. Expand SAML2 Web SSO Configuration inside the Inbound Authentication Configuration section. Click Configure.
Provide the configurations to register the API Publisher as the SSO service provider. These sample values may change depending in your configuration.
- Issuer : API_PUBLISHER
- Assertion Consumer URL : https://localhost:9443/publisher/jagg/jaggery_acs.jag. Change the IP and port accordingly. This is the URL for the acs page in your running publisher app.
Select the following options:
Enable Response Signing
Enable Signature Validation in Authentication Requests and Logout Requests
Enable Assertion Encryption
Enable Single Logout
- Click Register once done.
Similarly, provide the configurations to register the API Store as the SSO service provider. These sample values may change depending in your configuration.
- Issuer : API_STORE
- Assertion Consumer URL : https://localhost:9443/store/jagg/jaggery_acs.jag. Change the IP and port accordingly. This is the URL for the acs page in your running store app.
- Select the following options:
- Enable Response Signing
- Enable Signature Validation in Authentication Requests and Logout Requests
- Enable Assertion Encryption
- Enable Single Logout
- Click Register once done.
For more information on SAML related terminologies discussed in the sections above, go to Assertions and Protocols for the OASIS SAML 2.0 documentation.
- Make sure that the
responseSigningEnabledelement is set to
truein both the following files:
For more details on configuring WSO2 Identity Server 5.1.0 see, Configuring the service provider.
Configuring WSO2 API Manager apps as SAML 2.0 SSO service providers
<APIM_HOME>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.jsonand modify the following configurations found under ssoConfiguration.
- enabled: Set this value to true to enable SSO in the application
- issuer: API_PUBLISHER. This value can change depending on the Issuer value defined in WSO2 IS SSO configuration above.
- identityProviderURL: https://localhost:9444/samlsso. Change the IP and port accordingly. This is the redirecting SSO URL in your running WSO2 IS server instance.
- keyStoreName: A keystore which has an IDps public key. As you use a remote instance of WSO2 IS here, you can import the public certificate of the IS keystore to the APIM and then point to the APIM keystore. The default keystore of the APIM is <APIM_HOME>/repository/resources/security/wso2carbon.jks. Be sure to give the full path of the keystore here.
- keyStorePassword: Password for the above keystore
- identityAlias: wso2carbon
- Similarly, configure the API Store with SSO. The only difference in API Store SSO configurations is setting API_STORE as the issuer.
- Reduce the priority of the
SAML2SSOAuthenticatorconfiguration in the
You do this as a workaround for a known issue that will be fixed in a future release. The
SAML2SSOAuthenticatorhandler does not process only SAML authentication requests at the moment. If you set its priority higher than that of the
SAML2SSOAuthenticatortries to process the basic authentication requests as well. This causes login issues in the API Publisher/Store.
- Access the API Publisher :
https://localhost:<Port number>/publisher(e.g., https://localhost:9443/publisher). Observe the request redirect to the WSO2 IS SAML2.0 based SSO login page. For example,
- Enter user credentials. If the user authentication is successful against WSO2 IS, it will redirect to the API Publisher Web application with the user already authenticated.
- Access the API Store application, click its Login link (top, right-hand corner) and verify that the same user is already authenticated in API Store.
Even with SSO enabled, if the user doesn't have sufficient privileges to access API Publisher/Store or any other application, s/he will not be authorized to access them.
The steps above explain how to configure SSO between the API Publisher and Store Jagger applications, using WSO2 IS as the IDP. If there are many WSO2 products in your environment, you can configure SSO for the management consoles of those products by changing the
SAML2SSOAuthenticator configuration in
<PRODUCT_HOME>/repository/conf/security/authenticators.xml file as follows:
ServiceProviderID: In this example, it is the issuer name of the service provider created in step 1
IdentityProviderSSOServiceURL: In this example, it is the Identity Server port
Make sure the
SAML2SSOAuthenticatoris less than that of the
BasicAuthenticatorhandler. See here for more information.
Configuring the API Store for SSO in passive mode
If the passive mode is disabled and single sign-on (SSO) is enabled, it redirects the user to the SSO login page. Therefore, as the WSO2 API Store allows anonymous access, passive mode is enabled by default, so that irrespective of whether SSO is enabled or not it directs the user to the API Store URL, and enables the SSO work flow only when the Sign In button is clicked.
To disable the passive mode, set the property named
passive to false in the