Authorize Single-Page Application (SPA)

Introduction

When developing Single Page Applications (SPA), we use a client-side framework and the following procedures to set up authorization.

Before you begin

This guide requires you to have:

• A registered SPA. 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 SPA.
• A redirect URI of https://developer.bentley.com/redirect-tutorial. Add this redirect URI during app registration, or on the App Details for a previously registered application. The App Details page can be accessed through the My Apps page.
• The client_id of your application. You can copy the client_id from the App page by clicking the Copy button below the title.

User authorization code flow

SPAs can use the OAuth 2.0 Authorization Code Flow to enable data owners to authorize third-party apps to access user data. However, as opposed to web apps, SPA applications cannot keep a client secret as the entire source is available to the browser. In order to mitigate this, OAuth 2.0 provides an option for Proof Key for Code Exchance (PKCE) by OAuth Public Clients (see OAuth 2.0 RFC 7636) to securely obtain an authorization code. PKCE allows the calling application to dynamically generate a random, one-time key called a "code verifier" to accomplish this.

The following steps provide an overview of this process.

1. The application generates a cryptographically random code_verifier and from this generates a code_challenge.
2. The application makes a request to the authorization server endpoint.
3. The end-user provides their authentication information and consents for the application to access resources on their behalf.
4. The authorization server stores the code_challenge and returns an authorization code to the Redirect URI specified when creating the application.
5. The application uses the authorization code and code_verifer to obtain an access token from the authorization server.
6. The application uses the access token to call the API on behalf of the user.

Set up authorization for your app

The following guide steps you through retrieving an access token for your SPA. 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:

1. Generate code_verifier and code_challenge.

2. When the user opens the SPA, redirect them to the authorization server endpoint.

The request for an authorization code requires the following parameters:

Please copy the code_challenge generated above.

3. The user signs in to authenticate and consents for the application to access resources on their behalf. This page is managed by the Bentley authorization server and does not require any implementation in your application.

   

   Once authenticated, the Bentley authorization server returns an authorization code to the Redirect URI registered with your application. Extract the code in the response from the redirect_uri field.

   https://example-rediect-uri/?code=<code>

   Note

   Authorization codes are time-sensitive. If your code expires, send a new request to the authorization server for a new code.

4. Send a request to the token endpoint to exchange the authorization code for an access token.

   POST

   https://ims.bentley.com/connect/token

   The authorization request requires the following parameters:

   Field Name

   Description

   client_id

   Identification generated during application creation. Found in the My Apps page or in the first step if generated during the tutorial.

   grant_type

   Set to authorization_code Indicates the type of grant being used. This tells the service you are exchanging the code for a token.

   code_verifer

   The one-time-use code verifier generated by your Application.

   code

   This is the authorization code returned in the previous request.

   redirect_uri

   The callback URL you entered when registering your application. This URL must match the URL provided in the initial request.

5. The authorization server confirms the information sent in the request 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, with an expiry of 3600 seconds. The token is Bearer type, which must be specified in your API calls.

6. Use the access token to call the API. Tokens are added to the Authorization header with Bearer type in subsequent requests. Successfully sending a request to an API requires the end user to have the correct account permissions. Use the Access Control API to ensure your user can access the required resources.

Refresh token

Unlike native and web apps, SPAs don’t require a refresh token when the access token expires. This is because they can renew a session that is about to expire using a background silent sign-in.

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