Setting up Implicit OAuth flow for Frends APIs

In order to use OAuth implicit flow authentication for your APIs created in Frends, you can follow this guide on how to set it up.

Requirements

In order to set up an implicit OAuth 2.0 flow, you will need access to Azure Portal to manage your Entra ID, in order to set up an app registration there, as well as create or assign roles to users allowed to connect to your API.

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

Give the app a unique name, and choose suitable supported account type. By default the top option gives access to company's users in single tenant configuration.

Application and Tenant ID

Find your newly created application and go to its Overview page, if you didn't land on it by default. Copy the values of these fields and save them for use.

• Application (client) ID

• Directory (tenant) ID

Redirect URI and ID Tokens

To use the authentication you need to set the response from the application to contain an ID token. When viewing the created App registration, you can access the authentication options by navigating to Manage > Authentication and selecting Add a platform.

When setting up the platform, choose the platform type as Web, and click next.

Configuring the platform includes setting up the Redirect URI as well as selecting ID Tokens to be issued.

In this guide, we will use the Swagger UI hosted in the Frends Agent as our test client, so you need to give the reply URL it uses here, i.e. the agent's external address, including http/https and a possible port number, with the path /api/auth/oauth2-redirect.html added to the end. For example, if your Agent's external address is myagent.frendsapp.com, the redirect URI would be https://myagent.frendsapp.com/api/auth/oauth2-redirect.html. Click Register when all necessary fields are configured. An example is seen in the image below.

Create Application Roles

Using roles you can manage which users have access to which Frends APIs. You can add roles by navigating to Manage > App roles.

In this example we will create two roles: tester and user. Users will only have access to production APIs while Testers will also have access to test APIs. We can start creating a new role by clicking + Create app role.

While exact details might differ for each application, below you can see an example for basic user role that can be given access to your API.

Assign Users to Roles

Finally, you will need to assign users to the roles you just created. To do this, navigate to the app Overview page and click the link next to the Managed application in a local directory field.

This will take you to the Enterprise Application Overview page from which you can add users to roles by navigating to Users and groups in the Manage sidebar.

Users can be added to groups by clicking + Add user/group. In the following window you must select the user and then the role you wish to assign to that user. You can assign multiple roles to the same user by adding the user multiple times and giving it a different role. In this example a user has been assigned both the FrendsAPIUser and FrendsAPITester roles created earlier.

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.

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

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.

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.

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 Name value. Select it to connect it to your API Policy.

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.

After configuration, click Save Changes.

Configuring the API Specification UI to authenticate using Azure AD

To test API calls using the API Specification UI it requires OpenAPI Specification settings. Navigate to the API Management view in your Frends UI. Select your API specification and click Edit.

In the Editor page that appears find the authorizationUrl field in your API specification in the securitySchemes section. Set the value of the authorizationUrl field to

https://login.microsoftonline.com/<tenant_id>/oauth2/authorize?resource=<application_id>

Replace <tenant_id> and <application_id> with the values from your Azure AD application Overview page. Now you can authorize the API by providing the client_id which again can be found from your Azure AD application Overview page.

Save your changes, and update and optionally deploy the API and linked Processes for the changes to take effect. Process Triggers need to be enabled in order to have API Specification UI available.

Testing the authentication

In the API Specification UI, you should now see an Authorize button above your API endpoints.

Click on it, and you should get to the authorization flow, where you need to give your username and password. Eventually, you should be returned to the API Specification UI.

Once ready, you can Try out an operation, giving the necessary parameters and clicking Execute.

If you receive 200 or other 2xx status code, you're all set. Status code 401 usually means that the OAuth application details in Frends are set incorrectly, and those should be checked first. Finally, common error status code 403 usually means the API Policy is set up incorrectly as the authentication succeeded, but it was deemed that you are not allowed to connect to the API.

Accessing the Token within Process

The Frends Agent will validate the received token and read the claims from it. The claims data will then be available in the Process via #trigger.claimsprincipal reference value, which is object of type System.Security.Claims.ClaimsPrincipal.

Alternatively, if the trigger reference value is not available, you can try to use System.Threading.Thread.CurrentPrincipal built-in object, which you will only need to cast to System.Security.Claims.ClaimsPrincipal to use.

After this, you can access the claims using the methods in Claims Principal.

For example, you can check if the token has a claim "name" using the command:

#trigger.claimsprincipal.FindFirst("name") != null

Or by using the CurrentPrincipal object:

((System.Security.Claims.ClaimsPrincipal)System.Threading.Thread.CurrentPrincipal).FindFirst("name") != null