Authenticate External Users for API Invocation

There are different types of users who use your APIs in WSO2 API Cloud:

• Publishers create the APIs and publish them to the Developer Portal,
• Subscribers subscribe to the APIs and develop applications that invoke these APIs,
• End-users use the applications (for example, web or mobile applications) invoking the APIs.

The identities of the end-users often reside in a directory (such as LDAP) or a database that is external to WSO2 Cloud, or are authenticated using an identity provider.

In this case, you would likely use one of the following scenarios:

• The application is already using an Identity Provider (IdP) and now needs to substitute the SAML2 token from that IdP for an OAuth2 token and then invoke the APIs. For more information on this scenario, see SAML Extension Grant.
• There is a directory or database containing the identities. The application gets the username and password from the end-user and needs to use them to fetch the OAuth2 token and then invoke the APIs. This scenario is depicted in the following diagram (click to expand) and explained below. 

 Let's get started.

1. On the Configure menu, click External Users.

   

2. Click the API Consumer Authentication tab.

3. Click Connect your RESTful Authentication Service.

   • If you need to use an existing SAML identity provider instead, see SAML Extension Grant.
   • If you need to connect your LDAP user store instead, you can either provide the LDAP connection information and password (if LDAP is directly reachable from API Cloud) or use the Integration Cloud's connection to your directory (in which case you need to first go to Identity Cloud, download and configure the agent to hook up your directory to WSO2 Cloud. For more information, see /wiki/spaces/IdentityCloud/pages/41648198).

   
   You need to implement a web service that expects a POST invocation with the following JSON payload. 

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

   If the end-user record is valid, the web service responds with the following,

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

   • The web service itself should be protected with a username and password.
   • If your existing authentication web service is using a different JSON format, contact WSO2 Cloud support (using the Support menu) so we can change the format on our side.
   • If the userstore is behind a firewall and cannot be exposed to the cloud directly, we support various secure ways of doing so including VPN, reverse proxy services in DMZ, etc.

4. WSO2 adds your external user store as a secondary user store to WSO2 API Cloud and informs you. The users in this secondary user store have permission to invoke APIs in your tenant domain.

5. Invoke the following cURL command to generate an access token for a user via the Token API. 

   Tip: The Token API allows you to generate and renew user and application access tokens. The response of the Token API is a JSON message. You extract the token from the JSON and pass it with an HTTP Authorization header to access APIs in the API Store.

   curl -k -d "grant_type=password&username=<username@organization_name>&password=<PASSWORD>" -H "Authorization: Basic <Base64Encoded Consumer key:consumer secret>" https://gateway.api.cloud.wso2.com/token

   
   

   When you have connected your user store to the API Cloud via a RESTful service, you cannot generate tokens for different scopes. If you need to restrict access to different resources of your API based on scopes, you should not connect the user store via a RESTful service.

   
   

   Tip: When passing the username, take the username that the user has in your system and add "@<organization name that you have in the Cloud>" to the end.

   For example, if the username in your database is testuser@email.com and the organization name in WSO2 Cloud is my_company, then the username that you pass in the token request should be testuser@email.com@my_company.

   
   

   Tip: To get the consumer key and consumer secret pair, go to the API Store and click Applications on the left panel. This displays your existing applications. Next, click View on a required application and then depending on your requirement click either the Production Keys tab or Sandbox Keys tab to generate appropriate keys.

6. Using the OAuth access token that you got in the previous step, invoke an API in the API Cloud. For example,

   curl -k -X GET --header 'Accept: application/xml' --header 'Authorization: Bearer <OAuth token from step 3>' 'https://gateway.api.cloud.wso2.com/t/companyn/dmzdemo/1.0.0/jaxrs_basic/services/customerservice/customers/123'

7. See the actual identity of the user in your user store by examining the JWT token that is passed with each API call. The end user identity is passed in the “ http://wso2.org/claims/enduser ” property as shown in the example below:

   Sample JWT Token

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

You have now learned how to add your external user store as a secondary user store to WSO2 Cloud and to generate access tokens for the users using the Cloud's Token API.