Prerequisites
You will need access to Azure Portal and Entra ID to register applications. You will also need access to a Frends Tenant.
1 - Entra ID Application Registration
1.1 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 save it. Find your newly created application and go to its Overview page.
Copy the values of these fields and save them for future use:
Application (client) ID
Directory (tenant) ID
1.2 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.
1.3 Create App Roles (If Needed)
In client credential flow the application acts on its own with no user signed in. In the scenario where there is no signed-in user present, App-only access uses app roles instead of delegated scopes. App roles are also referred to as application-only permissions or application permissions.
However, in simple use cases, the App roles may not be needed if you want to authorize a certain API client with a certain Application ID to use the API.
In the following example we configure two App roles: Reader and Writer. There could be multiple APIs where the access rights depend on the what roles are granted for certain App registration.
Navigate to the App roles menu in the Manage dropdown and click “+ Create app role”. Fill the app role fields.
Expand for an example:
Expand for an example:
1.4 Configure API Permissions (If Needed)
If App roles are used you also need to configure API permissions in order to utilize the App roles.
Navigate to the API permissions menu in the Manage dropdown and click “+ Add a permission”.
In the opened Request API permissions page find your App registration. It can be found under APIs my organization uses or My APIs. Select it and you should then find the App roles that you created earlier. Choose and save those roles by clicking "Add permissions".
You should now see the permissions added in the main API permissions view.
1.5 Copy and Save the OAuth 2.0 Token Endpoint (v2) URL
The OAuth 2.0 token endpoint will be used in later steps, for example a test of fetching the OAuth 2.0 access token using the client ID and client secret.
Navigate to the Endpoints page in the Overview menu.
Copy the OAuth 2.0 token endpoint (v2) URL and save it.
1.6 Copy and Save the 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 - Test of Fetching OAuth 2.0 Access Token with Postman
2.1 Make Access Token Request with Postman
It’s good to test that fetching the access token works as expected with the new Entra ID App registration.
For testing you can use Postman or any other tool capable of making HTTP requests with the x-www-form-urlencoded formatted payload.
Enter your values, an example is shown in the following screenshot. The values are explained below the screenshot.
Change the method type to POST and paste the OAuth 2.0 token endpoint URI saved in step 1.5. Select Body > x-www-form-urlencoded parameters. Then add new Key rows for each of the following points:
For grant_type enter the value client_credentials
For client_id enter the Application (client) ID created in step 1.1
For client_secret enter the client secret value created in step 1.2
For scope enter the Application ID URI saved in step 1.6 AND add /.default to the end of the Application ID URI. In this example the resulting scope value is api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/.default
After setting these values, you are ready to test the access token request. With Postman the request is sent by clicking Send.
If done correctly, you should get a response with status 200 OK and a JSON payload containing the access_token field. Copy the access_token field's value for the next step.
If you want to use the curl tool to test fetching the access_token, the curl request looks like this:
If you want to use the curl tool to test fetching the access_token, the curl request looks like this:
1 curl --location 'https://login.microsoftonline.com/97759401-0ff9-42fb-8eae-9163e29d19bf/oauth2/v2.0/token' \
2 --header 'Content-Type: application/x-www-form-urlencoded' \
3 --data-urlencode 'grant_type=client_credentials' \
4 --data-urlencode 'client_id=9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14' \
5 --data-urlencode 'client_secret=GA_8Q~0YepR2Zmg_hKcMxyngv0Bsfhzf4m9MZakX' \
6 --data-urlencode 'scope=api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/.default'
Change the values to match the ones you saved in part 1 of this guide.
2.2 Decode the access_token Value and Review the Content
Now as you have an access_token, let’s encode 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 containing the following values:
aud - This should have the same value as the Application ID URI saved in step 1.6
roles - If you defined App roles, you should see a list of all the roles you defined in steps 1.3 and 1.4.
Your access_token value (continues outside of screenshot)
aud value
roles list
For the next step, copy and save the iss value which is found directly below the aud value. This is needed when configuring Frends to use Entra ID as an OAuth 2.0 authorization provider for an API published with Frends.
3 - Configure Frends API to use Entra ID and the Created App Registration as an Authorization Provider
3.1 Configuring OAuth 2.0 Client Credentials 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 Client Credentials OAuth 2.0 flow. You can modify this to your needs.
openapi: 3.0.1
info:
title: OAuth 2.0 Client Credentials Demo
description: Simple example API demonstrating the use of Entra ID as an OAuth 2.0 authorization provider with Client Credentials 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 with the client credentials grant flow.
flows:
clientCredentials:
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 (rows 20-30) at the end of the OpenAPI specification.
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.
3.2 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 client credentials authentication and authorization will be used.
Issuer - Paste the iss value that you saved in step 2.2
Audience - Paste the Application ID URI value that you saved in step 1.6
When ready, click Save changes
3.3 Configure the OAuth 2.0 API Access Policy in Frends
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 > 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 in step 3.2
Next configure the rules sections. It is possible to add fine grained rules for allowing and denying API clients based on the so called claims received in the access_token’s payload (see step 2.2 for instructions for the access_token decoding and an example of the payload
content).
In this example we are providing API access to the API client only when the access_token’s payload’s roles contain a Reader value.
During this guide we configured the Entra ID App roles so that the roles will contain the following data:
1 "roles": [
2 "Reader",
3 "Writer"
4 ],
For allowing any API client with a valid access_token for our Entra ID OAuth 2.0 application and with roles containing at least a Reader value, we would define this kind of Allow rule:
You can also add an Allow rule for the Application ID URI. An example of the whole API Access policy can be seen below. Remember to save when configuration is complete.
3.4 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.
4 - Testing API Requests made to the Frends API with an OAuth 2.0 Access Token
First fetch a new access_token as described in step 2.1.
Here is example of how to use the access_token fetched from Entra ID with Postman for a Frends API endpoint:
With the curl tool, the very same request is done like this:
curl --location 'https://frendsapp-dev-agent.frendsapp.com/api/MachineToMachine/v1/time' \
--header 'Authorization: bearer eyJ0eXAiOiJKV1Qi...'
NOTE: For readability, the full access_token value is truncated in this curl example. Naturally, ensure you use the full access_token value.