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 Azure Active Directory > App registrations, and click New registration.

Give the app a unique name and set the sign-on URL to the URL used by your app. Also set the Supported account types. 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.

Enable Access Tokens for Implicit Flow

To use implicit flow you need to set the response from the application to contain an access token. This can be done by navigating to Manage > Authentication and enabling the Access tokens (used for implicit flows) option. Remember to click Save.

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.

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.

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.