End-User Authentication via API Gateway

[UPDATE] Besides LDAP and web-service authentication, API Cloud now supports authentication via external Identity Provider (IdP) and WSO2 Integration Cloud. See the documentation for details: Authenticate External Users for API Invocation.

Quite often APIs need to be invoked on behalf of particular end-users. For example, a typical mobile application would ask the user to authenticate and then serve the data depending on who that user is.

These end-user identities are different from the engineers who publish the API (Publishers) and the ones who subscribe to the API to develop the application invoking it (Subscribers, developers.) Let's look into how WSO2 API Cloud supports that scenario:

1. The application first invokes Token API, passing end-user username and password.
2. API Gateway checks whether the user exists in the primary userstore (engineers who work with the API: publishers and subscribers), if not, it checks whether there is a secondary userstore, and if the one is registered with this organization, Gateway is making the call to check if the username and password are valid.
3. Userstore performs the check and reports success or failure.
4. If authentication is successful, Gateway generates the OAuth token and passes it back to the application.
5. For all subsequent actual API calls, the application passes the OAuth token in the Authorization header.
6. Gateway checks the token to authorize the call and passes to the backend user identity information in the form of a JWT token.

Here are the technical details on making this work:

Connecting End-User Identity Store to the Gateway

Application backends typically already have some sort of LDAP store or database that stores the end-user credentials. There are two ways you can get it connected to the cloud gateway:

1. If the userstore is LDAP (for example, OpenLDAP or Microsoft Active Directory) you can get it connected directly by supplying the access URL and credentials,
2. For everything else, you need to provide an authentication web-service that can perform the check.

If you are using the web-service option, it needs to expect a POST invocation with the following JSON payload:

{
"credentials": {
"username": "userx",
"password": "mypass"
}
}

If the enduser record is valid, the web-service should respond with the following JSON:

{
"response": {
"status": "true"
}
}

Notes:

• The web-service should obviously itself be protected with username and password.
• If your existing authentication webservice is using a different JSON format, this can be used too, we just need to configure the parameters to work with your schema.
• If the userstore is behind firewall and cannot be exposed to the cloud directly, we support various secure ways of doing so including VPN, reverse proxy services in DMZ and so on.

Token API

Token API of the cloud gateway is documented here.

For a particular application, you can easily get the right call generated for you right in API Cloud's Developer Portal (API Store), by going to the My Subscriptions tab,  clicking the cURL dropdown, and selecting GrantType: Password:

Note:

• When passing username in the token request, take the username that the user has in your system and add @ and the organization name that you have in WSO2 Cloud. For example, if the username that user has in your database is userx and your organization name in WSO2 is my_company, then instead of <USER> in the screenshot above you would pass userx@my_company.

JWT Token

The final step in the scenario, is decoding user identity information in your backend code. This is passed with each call in the form of JWT token.

Here is the sample JWT token. The enduser identity is passed in the "https://wso2.org/claims/enduser" property:

{
    "typ":"JWT",
    "alg":"NONE"
 }{
    "iss":"wso2.org/products/am",
    "exp":1345183492181,
    "https://wso2.org/claims/subscriber":"user.email.com@org",
    "https://wso2.org/claims/applicationname":"app2",
    "https://wso2.org/claims/apicontext":"/placeFinder",
    "https://wso2.org/claims/version":"1.0.0",
    "https://wso2.org/claims/tier":"Silver",
    "https://wso2.org/claims/enduser":"jane"
 }

Ready to Get Started?

On the Configure menu, click External Users, and then select the options you need on the API Consumer Authentication tab. See Authenticate External Users for API Invocation for details.