Tutorial: How to Refresh Tokens

Goal of this tutorial:

Preconditions:

Authentication in Organicity is activity-centere: Users acquire Access Tokens to perform an action with them in the next minutes. Access Tokens invalidate after 5 minutes, and have to be renewed with Refresh Tokens.

While this is good for security, it is unusable for long-term applications that run without supervision, like environmentally deployed sensor nodes. As these nodes still need to contact Organicity, for example to post measured data, they need a way to authenticate. This is facilitated by Refresh Tokens.

Please note: In order to generate Offline Tokens, a user needs to have the required role offline_access. Usually, every user gets this role when they sign up.

Acquire Refresh Tokens

To acquire Refresh Tokens, you just need to append the additional query parameter scope=offline_access to your Authorization Endpoint.

Authorization Code Grant

The flow is the same as described here, just with the additional query parameter scope=offline_access.

The full authorization URL looks as follows:

 https://accounts.organicity.eu/realms/organicity/protocol/openid-connect/auth?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=offline_access

As in the Authorization Code Grant, it returns an Authorization Code which must be converted into an Access Token.

If successful, the server returns a JSON, which contains the following attributes:

An example:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "bearer",
    "expires_in": 300,
    "refresh_token": <REFRESH_TOKEN>,
    "typ": Offline",
    "refresh_expires_in": 0
}

Implicit Grant

This grant cannot return a refresh token, because the application cannot keep the client_secret confidential (see below).

Client Credential Grant

This grant cannot return a refresh token, because this grant directly returns the Access Token.

Refresh Token Grant

To use a the Refresh Token Grant, you perform a simple HTTPS call, which will return a new suitable Access Token.

Option A (client_id and client_secret in the header):

POST /realms/organicity/protocol/openid-connect/token HTTP/1.1
Host: accounts.organicity.eu
Authorization: Basic <BASE64_ENCODE(<CLIENT_ID>:<CLIENT_SECRET>)> 
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>

The Authorization header contains your client_id and client_secret encoded with HTTP basic authentication. For details on how to create this field, see here.

Option B (client_id and client_secret in the body):

POST /realms/organicity/protocol/openid-connect/token HTTP/1.1
Host: accounts.organicity.eu
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Please note, that the same client_id and client_secret is needed to refresh the token.

The server verifies your credentials and the refresh token. If successful, the server returns a JSON record as described above.

Please note

Code Sample

Next we will describe a way, how you get Offline Tokens with the node.js tool accounts-demo-passport.

To get the initial Refresh Token, please install the tool as described in the README. Change the file server/auth/oauth2.js by adding your client_id and client_secret and run the application. The application runs on port 3000 by default. Set the environment variable PORT to another if needed (e.g., PORT=4000). Make sure, that you configure the following callback URL in the Experimenter Portal:

Afterwards, open the application within your browser:

Please login with your username and password (or social login) and open the profile page. There you find two tokens: an Access Token and a Refresh Token.