Use OAuth 2.0 implicit grant flow within your portal

Note

Effective October 12, 2022, Power Apps portals is Power Pages. More information: Microsoft Power Pages is now generally available (blog)
We will soon migrate and merge the Power Apps portals documentation with Power Pages documentation.

This feature allows a customer to make client-side calls to external APIs and secure them using OAuth implicit grant flow. It provides an endpoint to obtain secure access tokens. These tokens will contain user identity information to be used by external APIs for authorization following OAuth 2.0 implicit grant flow. The identity information of a signed-in user is passed in a secured manner to the external AJAX calls, which helps developers to pass authentication context and will also help users secure their APIs.

OAuth 2.0 implicit grant flow supports token endpoints that a client can call to get an ID token.

Custom certificates

Using the default certificate for OAuth 2.0 implicit grant flow is deprecated. You will need to use a custom certificate while using the OAuth 2.0 endpoint. Use the Power Platform admin center to upload the custom certificate. After uploading the custom certificate, you need to update site settings as below:

  1. Go to portal settings and select Site Settings.

  2. To create a new setting, select New.

  3. To edit an existing setting, select the site setting listed in the grid.

  4. Specify values:

    • Name: CustomCertificates/ImplicitGrantflow
    • Website: The associated website
    • Value: Copy the thumbprint of the uploaded custom certificate from the Manage custom certificate screen and paste it here. The value will indicate which certificate will be used for implicit grant flow.
  5. Select Save & Close. General menu for New Site Settings with values specified.

Token endpoint details

You can also get a token by making a post request to the /token endpoint. The URL for token endpoint is: <portal_url>/_services/auth/token. The token endpoint supports the following parameters:

Parameter Required? Description
client_id No A string that is passed when making a call to the authorize endpoint. You must ensure that the client ID is registered with the portal. Otherwise, an error is displayed. Client ID is added in claims in the token as aud and appid parameter and can be used by clients to validate that the token returned is for their app.
The maximum length is 36 characters. Only alphanumeric characters and hyphen are supported.
redirect_uri No URL of the portal where authentication responses can be sent and received. It must be registered for the particular client_id used in the call and should be exactly the same value as registered.
state No A value included in the request that also is returned in the token response. It can be a string of any content that you want to use. Usually, a randomly generated, unique value is used to prevent cross-site-request forgery attacks.
The maximum length is 20 characters.
nonce No A string value sent by the client that is included in the resulting ID token as a claim. The client can then verify this value to mitigate token replay attacks. The maximum length is 20 characters.
response_type No This parameter supports only token as a value, allowing your app to immediately receive an access token from the authorize endpoint without making a second request to the authorize endpoint.

Note

Even though client_id, redirect_uri, state, and nonce parameters are optional, it is recommended to use them in order to make sure your integrations are secure.

Successful response

The token endpoint returns state and expires_in as response headers, and token in the form body.

Error response

The error in a token endpoint is returned as a JSON document with the following values:

  • Error ID: Unique identifier of the error.
  • Error message: A specific error message that can help you identify the root cause of an authentication error.
  • Correlation ID: A GUID that is used for debugging purposes. If you have enabled diagnostic logging, correlation ID would be present in server error logs.
  • Timestamp: Date and time when the error is generated.

The error message is displayed in the default language of the signed-in user. If the user isn't signed in, a sign-in page is displayed for the user to sign in. For example, an error response looks as follows:

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }

Authorize endpoint details

Note

Authorize endpoint is deprecated. Use Token endpoint POST request to get ID token.]

The URL for authorize endpoint is: <portal_url>/_services/auth/authorize. The authorize endpoint supports the following parameters:

Parameter Required? Description
client_id Yes A string that is passed when making a call to the authorize endpoint. You must ensure that the client ID is registered with the portal. Otherwise, an error is displayed. Client ID is added in claims in the token as aud and appid parameter and can be used by clients to validate that the token returned is for their app.
The maximum length is 36 characters. Only alphanumeric characters and hyphens are supported.
redirect_uri Yes URL of the portal where authentication responses can be sent and received. It must be registered for the particular client_id used in the call and should be exactly the same value as registered.
state No A value included in the request that also is returned in the token response. It can be a string of any content that you want to use. Usually, a randomly generated, unique value is used to prevent cross-site-request forgery attacks.
The maximum length is 20 characters.
nonce No A string value sent by the client that is included in the resulting ID token as a claim. The client can then verify this value to mitigate token replay attacks. The maximum length is 20 characters.
response_type No This parameter supports only token as a value, which allows your app to immediately receive an access token from the authorize endpoint without making a second request to the authorize endpoint.

Successful response

The authorize endpoint returns the following values in the response URL as a fragment:

  • token: Token is returned as a JSON Web Token (JWT) digitally signed by the portal’s private key.
  • state: If a state parameter is included in the request, the same value should appear in the response. The app should verify that the state values in the request and response are identical.
  • expires_in: The length of time that the access token is valid (in seconds).

For example, a successful response looks as follows:

GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier

Error response

The error in authorize endpoint is returned as a JSON document with the following values:

  • Error ID: Unique identifier of the error.
  • Error message: A specific error message that can help you identify the root cause of an authentication error.
  • Correlation ID: A GUID that is used for debugging purposes. If you have enabled diagnostic logging, correlation ID would be present in server error logs.
  • Timestamp: Date and time when the error is generated.

The error message is displayed in the default language of the signed-in user. If the user isn't signed in, the sign-in page is displayed for the user to sign in. For example, an error response looks as follows:

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }

Validate ID token

Just getting an ID token isn't sufficient to authenticate the user; you must also validate the token's signature and verify the claims in the token based on your app's requirements. The public token endpoint provides the public key of the portal, which can be used to validate the signature of the token provided by the portal. The URL for public token endpoint is: <portal_url>/_services/auth/publickey.

Turn implicit grant flow on or off

By default, implicit grant flow is enabled. If you want to turn off implicit grant flow, set the value of the Connector/ImplicitGrantFlowEnabled site setting to False.

If this site setting isn't available in your portal, you must create a new site setting with the appropriate value.

Configure token validity

By default, the token is valid for 15 minutes. If you want to change the validity of token, set the value of the ImplicitGrantFlow/TokenExpirationTime site setting to the required value. The value must be specified in seconds. The maximum value can be 1 hour, and the minimum value must be 1 minute. If an incorrect value is specified (for example, alphanumeric characters), the default value of 15 minutes is used. If you specify a value more than the maximum value or less than the minimum value, the maximum and minimum values are used respectively, by default.

For example, to set the token validity to 30 minutes, set the value of the ImplicitGrantFlow/TokenExpirationTime site setting to 1800. To set the token validity to 1 hour, set the value of the ImplicitGrantFlow/TokenExpirationTime site setting to 3600.

Register client ID for implicit grant flow

You must register the client ID with the portal for which this flow is allowed. To register a client ID, you must create the following site settings:

Site setting Value
ImplicitGrantFlow/RegisteredClientId The valid client ID values that are allowed for this portal. The values must be separated by a semicolon and can contain alphanumeric characters and hyphens. The maximum length is 36 characters.
ImplicitGrantFlow/{ClientId}/RedirectUri The valid redirect URIs that are allowed for a specific client ID. The values must be separated by a semicolon. The URL provided must be of a valid web page of the portal.

Sample code

You can use the following sample code to get started with using OAuth 2.0 Implicit Grant with Power Apps portals APIs.

Use Portal OAuth token with an external Web API

This sample is an ASP.NET based project and is used to validate the ID token issued by Power Apps portals. The complete sample can be found here: Use Portal OAuth token with an external Web API.

Token Endpoint sample

This sample shows how you can use the getAuthenticationToken function to fetch an ID token using the Token endpoint in Power Apps portals. The sample can be found here: Token Endpoint sample.