Tutorial: How to Authenticate a User for your Application

Goal of this tutorial:

Preconditions: To be able to authenticate users for your application, you must have the role experimenter assigned. You created an experiment within the Organicity Experimenter Portal. * The Experimenter Portal provides you a client_id and a client_secret, both is needed in this tutorial.

Organicity Accounts provides unified user management to the whole Organicity platform. Of course, a unified experience requires all Organicity components to properly talk to Organicity Accounts. This document guides through the process of setting your component up.

OAuth2 Grants

Organicity Accounts is an OAuth2 server, which provides a Single Sign-On (SSO) service. Thus, you can login to all Organicity Components by using one single account. In case of web-applications, you even just need to login once. Probably you know this from Google: To use gmail, youtube or the calendar, you use the same account.

Client ID + Client Secret

After creating your experiment within the Experimenter Portal, you will receive a client_id and a client_secret:

Grant Types

The OAuth2 specification provides several Grant Types for different types of applications:

In this two grants, after a successful login, the applications will act in name of the user. There is one more important grant:

Per default, this grant ist not enabled for experiments.

Endpoints

The following endpointd are needed by the grants described below:

Authorization Code Grant

As said before, this grant is used for applications running on a web server. Thus, the source code of the web-application keeps the client_secret confidential. This grant is divided in two flows:

For the first flow, you must extend the authorization endpoint with the following query parameters:

HINT: Make sure, that you're web-application, and thus the redirect_uri, runs on HTTPS. This ensures, that the exchanged data cannot be intercepted during the login process.

Thus, 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>

An example:

 https://accounts.organicity.eu/realms/organicity/protocol/openid-connect/auth?response_type=code&client_id=example&redirect_uri=https://example.com/callback 

Calling this URL, the users must login with their credentials. If the login is successful, the user is redirected back to the configured redirect URI. OAuth2 appends one parameter to the URL:

Thus, the full callback URL looks as follows:

<REDIRECT_URI>?code=<CODE>

An example:

https://example.com/callback?code=0123456789

Now, the second flow starts. You're web-application takes this code and must send an HTTP POST request to the token endpoint, with the following parameters:

HINT: Make sure, that this call is done from the web-application in the background, thus the client_secret stays confidential!

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=client_credentials&code=<CODE>&rediret_uri=<REDIRECT_URI>

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=client_credentials&code=<CODE>&rediret_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Calling this URL, the server verifies your credentials and the code. If successful, the server returns a JSON, which contains the following attributes:

An example:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "bearer",
    "expires_in": 300,
}

See here for further details on the Access Tokens.

Implicit Grant

HINT:

This grant is used for browser-based applications (e.g., JavaScript-only applications without a server-side component) or mobile apps. These kind of applications cannot keep the client_secret confidential. The Implicit Grant has just one flow, which returns the Access Token directly. The Grant is called implicit, as no intermediate credentials (such as an authorization code) are issued.

For this grant, you must extend the authorization endpoint with the following query parameters:

HINT: Make sure, that you're web-application, and thus the redirect_uri, runs on HTTPS. This ensures, that the exchanged data cannot be intercepted during the login process.

Thus, the full authorization URL looks as follows:

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

An example:

 https://accounts.organicity.eu/realms/organicity/protocol/openid-connect/auth?response_type=token&client_id=example&redirect_uri=https://example.com/callback

Calling this URL, the users must login with their credentials. If the login is successful, the user is redirected back to the configured redirect URI. OAuth2 appends one parameter to the URL:

The JSON contains the following attributes (similar to the Authorization Code Flow):

An example:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "bearer",
    "expires_in": 300,
}

See here for further details on the Access Tokens.

Client Credential Grant

HINT: The Client Credential Grant is used for applications (e.g, clients), which act on their own.

To authorize a client, you perform a simple HTTPS request with your client_id and client_secret, which will return an 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=client_credentials

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=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Answer for Option A and Option B

The request returns a JSON record, which contains the following attributes:

An example:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "bearer",
    "expires_in": 300,
}

Libraries

Of course, you do not have to write you're own OAuth2 adapter. You can use well-tested existing librabries, like the following:

For these two, we created two minimal working examples:

In order to talk to Organicity Accounts, your component needs to talk to the Accounts Server using any of the above mentioned grants.

Sources on OAuth2