Labforward API - Authentication

This article describes how to authenticate against any of the API provided by Labforward products using a Labforward account and OAuth 2.0.

If you are not yet familiar with OAuth, you can get started with some useful resources to understand the basics.

Step 1: Registering an OAuth 2.0 Client

1. You'll be able to register an OAuth 2.0 Client after logging in to your Labfoward account, by clicking on OAuth2 in the left menu navigation.

2. On the "OAuth2 Client Registration Page", proceed by clicking on CREATE NEW OAUTH2 CLIENT.

3. Fill in the required "Client Name" and "Redirect Url" as needed by your API integration requirement and click SAVE.

4. The OAuth2 Client table view will provide you with the necessary "Client ID" and "Client Secret", which will later be needed in the chosen authentication flow. It is very important that you treat the "Client Secret" as highly sensitive data with utmost secrecy. Just as you would do with a personal user account, because that is what it effectively resembles.

Step 2: Choosing the OAuth 2.0 Grant Types

In OAuth 2.0, the term “grant type” refers to the way an application (OAuth2 Client) gets an access token. OAuth 2.0 defines several grant types of which Labforward supports the authorization code flow and refresh token flow. Using the access token, the application will be able to access the user data, and perform action on behalf of the user in Labforward platform.

OAuth 2.0 Authorization Code Flow

This grant types is typically used by web and mobile application to integrate into the Labforward platform. This flow requires access to the browser and the end-user presence to authorize the application to access their Labforward data.

At a high level, the flow has the following steps:

1. The application opens a browser to send the user to the OAuth server.
2. The user sees the authorization prompt and approves the app’s request.
3. The user is redirected back to the application with an authorization code in the query string.
4. The application exchanges the authorization code for an access token.

Requesting the user authorization requires the application to direct the user to the following URL:

https://account.labforward.app/realms/labforward/protocol/openid-connect/auth
  ?response_type=code
  &client_id=XXXXXXXX
  &redirect_uri=http%3A%2F%2Fexample.com%2Foauth%2Fcallback
  &scope=openid+profile+offline_access
  &state=[random-string]

Which consist of the following query parameters

• response_type=code - Enables OAuth 2.0 Authorization Code Flow
• client_id - Your OAuth 2.0 Client ID
• redirect_uri - The Redirect Uri configured for your OAuth 2.0 Client
• scope - The desired authorization scope
• state - (Optional) A random string that the application generates and includes in the request. The exact same string will be included in the redirection after the user authorized the request. The application can check that the same value is returned to protect against CSRF attacks.

After user authorize the application, the user will be redirected to the following URL:

https://example.com/oauth/callback
  ?session_state=[uuid-string]
  &code=[authorization-code]
  &state=[random+string]

Which consist of the following query parameters

• session_state - JSON string that represents the End-User's login state, as defined by OpenID Connect Session Management 1.0
• code - The Authorization Code that you would need to exchange with Access Token
• state - (Optional) A random string that the application generates and includes in the request. The exact same string will be included in the redirection after the user authorized the request. The application can check that the same value is returned to protect against CSRF attacks.

Finally, you will need to exchange the Authorization Code for an Access Token by sending the following Back-Channel POST request:

curl \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=authorization_code&code=[authorization-code]&client_id=XXXXXXXX&client_secret=XXXXXXXX&redirect_uri=http%3A%2F%2Fexample.com%2Foauth%2Fcallback' \
  "https://account.labforward.app/realms/labforward/protocol/openid-connect/token"

Which consist of the following request body

• grant_type=authorization_code - Enables OAuth 2.0 Exchange of Authorization Code for Access Token
• code - The Authorization Code that was returned by the previous step
• client_id - Your OAuth 2.0 Client ID
• client_secret - Your OAuth 2.0 Client Secret
• redirect_uri - The Redirect Uri configured for your OAuth 2.0 Client

If everything checks out, you'll get the following JSON object as a response:

{
  "access_token":"JWT Token",
  "expires_in":86400,
  "refresh_expires_in":0,
  "refresh_token":"JWT Token",
  "token_type":"Bearer",
  "not-before-policy":0,
  "session_state":"UUID string",
  "scope":"profile email offline_access"
}

OAuth 2.0 Refresh Token Flow

This grant type is used by application to exchange a refresh token for an access token when the access token has expired. This allows applications to continue to have a valid access token without further interaction with the user.

To do so, you will need to exchange the Refresh Token for an Access Token by sending the following Back-Channel POST request:

curl \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=refresh_token&refresh_token=[JWT Token]&client_id=XXXXXXXX&client_secret=XXXXXXXX&redirect_uri=http%3A%2F%2Fexample.com%2Foauth%2Fcallback' \
  "https://account.labforward.app/realms/labforward/protocol/openid-connect/token"

Which consist of the following request body

• grant_type=refresh_token - Enables OAuth 2.0 Exchange of Authorization Code for Access Token
• code - The Authorization Code that was returned by the previous step
• client_id - Your OAuth 2.0 Client ID
• client_secret - Your OAuth 2.0 Client Secret
• redirect_uri - The Redirect Uri configured for your OAuth 2.0 Client

Step 3: Authorizing the API Request

Whichever grant flow was chosen, once you have an Access Token, you can authenticate the API requests against any API endpoint provided by Labforward product, by including the Access Token as Bearer token in the Authorization header, e.g.

curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer [access_token]" \
  https://account.labforward.app/realms/labforward/account/