# 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](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 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

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

### 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**.

Access tokens are required to be set up within 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. {% hint style="info" %} 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. {% endhint %}

Setting the URI and ID Token generation.

### 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**.

App roles give more granular permission structure for your API.

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.

An example of a role for standard users of 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.

Add users to the defined roles through here.

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

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//`. Replace `` 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**, if it was defined during the App Registration in Azure. Application ID URI is the same application ID, with **api://** appended at the beginning, such as api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14 {% hint style="warning" %} **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. {% endhint %}

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

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](/frends-development/api-management/api-policies.md) 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.

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**. ## 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**.

Implicit OAuth flow requires some settings in the OpenAPI specification.

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//oauth2/authorize?resource=` Replace `` and `` 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.

Example API specification using OAuth 2.0 security scheme.

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.

Authenticating to the API requires the client id from Azure.

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](https://msdn.microsoft.com/en-us/library/system.security.claims.claimsprincipal\(v=vs.110\).aspx). 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.frends.com/guides/api-management/setting-up-implicit-oauth-flow-for-frends-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.