Authorize a Service Application

Introduction

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

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.

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.

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

---

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.

More resources that you may like