Prerequisites
You will need access to Azure Portal and Entra ID to register applications. You will also need access to a Frends Tenant.
1 - Set Up an Application in Azure AD
Create New App Registration
To start, go to https://portal.azure.com using an account that can register new applications in the directory, and go to Azure Active Directory > App registrations, and click New registration.
Give a descriptive name for the application registration and select the Multitenant option from the Supported account types list as shown in the image below. You also need to add a redirect URI however this will be done in the following steps. Click Register once you have configured the required settings.
Enable Access Tokens and Set Redirect URI
With Authorization Code flow you need to set the response from the application to contain an access token as well as adding a Redirect URI. This can be done by navigating to Manage > Authentication and clicking "+ Add a platform".
In the Configure Web window that appears you can set the Redirect URI and in the Implicit grant and hybrid flows section enable the ID tokens (used for implicit and hybrid flows) option. If your Agent's external address is myagent.frendsapp.com, the redirect URI would be https://myagent.frendsapp.com/api/auth/oauth2-redirect.html
Once all the settings are configure click Configure to save.
Create New Client Secret
Next find the Certificates & secrets page in the Manage dropdown. Navigate to Client secrets and click "+ New client secret".
In the opened view enter a descriptive name for the client secret and define the expiration time, then click Add. After the client secret has been added, find it in the list below and copy and save the Value for later use. This value can only be saved directly after creation, so remember to save it immediately. If you lose the value, you will have to create a new client secret.
Collect the Following Items:
Client ID and Tenant ID
Client ID and Tenant ID
Navigate to the Overview page in your application and take note of the Application
(client) ID and the Directory (tenant) ID
OAuth 2.0 Authorization and Token Endpoint URLs
OAuth 2.0 Authorization and Token Endpoint URLs
Navigate to the Endpoints page in the Overview menu.
Copy both the OAuth 2.0 authorization endpoint (v2) and the OAuth 2.0 token endpoint (v2).
Change "organizations" in the endpoint URL to the Directory (tenant) ID.
Application ID URI
Application ID URI
Navigate to the Expose an API page from the Manage dropdown. Copy the Application ID URI value and save it. If there is not an Application ID URI value there, simply click Add and there should be a suggested value that you can use.
2 - Generate Access Token with Postman
To generate an Access Token use Postman as it has a built in OAuth 2.0 Authorization method that is extremely convenient.
Create a new Request page and navigate to the Authorization tab. Then configure the settings as seen in the image and further instructions below.
In Token Name provide a descriptive name for your Access Token request
In Grant type select the Authorization Code option from the dropdown menu
In Callback URL add the Redirect URI that you configured earlier
In Auth URL add the OAuth 2.0 authorization endpoint (v2) that you saved earlier
In Access Token URL add the OAuth 2.0 token endpoint (v2) that you saved earlier
In Client ID add the Application (client) ID that you saved earlier
In Client Secret add the Client Secret value you created (and hopefully) saved earlier. If you did not save it you have to create a new one
In Scope add the Application (client) ID and add /.default to the end of it
In State add 123456. As stated by Postman this is "an opaque value that is used for preventing cross-site request forgery."
In Client Authentication select the Send client credentials in body option from the dropdown menu
Once all the settings are configured click Get New Access Token and you should be prompted with a login page. Login and in Postman you should be given your Access Token.
3 - Decode Access Token
Now as you have an access_token, let’s decode it and check the token’s decoded value.
One of the easiest ways to do this is to go to jwt.io and use the Debugger function.
Paste the access_token value to the Encoded field. Verify that you are able to see the Decoded PAYLOAD: DATA field
Copy and save the iss value which is found in the PAYLOAD:DATA field. This is needed when configuring Frends to use Entra ID as an OAuth 2.0 authorization provider for an API published with Frends.
4 - Configure Frends API to use Entra ID and the Created App Registration as an Authorization Provider
Configuring OAuth 2.0 Authorization Code Flow in the Frends API’s OpenAPI Specification
Here is a simple example API demonstrating the use of Entra ID as an OAuth 2.0 authorization provider with Authorization Code flow. You can modify this to your needs.
openapi: 3.0.1
info:
title: OAuth 2.0 Authorization Code Flow Demo
description: Simple example API demonstrating the use of Entra ID as an OAuth 2.0 authorization provider with Authorization Code OAuth 2.0 flow.
version: 0.0.1
servers:
- url: /api/MachineToMachine/v1
paths:
/time:
get:
summary: Returns current time and date.
responses:
'200':
description: Current time and date
content:
application/text:
schema:
type: string
components:
securitySchemes:
AzureAD:
type: oauth2
description: This API uses OAuth 2.0 flows.
flows:
authorizationCode:
authorizationUrl: https://login.microsoftonline.com/common/oauth2/ authorize?resource=REPLACE WITH CLIENT ID
tokenUrl: https://login.microsoftonline.com/REPLACE WITH APPLICATION ID/
scopes: { }
security:
- AzureAD: [ ]
To enable the use of OAuth 2.0 with the API, the essential parts are securitySchemes and security at the end of the OpenAPI specification.
In the authorizationUrl field you need to replace the text REPLACE WITH CLIENT ID with the actual Client ID. For this example App registration, the authorizationUrl field value should look like this:
https://login.microsoftonline.com/common/oauth2/authorize?resource=649c7107-f69f-4a4f-b691-71ef91f573d7
In the tokenUrl field you need to replace the text REPLACE WITH APPLICATION ID with the actual Application ID. For this example App registration, the tokenUrl field value should look like this:
https://login.microsoftonline.com/9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/
Save the OpenAPI specification before continuing to the next step.
Configure the OAuth 2.0 Application in Frends
NOTE: Instructions from this point onward are intended for Frends 5.7 or older.
NOTE: For this step you need to have administrator rights for your Frends Tenant or request a Frends administrator to do the configuration for you.
In the Frends UI, navigate to Administration > OAuth applications and click “+ Create new”.
In the New OAuth application page fill the following fields:
Name - Give a descriptive name for the OAuth application. Usually the name refers to the API where the OAuth 2.0 Authorization Code Flow authentication and authorization will be used.
Issuer - Paste the iss value that you saved earlier
Audience - Paste the Application ID URI value that you saved earlier
When ready, click Save changes
Configure the OAuth 2.0 API Access Policy in Frends
In the Frends UI navigate to Administration > API Access Policies.
In the Create new access policy page fill the following fields:
Name - Give a descriptive name that refers to the API and API clients to whom this policy defines API access
Description - This is not mandatory but it is good practice to describe in more details the use cases for the API
Allowed access token issuer - From the dropdown menu select the issuer that you configured earlier
Configure the Frends API to Use a Certain API Access Policy or Policies
Open the Frends API Management view, navigate to your Frends API and from the API Access Policies dropdown list select the API Access policy you configured in the previous step. Below is an example of a Frends API with the example API Access policy made in the previous step selected.
