NAO Cloud can act as an Oauth2 resource and authorization server.

Overview

The benefits of Oauth2 authentication is two-fold:

• Users log in once on NAO Cloud, and automatically get logged-in to your site
• Your site gets an access token to authenticate with NAO Cloud REST API without the user having to explicitely provide it.

The authentication steps are:

• user arrives at your site, you say “Login through NAO Cloud” and redirect her to NAO Cloud’s authentication URL with a callback URL
• user authenticates with email/password on NAO Cloud and gives your app permission to access her account. The user is now logged-in on NAO Cloud.
• NAO Cloud redirects the user to your callback URL, giving your site a grant code at the same time
• Your site makes a request to NAO Cloud token endpoint end gets back a access token, using the grant token
• Your site makes a request to me endpoint to get the user info (ID, name and email), using access token
• Your site can then authenticate the user.
• • it either finds the NAO Cloud User ID in your database or creates a new record,
• • it then logs the user in (e.g: set the right cookies or session variables)
• Your site can use the access token to make subsequent requests to NAO Cloud REST API until the token expires

Prerequisites

Credentials

First you need to get your app registered on NAO Cloud and get your App credentials. App credentials have 2 keys client_id and client_secret. Let’s assume that your Keys are:

  CLIENT_ID = 5c37d709a5d1e3fc4c5a7e06dcf99ce66cffd86683948baedb9847b3b99706f3
  CLIENT_SECRET = 37c705fc25993e47b0abd1ea3cd10b714f12f3101b4134a13fc94089dcbb517e

Your users also should have a valid NAO Cloud account.

Callback URL

You then need to provide a callback URL that NAO Cloud will call to give your app the grant token and access token. grant token is required to request a access token which can be used in subsequent requests to access NAO Cloud resources via the REST API. Both tokens will eventually expire.

Let’s assume that your callback URI is:

http://yourdomain.com/callback

User logs in through NAO Cloud

When a new user arrives at your app, you can show them a link saying “Login through NAO Cloud”.

When the user clicks on the link, you should redirect her to NAO Cloud’s grant token endpoint (all params should be in the path):

GET /oauth/authorize HTTP/1.1
client_id: CLIENT_ID
redirect_uri: CALBACK_URI
response_type: code
state: b91692747248010028095e1845dcea29ea23cd935d4c2cfc

Please note the state parameter, it is used to prevent Cross Site Request Forgery (XRSF) attacks. XRSF attacks are not new or specific to OAuth. The way to prevent them in OAuth is to include something in the request that the client can verify in the response but that an attacker could not know.
An example of this would be a hash of the session cookie or a random value stored in the server linked to the session.
If the OAuth client verifies the value returned than it will reject authentication responses that were generated as the result of requests by third party attackers trying to log the user in in the background without the users knowledge. The state parameter is just a string so any other information can be encoded in it.

Curl

curl -L -v -s "http://localhost:3000/oauth/authorize?client_id=5c37d709a5d1e3fc4c5a7e06dcf99ce66cffd86683948baedb9847b3b99706f3&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2Fauth%2Fnaocloud%2Fcallback&response_type=code&state=b91692747248010028095e1845dcea29ea23cd935d4c2cfc" -o /dev/null

Response with redirection

HTTP/1.1 302 Found
Location: http://localhost:3000/login

If the user is not yet logged-in on NAO Cloud, the User Agent is redirected to the NAO Cloud’s login page, where the user will authenticate herself with email and password.

Once logged-in, if the user has not yet given your app permission to access her account, NAO Cloud will ask her.

Let’s assume the user gives her permission. NAO cloud will redirect the User Agent to your callback URI with the same state parameter as your initial request and a code parameter which is the grant token.

Response with redirection

HTTP/1.1 302 Found
Location: http://yourdomain.com/callback?code=e515044412577d9940fc676e3c5466bfd2112a3adfc12e362be2f4e1f6f10471&state=b91692747248010028095e1845dcea29ea23cd935d4c2cfc

The grant token here is : e515044412577d9940fc676e3c5466bfd2112a3adfc12e362be2f4e1f6f10471. We will use this to request the access token

Your App requests Access Token

You can use the following endpoint to request the access token:

POST /oauth/token HTTP/1.1
client_id: CLIENT_ID
client_secret: CLIENT_SECRET
code: GRANT_TOKEN
grant_type: authorization_code
redirect_uri: CALBACK_URI

Curl

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=5c37d709a5d1e3fc4c5a7e06dcf99ce66cffd86683948baedb9847b3b99706f3&client_secret=37c705fc25993e47b0abd1ea3cd10b714f12f3101b4134a13fc94089dcbb517e&code=e515044412577d9940fc676e3c5466bfd2112a3adfc12e362be2f4e1f6f10471&grant_type=authorization_code&redirect_uri=http://localhost:5000/auth/naocloud/callback' 'http://localhost:3000/oauth/token'

Reponse

{
    "access_token":"7ec6d18197760f7bb2f59378a62bbdaa84854b95fec30ed2cffcb0bcf3782bcb",
    "token_type":"bearer",
    "expires_in":7200,
    "created_at":1472820355
}

So now you have the access token that you can use to find out who the user is.

Your App requests User info

To find out who the user is, use the following request using the access token in the Authorization header:

GET /api/v2/me HTTP/1.1
Authorization: Bearer ACCESS_TOKEN

Curl

curl -X GET --header 'Authorization: Bearer 7ec6d18197760f7bb2f59378a62bbdaa84854b95fec30ed2cffcb0bcf3782bcb' 'http://localhost:3000/api/v2/me'

Response

{
    "user":
    {
        "id":1,
        "email":"long.nguyen@polestar.eu",
        "name":"Thanh long Nguyen",
        "admin":false,
        "site_ids":[]
    }
}

Now you can use the user info to authenticate the user on your system.

Conclusion

Congratulations! You can now use NAO Cloud’s Oauth2 mechanism to build a Single Sign On system!