Get Started
Documentation
Samples

Authorize a Service Application

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 assumes you have:

  • Registered a service application with the necessary scopes for your use case. If you have not created an application, open the My Apps page under your Profile menu to create one. For this guide, the application type is Service.
  • The client_id and the client_secret supplied when you created your application.

Note

There is an optional step at the end of the tutorial that enables you to validate the token you received beyond the successful HTTP response. If you would like to perform this step, your app must have the users:read scope assigned.

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.

  1. The application makes a request to the authorization server token endpoint with the required parameters.
  2. The authorization server confirms the information supplied and returns an access token.
  3. The application uses the access token to call a given API.
  4. 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 steps guide you through setting up your application and retrieving an access token with the needed permissions for your service application and identity.

Register a service application

  1. Click your profile button in the upper-right corner of the page. You must be logged in to the Developer Portal.
  2. Select My Apps from the drop-down.
  3. Click the Register New button.
  4. Enter the name of your application. Service apps have a maximum of 60 characters, the following characters are not allowed: ,;[]=\<>?"{}|+!@#\$%\^*`~
  5. Select the appropriate scopes for your application in API associations.
    Selected scopes are listed in the Allowed scope list box.
  6. In Application Type, click Service to indicate you are creating a Service app.
  7. Click Save.
  8. On the Success dialog, click Copy to copy the client_id and client_secret created for your app. Make sure you save this data in a secure location. It is required to obtain a token.
    Close the dialog by clicking the X in the upper-right corner or clicking outside the box.

Obtain an access token

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

  1. 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 scopes assigned to your app during registration. Scopes enable the application to access requested resources. Separate multiple scopes with a space. Note: Needed scopes for each API are in their respective reference documentation pages.

  2. 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.

  3. 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

HTTP Request
Body
Validate your token
If you received a 200 OK response to your request for a token, it is not necessary to validate it. However, the users/me endpoint is provided if you would like to do so. This returns the profile information for the user account assigned to the service when you created your service application.
Remember, the iTwin Platform Base URI is api.bentley.com.
HTTP Request
More resources that you may like
Access Control
Manage Access Controls for your iTwin member using iTwin roles and permissions.