Authorize a Service Application - Tutorials

Introduction

When building a server-side app that securely stores secrets, use the following procedures to set up your authorization.

IMPORTANT

Keep your client credentials, i.e., client ID, client secret, and access tokens, secure. Do not include them in publicly accessible code where they could be discovered. Instead, store them safely on a backend server.

Note

Service apps need permission to access the your iTwin’s or iTwin-related data. iTwin roles and permissions are set up using the Access Control API and the generated email on the App Details page in My Apps > App Name. Setting up access control is not necessary for this tutorial; however, it must be set up before making requests to the APIs.

Before you begin

This guide requires you to have:

A registered service application. If you have not created an application, open the My Apps page under your Profile menu and click the Register New button. For this guide, the application type is Service.
The client_id and the client_secret supplied when you create your application. Make sure to save this data in a secure location.

Note

There is an optional step at the end of the tutorial that enables you to test the token you received beyond the successful HTTP response.

Client credential flow

The Client Credential Flow allows your backend process or service, i.e., a confidential client, to authenticate using its own credentials rather than impersonating a user.

An administrator grants permissions directly to the application. Since no user is involved in the authentication, the resource enforces that the application is authorized to perform an action when it presents a token to a resource.

The following steps provide an overview of the process.

The application makes a request to the authorization server token endpoint with the required parameters.
The authorization server confirms the information supplied and returns an access token.
The application uses the access token to call a given API.
The API responds to the request with the requested data when the necessary scopes are included in the token, and the service identity has the proper permissions for that API.

sequenceDiagram participant app as Application participant as as Authorization Server participant api as iTwin API app->>+as: Authenticate using client_id and client_secret as->>as: Validate client_id, client_secret and scopes as->>-app: Granted access token app->>+api: API request with the access token api->>-app: API response

Set up authorization for your app

The following guide steps you through retrieving an access token for your service application. Once you have your app registered, you can begin to obtain the access token.

Obtain an access token

To obtain an access token for your app, follow these steps:

Send a request to the authorization server endpoint.
POST
https://ims.bentley.com/connect/token
The authorization request requires the following parameters:
Parameter
Description
grant_type
Set to client_credentials for service-based applications.
client_id
The ID of the app you created. If you forgot the ID, find it on the My Apps page. Locate your app in the list. The Client ID is in the same-named column.
client_secret
The secret given when you registered the app. If you did not save the client secret, generate a new one. To do so, open the My Apps page and find your app in the list, click the link to open the Details page, and then click Re-generate in the Client Secret field.
scope
Add the itwin-platform scope assigned to your app during registration.
The authorization server confirms the client_id and client_secret and returns an access token. Bentley’s authorization server completes this step. There is no implementation needed in your application. A successful response includes the access token.
Use the access token to call the API. Remember to call iTwin platform APIs, you must set up your iTwin roles and permissions. For more information, see the Access Control API documentation.

Token request example

Test your token

If you received a 200 OK response to your token request, you have successfully obtained a token. You can use this token to call various iTwin Platform APIs. You can try making an API call to users/me endpoint to test your token. On success, this request returns the profile information for the user account associated with the token received.

Remember, the iTwin Platform Base URI is api.bentley.com.

More resources that you may like

Access Control

Manage Access Controls for your iTwin member using iTwin roles and permissions.