How to use Private Applications for authenticating to Frends API

In order to use static authentication tokens in order to allow or deny access to your APIs in Frends, Private Applications can be set up and used as authentication method.

Requirements

In order to have access to Private Applications, at least Editor role, or similar Edit permissions are needed.

You should also have access to creating and editing API Policies, which is granted by the default Editor role in Frends, or byhaving ApiPolicy.Edit permission through a role.

What are Private Applications?

Private application is alternative to API keys and OAuth methods, where the authentication is performed by comparing the contents of a generated JWT token to rules specified in API Policies.

When using Private Application for authentication, all the tokens are generated by hand and distributed manually, much like the API keys are handled in Frends.

The authentication token has an expiration date like tokens from OAuth providers, as well as more details and possible values included in the token that can be used to authorize user for specific access. Unlike OAuth token, the expiration time for Private Application's token is generally longer due to its more static nature than with OAuth's more short term authentication tokens.

There is also no built-in, automated way of requesting and distributing the tokens for Private Applications, so the Private Application cannot be used to replace an authentication provider that issues tokens upon signing in.

For internal use, using Private Application is more secure and adjustable than API key or Basic Authentication methods due to the provided expiration date and more information that can be connected to the tokens themselves.

How to create a Private Application

Head over to Administration > Private Applications to create a new Private Application for your use case. You need to provide at least a name for the Private Application, but you can also add a description and tags for identifying the Private Application later.

Default token validity time is set to 2 years by default, but it can be adjusted to be shorter here or whenever a new token is created from this.

Custom token content field contains the token content applied to each token generated from this Private Application by default. Again, these can be adjusted while creating the token. Any fields, or claims, and values specified here can be used as an authentication rule in the API Policy.

By default, the sub claim, identifying the subject of the token, is set to be equal to the name of the Private Application, and the issuer and audience claims cannot be changed from matching the current Frends Tenant.

Once any necessary fields have been added to the default configuration, click on Save changes to save the Private Application.

Generating authentication tokens

With the Private Application created, new tokens can be created from it. Each token can be specified a separate name to identify who the token is for, and validity time and token specific content which can vary from the default values set in the Private Application.

Note that the default claims for the token cannot be removed or renamed, but aside from the iss and aud fields, their content can be changed to suit your needs.

Any additional fields can be added to the token to adjust what resources (APIs and endpoints) the token can or cannot access, if rules have been created for the additional fields in API Policies.

When the token is created, its content will be shown in order to share it with the intended user. The claims specified earlier are extended with issue date, expiration date and the identity of the token.

Using Private Application in API Policies

After you have created a Private Application, we need to head over to APIs > API Policies page to set it up for our APIs.

In order to learn more about creating API Policies, you can check out the guide for it.

With new or existing API Policy, make sure Public access is disabled, and then click on New identity to add the Private Application to your Policy. The name requested specifies the identity for this Policy and not the Private Application's name. You then also specify the targeted Agent Groups for this identity.

In the example, the authentication method will only be applied for the API in Development Agent Group.

With the identity added we need to still define the rules on what tokens are allowed to make requests to our APIs. More specifically, a rule (or multiple rules) can be created for each claim or field in the token's content, which will define whether the caller is allowed to connect to our API.

For example, the default claim sub can be used as primary rule to allow tokens that have been generated from the created Private Application, instead of all tokens generated by any Private Application. We can additionally deny access for tokens that contain claims limiting the access.

By default, the expiration time must not have passed in order to allow connections for a token. The issuer and audience claims must also match the current Frends Tenant in order to consider the defined rules, meaning all tokens generated from other Tenants or systems will not be considered valid here.

The rules don't need to use the Exact rule for checking the values. In addition to Exact, one can also use Contains or Regex options to make more variable rules than shown.

Remember to click on Save Changes in order to save the API Policy.