Authorize Service Application

Introduction

In this tutorial you will create Service application. Learn how client_credential flow works and how to get access token with it. And in the end we will double check if token is truly valid by making request to one of iTwin Platforms API endpoint.

Info

Skill level:

Basic

Duration:

10 minutes

1. Register an Service Application

Service application is designed to operate without user interaction (sometimes called two-legged OAuth) in order to access web-hosted resourced by using the identity of an application. Services run on a server where the source code or configuration of the application is not available to the public. This allows the use of a client secret when communicating with the authorization server to help improve security.

To be able to register application you need to be Signed in. If you are not already you can do that in action pane by clicking Sign In button or in the headers top right corner.

You will need to register an application to be able consume/use iTwin Platform APIs. To make your tutorial more interactive please use the Register Application button.

After you click this button it will registers an client and will display its settings.

  • client_id: This is the unique identifier for your application. It is displayed on the application details page as Client ID.
  • client_secret: Secret that was created and shown first time you created an application.
  • scope: List of accesses granted to the application. Displayed on the application details page as Scopes.
For future use: You can register applications in My apps page. But it is not recommended for this tutorial

2. Get Access Token

An Access Token is token which contains a string that can be used to make authenticated requests to an API to access protect resources (in this case iTwin Platform APIs). The string has no meaning to the application using it, but represents that the user has authorized the application to access their account. The token is bounded by an appropriate lifetime, scopes, and other information that the server may require.

Client credentials flow provides the ability for a web service (confidential client) to use it’s own credentials, instead of impersonating a user, to authenticate when calling a web service. Permissions are granted directly to the application itself by an administrator. When the app presents a token to a resource, the resource enforces that the app itself has authorization to perform an action since there is no user involved in the authentication.

You can find more information here, but it is more technical.

To sum up in simpler terms:

  • No user interaction,
  • No user context/information,
  • You will use client id and client secret and scope to get access token.

You need to call the token endpoint with the Content-Type header equal to application/x-www-form-urlencoded.

Request body (with url encoded characters):

  • client_id: Identification that is generated when the application is created. You can find it in the My Apps page. If you generated it during this tutorial you can find it in the first step.
  • client_secret: Secret that was created and shown first time you created an application
  • scope: Space separated scopes (in this tutorial: users:read)
  • grant_type: client_credentials it indicates what flow is in use and client_credentials basically means that you will provide client_id and client_secret as credentials for fake user.

Request to Token endpoint


HTTP
POST https://ims.bentley.com/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=users%3Aread&grant_type=client_credentials

Response contains:

  • token_type: Bearer this is part of Authorization header that is constructed like Authorize: token_type access_token you can read more here.
  • access_token: access token itself (in JWT format) that will be passed into Authorize header for api calls as Bearer JWT_TOKEN.
  • expires_in: lifespan of access token in seconds.

Response from the Token endpoint


JSON
{
  "access_token": "JWT_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3599
}

This request will show that newly created access token is valid and will show how to use it. /users/me endpoint would retrieve the logged in user’s profile, but because authorization was done without user interaction it will contain “fake” user information that is associated with this Service application.

Request to /users/me endpoint


HTTP
GET https://api.bentley.com/users/me HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.itwin-platform.v1+json

Because service applications does not require user interaction it does not contain any user context or in simpler terms access token does not contain any user information and it gets assigned to “fake” user and you can see details in this response. To give this application any additional access you need give extra roles, that can be done by administrator more information about that.

Response from /users/me endpoint


JSON
{
  "user": {
    "displayName": "CLIENT_ID@apps.imsoidc.bentley.com",
    "givenName": "CLIENT_NAME",
    "surname": "LastName",
    "email": "CLIENT_ID@apps.imsoidc.bentley.com",
    "alternateEmail": "CLIENT_ID@apps.imsoidc.bentley.com",
    "city": null,
    "country": "US",
    "language": "EN",
    "createdDateTime": "2021-08-27T10:19:07.2510000Z"
  }
}