How to use OAuth Client Credentials for Frends API

Setting up OAuth Client Credentials for your APIs in Frends.

In order to use OAuth token authentication for your APIs created in Frends, you can follow this guide on how to set up Client Credential flow with Azure and Entra ID.

Requirements

In order to set up the OAuth 2.0 client credential flow, you will need access to Azure Portal to manage your Entra ID, in order to set up an app registration there.

You will also need administrator rights to your Frends Tenant in order to create the OAuth Application.

Alternatively, you can provide this guide and the mentioned details to your Azure and/or Frends administrators to set up the flow.

Using the authentication in your API once set up do not require additional permissions.

Set Up an Application in Azure AD

First, you will need to set up the application in the Azure AD instance where the users you wish to authenticate are registered.

You will also need to decide how you wish to grant access to the users. If you want to give access to everyone from the given AD tenant, you only need to set up an app and give access to anyone with a valid access token from the Azure AD tenant. However, in many cases, you may wish to separate your API users by assigning different roles, for example "User" and "Administrator" with different access. The "User" role can only read data, not issue updates, while the "Administrator" role can do both. In this guide, we will set up the Azure AD app to use application roles that you assign to users, and can then verify in your access policies.

Create an Application

To start, go to https://portal.azure.com using an account that can register new applications in the directory, and go to Microsoft Entra ID > App registrations, and click New registration.

Creating a new app registration in Azure.

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

Take note of these values for adding the registration to Frends later.

Create New Client Secret

Next find the Certificates & secrets page in the Manage dropdown. Navigate to Client secrets and click + New client secret.

Client secret is used as "password" for the token request.

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.

Save the client secret for use later.

Optional: Create App Roles

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.

Example details for an App Role. Take note of the Value field, as you will need it later in Frends.

Optional: Configure API Permissions

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.

Roles can have different permissions to your APIs.

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.

Select the permissions and roles here.

You should now see the permissions added in the main API permissions view.

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.

You can find the endpoint urls dicrectly from here. They can also be built using app and tenant ids.

Copy the OAuth 2.0 token endpoint (v2) URL and save it.

Take note of the token endpoint especially for client credential flow.

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.

App ID URI is the same value as application ID from earlier, with the protocol added to it.

How to Test Fetching OAuth 2.0 Access Token

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.

Make Access Token Request with Postman

Enter your values, an example is shown in the following screenshot. The values are explained below the screenshot.

Example request in Postman.

Change the method type to POST and paste the OAuth 2.0 token endpoint URI. Select Body > x-www-form-urlencoded parameters. Then add new Key rows for each of the following points:

1. For grant_type enter the value client_credentials

2. For client_id enter the Application (client) ID

3. For client_secret enter the client secret value

4. For scope enter the Application ID URI 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 field's value for the next step.

Make Access Token Request with CURL

If you want to use the curl tool to test fetching the access_token, the curl request looks like this.

curl --location 'https://login.microsoftonline.com/97759401-0ff9-42fb-8eae-9163e29d19bf/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14' \
--data-urlencode 'client_secret=GA_8Q~0YepR2Zmg_hKcMxyngv0Bsfhzf4m9MZakX' \
--data-urlencode 'scope=api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/.default'

Change the values to match the ones you saved earlier in this guide.

Decode the Token Value and Review the Content

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 containing the following values:

• aud - This should have the same value as the Application ID URI

• roles - If you defined App roles, you should see a list of all the roles you defined

Jwt.io can be used to check and decode authentication tokens from Azure.

For the next step, you can 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.

Alternatively, the Issuer (iss) value can be built using the Tenant ID or Directory ID value from the App registration Overview page. Issuer value is in form https://sts.windows.net/<tenant_id>/ .

Issuer is an URI which is based on tenant id value.

Configure Frends to use the created App Registration

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.

Configure OAuth 2.0 Application Details in Frends

Once app has been registered and configured in the Azure AD, you need to give the details of that to Frends so it accepts the access tokens. To do this, go to the Frends UI and navigate to Administration > OAuth applications. Click on Create new.

OAuth Applications are found under Administration menu.

In the New OAuth application page you need to fill in the following details. An example can also be seen in the screenshot.

1. Name - Give a descriptive name

2. Issuer - Provide the issuer ID which is in the form https://sts.windows.net/<tenant_id>/. Replace <tenant_id> with the Directory (tenant) ID value which can be found in the Overview page of the application you created earlier in the guide.

3. Audience - Provide the application ID which is the Application (client) ID value which can be found in the Overview page of the application you created earlier in the guide.

   • Alternatively, this can be the Application ID URI, which is the same application ID, with api:// appended at the beginning, such as api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14

Issuer will also be used to select the OAuth Application in API Policy view.

Use your own Tenant and Application ID, obtained from Azure Portal for your Application registration, instead of the example values. The example value will not work for you.

Once all the settings are configured, click Save changes.

In addition, you can also configure the Advanced settings for your OAuth application.

• Name claim type - the claim from the token that contains the name of the user, if given. This value will be used for logging purposes, to show who called the API

• Role claim type - the claim from the token that contains the role name of the user, if available. If set, this value can be used in processes e.g. by calls to ClaimsPrincipal.IsInRole()

• Scope claim type - the claim from the token that contains the scopes from the token.

• Well known metadata location override - if the identity provider's OpenID .well-known/openid-configuration endpoint is not located in the default location. This parameter can be used to specify a custom location, which is needed for some providers, such as Azure AD B2C. By default FRENDS assumes the configuration can be found from the URL [Issuer]/.well-known/openid-configuration

• Signing Certificate Details Json - if the Agent cannot contact the identity provider directly to fetch the well known OpenID configuration, the public key can be provided here. The JSON structure can be found from the URL in the well known OpenID configuration endpoint's jwks_uri field.

Configure an API Policy in Frends

To limit access to an API we need to define an API Policy with OAuth identity. You can also edit an existing Policy to add OAuth as authentication method.

Navigate to APIs > API Policies and click + Create new. Give a descriptive name, a description (optional) and tags (also optional).

Select the APIs and/or endpoints you want to apply the new OAuth flow.

Creating new API Policy.

To add the OAuth flow to your API, click on New identity to add an identity to your Policy. Select the type to be OAuth, give the identity a descriptive name, and select the target Agent Group(s) to which the OAuth authentication flow should apply to. Click Add identity to add it to your Policy.

Creating a new identity to an API policy.

Once the identity is created, you need to connect it to the OAuth Application we created earlier. This is done by selecting the Issuer, which should list the OAuth Application we created earlier by its Issuer value. Select it to connect it to your API Policy.

Select the OAuth Application by Issuer value.

Next, add a rule by clicking "Add rule". In the Claim field add "roles" and in the Value field add the role that has access to this specific API. For example, if you are creating an API Policy for a production API, then the User role should have access.

For client credential flow, it's common to have roles Reader and Writer set up with the app registration. Those would also be used here to allow either one or both to access this API.

You can also add an Allow rule for the Application ID URI. An example of the whole API Policy can be seen below.

Add rules for the roles and/or applications you created.

After configuration, click Save Changes.

How to Test API Requests made to the Frends API with an OAuth 2.0 Access Token

First fetch a new access token, as described in earlier step.

Here is example of how to use the access_token fetched from Entra ID with Postman for a Frends API endpoint:

Testing your API with an access token in Postman.

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...'

For readability, the full access_token value is truncated in this curl example. Naturally, ensure you use the full access_token value.