Wednesday, March 15, 2017

How to expose sensitive services to outside as APIs

APIM 2.0.0 supports oauth 2.0.0 based security for APIs(with JWT support) out of the box and we can utilize that for secure services. Let me explain how we can use it. Lets consider how mobile client application can use those secured APIs. 
  • User logs into system(using multi step authentication including OTP etc ). If we are using SAML SSO then we need browser based redirection from native  application.
  • Then once user authenticated we can use same SAML assertion and obtain OAuth 2.0.0 access token on behalf of logged in user and application(which authenticate both user and client application).
  • Then we can use this token for all subsequent calls(service calls). 
  • Then when requests come to API gateway we will fetch user information from token and send them to back end.
  • Also at gateway we can do resource permission validation.
  • If we need extended permission validation we can do that as well before request routed to core services.
  • So internal service can invoke only if user is authenticated and authorized to invoke that particular API.
This complete flow can be implement using WSO2 API Manager and Identity server.

JWT token and its usage in WSO2 API Manager

JSON Web Token (JWT) represents claims to be transferred between two parties. The claims in a JWT are encoded as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure or as the plain text of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed. A JWToken is self-­contained, so when we create one, it will have all the necessary pieces needed inside it.

To authenticate end users, the API manager passes attributes of the API invoker to the back-end API implementation. JWT is used to represent claims that are transferred between the end user and the backend. A claim is an attribute of the user that is mapped to the underlying user store. A set of claims are called a dialect (e.g. The general format of a JWT is {token infor}.{claims list}.{signature}. The API implementation uses information, such as logging, content filtering, and authentication/authorization that is stored in this token. The token is Base64-encoded and sent to the API implementation in a HTTP header variable. The JWT header will contain three main components.

What are those pieces? The JWT token string can be divided into three parts.
A header
A payload
A signature

We will discuss about these parts later and understand them.

First let's consider very simple use case to understand the usage of API Manager JWT use case.
Let's say we have shopping cart web application. And user is invoking some web services associated with that application through API Manager. In such cases we may need to pass user details to backend service. So as discussed above we may use JWT to pass that information to backend.

Lets think we have 2 users named Bob and frank.
  • Bob is 25 years old and he is enjoying watching cricket. He based on colombo, sri lanka.
  • Frank is 52 years old and he enjoys watching football.He is living in frankfurt germany

They both realized coming weekend is free for them and then decided to go out to watch game.
Both Bob and Frank installed find
They both will call find ticket for games API from their mobile devices. Each time they invoke APIs we cannot ask them to send their details. They will only send access token which is mandatory for their security.
When request come to API Manager it will first validate token. Then if user is authenticated to call service we will follow up with next steps.
From access token we can get username of the user.Then we can get user attributes and create JSON payload with it.
Then API Management server will send user details as JSON payload in transport header.
So when request reach backend server they can get user details from JWT message. Then back end server will generate customized response for each user.
Bob will get response with cricket events happens around colombo area while Frank is getting response with football events happen in germany.

This is one of the most common use case of JWT.


In most production deployments, service calls go through the API manager or a proxy service. If we enable JWT generation in WSO2 API Manager, then each API request will carry a JWT to the back-end service. When the request goes through the API manager, we can append the JWT as a transport header to the outgoing message. So, the back-end service can fetch JWT and retrieve required information about the user, application, or token. There are two kinds of access tokens we use to invoke APIs in WSO2 API Manager.

Application access token: Generate as application owner and there is no associated user for this token (the actual user will be the application owner). In this case, all information will be fetched from the application owner, so the JWT will not have real meaning/usage when we use the application access token.
User access token: User access tokens are always bound to the user who generated token. So, when you access the API with user access token, the JWT will generate user details. On the back-end server side, we can use this to fetch user details.
Sample JWT message

As you can see JWT contain claims associated with User (end user TenantId, full name, given name, last name, role, email address, user type) API (API context, version, tier), Subscription (keytype, subscriber)
Application (application ID, application name, application tier)

However, in some production deployments, we might need to generate custom attributes and embedded to the JWT.

Thursday, March 9, 2017

SMS OTP Two Factor Authentication for WSO2 API Manager publisher

In this post, I will explain how to use SMS OTP multi factor authenticator through WSO2 Identity server. We will be using Twilio SMS Provider which was used to send the OTP code via SMS at the time authentication happens. For this solution we will 2 WSO2 API Manager(2.1.0) and Identity server(5.3.0). Please note that we need to set port offset as 1 in carbon.xml configuration file available with identity server. So it will be running on https 9444 port.

First to to and create account there. Then provide your mobile number and register that.

Then generate mobile number from twilio. Then it will give you new number for you to use.

curl -X POST '{Account-Sid}/SMS/Messages.json'  --data-urlencode 'To={Sender SMS}' --data-urlencode 'From={generated MobileNumber from Twilio}' --data-urlencode 'Body=enter this code'  -H 'Authorization: Basic {base64Encoded(Account SId:Auth Token)}'

Please see the sample below.

curl -X POST ''  --data-urlencode 'To=+94745345779' --data-urlencode 'From=+1454543535' --data-urlencode 'Body=enter this code'  -H 'Authorization: Basic LKJADJAD:ADJLJDJ:LAJDJDJJJJJJL::LMMIYGBNJN=='

Now it should send you message to your mobile number provided.

Now login to identity server and create new identity provider. When you do that provide following inputs in user interface.
Screenshot from 2017-03-09 15-09-17.png

Then go to federated authenticator section and add SMS OTP Configuration as follows. Provide basic authentication credentials like we did for CuRL request.

Please fill following fields as below.
SMS URL:   HTTP Method: POST    HTTP Headers: Authorization: Basic QUNkNWFjN2ZmOTNTNmNjMzOWMwMjBkZQ==HTTP Payload: Body=$ctx.msg&To=$ctx.num&From=+125145435333434

Screenshot from 2017-03-09 15-10-01.png

Then let's add service provider as follows. Provide service provider name as follows.

Screenshot from 2017-03-09 15-29-50.png

Then go to SAML2 web SSO configuration and provide following configurations. Then save it and move forward.

Screenshot from 2017-03-09 15-30-08.png

Now save this service provider and come back to identity server UI. Then we need to configure local and outbound authentication steps as follows. We need to configure advanced authentication configuration as we are going to configure multi step authentication.

Screenshot from 2017-03-09 16-47-42.png

Then add username and password based local authentication as first steps and add out SMS otp as second authentication step. Now we can save this configuration and move forward.

Screenshot from 2017-03-09 16-48-12.png

Also add following configuration to wso2is-5.3.0/repository/conf/identity/application-authentication.xml file and restart server.

<AuthenticatorConfig name="SMSOTP" enabled="true">
             <Parameter name="SMSOTPAuthenticationEndpointURL">https://localhost:9444/smsotpauthenticationendpoint/smsotp.jsp</Parameter>
             <Parameter name="SMSOTPAuthenticationEndpointErrorPage">https://localhost:9444/smsotpauthenticationendpoint/smsotpError.jsp</Parameter>
             <Parameter name="RetryEnable">true</Parameter>
             <Parameter name="ResendEnable">true</Parameter>
             <Parameter name="BackupCode">false</Parameter>
             <Parameter name="EnableByUserClaim">false</Parameter>
             <Parameter name="MobileClaim">true</Parameter>
             <Parameter name="enableSecondStep">true</Parameter>
             <Parameter name="SMSOTPMandatory">true</Parameter>
             <Parameter name="usecase">association</Parameter>
             <Parameter name="secondaryUserstore">primary</Parameter>
             <Parameter name="screenUserAttribute"></Parameter>
             <Parameter name="noOfDigits">4</Parameter>
             <Parameter name="order">backward</Parameter>

Now it's time to configure API publisher to configure, so it can work with identity server to do authentication based on SSO. Add following configuration to /wso2am-2.1.0/repository/deployment/server/jaggeryapps/publisher/site/conf/site.js file.

 "ssoConfiguration" : {
       "enabled" : "true",
       "issuer" : "apipublisher",
       "identityProviderURL" : "https://localhost:9444/samlsso",
       "keyStorePassword" : "",
       "identityAlias" : "",
       "keyStoreName" :"",
       "signRequests" : "true",
       "assertionEncryptionEnabled" : "false",
       "idpInit" : "false",

Now go to API publisher URL and you will be directed to identity server login page. There you will see following window and you have to enter user name and password there.

Then once you completed it you will get SMS to number you have mentioned in your user profile. If you havent already added mobile number to your user profile please add by login to identity server. You can go to users and roles window and select user profile from there. Then edit it as follows.

Then enter the OTP you obtain in next window.