You will need access to Azure Portal and Entra ID to register applications.

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.

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.

Note: A redirect URI is only needed for authentication in API Specification UI. If you want to use API Specification UI in multiple Agent Groups you need to create an application for each of those Agent Groups.

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.

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

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.

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.

Once the 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.

Once all the settings are configured, click Save changes.

To limit access to an API we need to define an API Access Policy. In this example we will create two different Access Policies. One Policy for production APIs and one Policy for test APIs. Access Policies are assigned as Agent Group specific, so having two different Access Policies allows us to limit access for specific users according to their assigned roles in the application.

Navigate to Administration > API Access Policies and click "+ Create new access policy". Give a descriptive name, a description (optional) and assign an access token issuer from the "Allowed access token issuer" dropdown menu. This can be the same issuer value you created in the previous step. 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 Access Policy for a production API, then the User role should have access. After configuration, click Save.

After the API Access Policies are created you need to assign them to the correct API in the API Management view.

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.

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.