2016/02/19
19 Feb, 2016

[Article] How To Setup a WSO2 API Manager Store Login with Google

  • Sanjeewa Malalgoda
  • Director - Engineering | Architect at WSO2 - WSO2

Applies to

WSO2 API Manager Version 1.10.0 and above
WSO2 Identity Server Version 5.1.0 and above


Table of contents

  • Introduction
  • What is SSO and How We Use it in WSO2 API Manager
  • Setting up SSO-Based Login for API Manager Store with WSO2 Identity Server
  • Add Google as Identity Provider for WSO2 Identity Server
  • Conclusion


Introduction

WSO2 API Manager is a complete solution for publishing APIs, creating and managing a developer community, and for scalably routing API traffic. It leverages proven, production-ready integration, security, and governance components from WSO2 Enterprise Service Bus, WSO2 Identity Server, and WSO2 Governance Registry. Moreover, it is powered by WSO2 Business Activity Monitor, thereby making WSO2 API Manager ready for any large-scale deployment right away.

When we setup WSO2 API Manager in production deployments it’s evident that users are somewhat reluctant to create a new account or self sign up. The time taken to fill forms and validation process may sometimes discourage them, but if we allow them to login to the API store with their Google or Facebook credentials it will be much more convenient. Single sign-on (SSO) takes away the hassle of having to memorize a long list of passwords too. How does this translate to cost savings though? Statistics show that up to 50% of all Help Desk calls are just requests for password resets. Therefore, a user-friendly login process is key because the login screen is the first point of interaction between users and the inner halls of your website.


What is SSO and how we use it in WSO2 API Manager

SSO allows users who are authenticated against one application to gain access to multiple other related applications as well without having to repeatedly authenticate.

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.

WSO2 API Manager includes SSO with the SAML 2.0 feature that’s implemented according to the SAML 2.0 Web browser-based SSO support facilitated by WSO2 Identity Server. This feature is available in any IS version from 4.1.0 onwards. We use IS 5.1.0 in this deployment.

WSO2 Identity Server acts as an identity service provider of systems enabled with SSO, while Web applications, such as API manager apps, act as SSO service providers. By using this feature you can configure SSO across the two API manager Web applications, which include API Publisher and API Store, as well as other Web applications in your organization. Post configuration, you will be able to access the API Store or API Publisher in a single authentication attempt.


Setting up SSO-based login for API Manager Store with WSO2 Identity Server

First we will setup the API Manager Store to use Identity Server to login with SSO. To do that we need to follow instructions below:

  1. To run this sample you will need WSO2 API Manager and WSO2 Identity server. Since we are running both in the same physical server, we have used port offset as 1 for identity server. You can go to <Identity_server_home>/repository/conf/carbon.xml file and edit offset value to 1. Then the WSO2 Identity Server management console will start with port 9444. We can run API manager in default ports so it will start with port 9443.
  2. On the WSO2 Identity Server side we need to register the service provider as follows. This service provider will act as the SAML service provider on the identity server side.

    Figure 1


  3. Once you’ve created the service provider you need to go to SAML2 and the SSO configurations section and register the new issuer. When you create the new issuer you need to pass some important parameters. Let’s see how we can do this:

    Figure 2

    We will only discuss the required configurations here. If you need more information about all parameter you can refer to this tutorial - https://docs.wso2.com/display/IS500/Adding+a+Service+Provider.

    Issuer: This is the <saml:Issuer> element that contains the unique identifier of the service provider. This is also the issuer value specified in the SAML Authentication Request issued by the service provider. Since we are creating different issuers for Store and Publisher, we have named this issuer API_STORE_ISSUER.


  4. Specify the Assertion Consumer URL. This is the URL to which the browser should be redirected to after the authentication is successful. This is the Assertion Consumer Service (ACS) URL of the service provider. The identity provider redirects the SAML2 response to this ACS URL. However, if the SAML2 request is signed and SAML2 request contains the ACS URL, the identity server will honor the ACS URL of the SAML2 request. For this sample you need to provide the ACS user of the API Store and Publisher applications. In the API Store we have the Jaggery file to act as the assertion consumer service (ACS) https://127.0.0.1:9443/store/jagg/jaggery_acs.jag. Once the request comes to jaggery_acs.jag we will be able to decode the SAML response and extract the required parameters here and validate it on the API manager side. Once it’s validated we will set the user name found in the SAML response as the logged in user. The user will then be able to use the API Store as per permissions allocated.
  5. For this usecase we will define the Assertion Consumer URL as https://127.0.0.1:9443/store/jagg/jaggery_acs.jag
  6. Specify the NameID format. This defines the name identifier formats supported by the identity provider. The service provider and identity provider usually communicate with each other regarding a specific subject. This specifies the name identifier format that the identity server wants to receive in the subject of an assertion from a particular identity provider. The following is the default format used by the identity provider.

    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress


  7. Select Enable Response Signing to sign the SAML2 Responses returned after the authentication process.
  8. Select the Certificate Alias from the dropdown. This is used to validate the signature of SAML2 requests and is used to generate encryption. Basically the service provider’s certificate must be selected here. Note that this can also be the identity server tenant's public certificate in a scenario where you are doing a tenant-specific configuration.
  9. Select Enable Single Logout so that all sessions are terminated once the user signs out from one server. If a single logout is enabled, the identity provider sends the logout requests to all service providers. Basically, the identity provider acts according to the single logout profile. If the service provider supports a different URL for logout, you can enter a Custom Logout URL for logging out. If you do not specify this URL, the identity provider uses the ACS URL.
  10. Select Enable Attribute Profile to enable this and add a claim by entering the claim link and clicking the Add Claim button. The identity server provides support for a basic attribute profile where the identity provider can include the user’s attributes in the SAML assertions as part of the attribute statement. Once you select the checkbox to Include Attributes in the Response Always, the identity provider always includes the attribute values related to the selected claims in the SAML attribute statement.
  11. After creating the service provider you need to edit site.json file for each Jaggery app as follows:

    sample SSO configuration for API store site.json config file.


  12. Here you need to provide the issuer, idpurl and some other parameters.

    enabled: Set this value to true to enable SSO in the application.

    keyStoreName: The keystore of the running IDP. Given that you’re using a remote instance of WSO2 Identity Store here, you can import the public certificate of the identity server keystore to the API manager and then point to the API manager keystore. The default keystore of the API manager is /repository/resources/security/wso2carbon.jks. Be sure to give the full path of the keystore here.

    keyStorePassword: Password for the above keystore (default value "wso2carbon").

    identityAlias: "wso2carbon".

    issuer: API_PUBLISHER. This value can change depending on the Issuer value defined in WSO2 Identity Server SSO configuration above.

    identityProviderURL: https://localhost:9444/samlsso. Change the IP and port accordingly. This is the redirecting SSO URL in your running WSO2 Identity Server instance.

Please refer to the following sample configurations:

 "ssoConfiguration" : {
        "enabled" : "true",
        "issuer" : "API_STORE_ISSUER",
        "identityProviderURL" : "https://localhost:9444/samlsso",
        "keyStorePassword" : "wso2carbon",
        "identityAlias" : "wso2carbon",
        "responseSigningEnabled":"true",
        "keyStoreName" :"/home/sanjeewa/work/bootcamp/wso2is-5.1.0/repository/resources/security/wso2carbon.jks",
        "passive" : "true",
        "signRequests" : "true",
        //"acsURL" : "https://localhost:9443/store/jagg/jaggery_acs.jag", //In passive or request signing mode, use only if default Assertion Consumer Service URL needs to be overidden
        //"nameIdPolicy" : "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", //If not specified, 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified' will be used
    }

sample SSO configuration for the API Publisher site.json config file.

 "ssoConfiguration" : {
        "enabled" : "true",
        "issuer" : "api_publisher_issuer",
        "identityProviderURL" : "https://localhost:9444/samlsso",
        "keyStorePassword" : "wso2carbon",
        "identityAlias" : "wso2carbon",
        "responseSigningEnabled":"true",
        "keyStoreName" :"/home/sanjeewa/work/bootcamp/wso2is-5.1.0/repository/resources/security/wso2carbon.jks",
        "passive" : "true",
        "signRequests" : "true",
        //"acsURL" : "https://localhost:9443/store/jagg/jaggery_acs.jag", //In passive or request signing mode, use only if default Assertion Consumer Service URL needs to be overidden
        //"nameIdPolicy" : "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", //If not specified, 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified' will be used
    }

After these steps, the API Manager Store and Publisher login will redirect to WSO2 Identity Server and you can login to the API Manager Store and Publisher using SSO. When you try to login to the API Store or Publisher you will be redirected to the identity server and once you’ve provided the username and password you will return back to the API Store after successful login.

Please note that you may need to share the same permission database between the API manager and identity server if they both need to share the same permissions.

Add Google as Identity Provider for WSO2 Identity Server

Since we have already set up the Store and Publisher with SSO, we are now going to add Google as the identity provider. To do that you can follow these instructions:

We are going to create an OAuth client application in Google and integrate it with the identity server.

  • First visit the Google app console and create a project.
  • Create an OAuth application by logging in to the Google developer console.
  • Create an Application in the Google app console.
  • Next go to manager and APIs and then go to credentials.
  • Then click on new credentials.
  • Now from the dropdown menu select the OAuth Client ID.
  • Then go to configure consent page.

    Figure 3

  • Select your application type.

    Figure 4

  • Finally you will get a client ID and secret for your application.
  • Then you need to copy and save client application. Else you can download application information json file.

    Figure 5

We have completed the Google application creation process. Now we are going to create an identity provider with the Google credentials. For that let’s create an identity provider in the identity server.

Figure 6

Provide name for the identity provider and other details as shown above.

Alias: https://localhost:9444/oauth2/token

Figure 7

Then go to the federated authenticators section and go to Google configurations. First you need to enable google authenticator. To do this click on the enable button as shown above.

Here you need to provide a consumer key and secret key generated from the Google app console. We will use that client ID and secret when we connect to Google. What google does is authenticate users against the application that was created.

Then as Additional Query Parameters you can pass scope=openid email profile.

Add Claim mapping for IDP.

Figure 8

Thereafter provision users to API manager. Provision users to identity server means we create a corresponding entry for the logged in user in the identity server. To understand more about user provisioning you may refer to this article.

Figure 9

Then we need to integrate the created identity provider in outbound flow of the above created SSO providers. For this go to the advanced configurations section in Local and Outbound Authentication Configuration.

Then go to advanced options as follows.

Figure 10

There you need to add both basic authentication and Google authentication to flow (see attached image).

According to your use case you may select the authentication steps. In this example we will let users login with both Google and basic authenticator. In some scenarios we may need to let users login only using Google or we may need to enable both Google and Facebook.

Figure 11

Then when you login to the API store or publisher apps you will see the following login page where you can login to the system using WSO2 Identity Server with integrated Google user credentials.

Figure 12

We have completed SSO authentication for WSO2 API Manager Store and Publisher login flow (included Google integration).

Figure 13

You need to follow these instructions for both API Store and Publisher applications separately.


Conclusion

Decentralized systems are becoming increasingly common and authentication is an essential aspect of all of them. SSO helps to manage the increasing number of users across different platforms. Platforms like Facebook and Google have the world's largest user bases. When you develop the API management platform you can integrate the existing user bases to offer a high quality user experience. With SSO users don't need to self sign up, fill many forms, remember passwords, and usernames. In conclusion, SSO integration for an API Store will add value to the user experience and help users to subscribe and use APIs with a minimum number of steps.

 

About Author

  • Sanjeewa Malalgoda
  • Director - Engineering | Architect at WSO2
  • WSO2