Setting up API Policies

How to set up authentication and logging policy for your API.

To have external access to your API, and to define the authentication methods for controlling who can use it, API Policies are required.

In addition, API Policies are used to set up API Monitoring and logging for your API.

Step by Step Tutorial Available

If you prefer more visual or interactive guidance on how to add an API Policy to your API in Frends, you can find a step-by-step walkthrough from your own environment's home page, under Onboarding by selecting "Tutorial 5, Step 3: API authentication with Policies" tutorial.

API Policy creation

In an API policy, you define the name for the policy and what API endpoints and HTTP methods it is targeting.

It can either target few specific endpoints and methods, or include an implicit wildcard to match whole API and not specific endpoints or methods for them.

Each policy can also target multiple APIs, and also endpoints not included in any API, if there are other resources under Frends environment's url you would like the policy to consider. This can be useful for setting up general logging policy to log all connections coming to your Frends Agent.

Throttling can also be set for each endpoint separately, as well as for the authentication methods, depending on your requirements.

API Policy for setting up API key authentication.

API Authentication

To set up authentication into the policy, you can create a New identity to the policy. Options here are OAuth, private application and API key.

• OAuth here refers to external OAuth application authentication, which can be connected to Frends through Administration > OAuth applications menu.

• Private application refers to OAuth authentication where the issuer is not defined, or is the Frends tenant itself. These can be configured under Administration > Private applications menu.

• API key can be configured under Administration > API keys menu, which are then enabled to be used in the specified API endpoints here.

Setting up Microsoft Entra ID as OAuth provider for your API.

Instead of specified authentication method, you can also enable public access, which would enable anyone to access the specified endpoints without authentication. Enabling public access will replace all other authentication methods.

If Public Access toggle is enabled, you only specify which Agent Groups the Policy targets.

Regardless of the authentication method chosen, a target Agent Group has to be defined. It can be one or more Agent Groups, and it specifies which Agent Groups the current Policy and authentication rules apply to. For API key authentication, the target Agent Group is defined with the API key and not in this view.

If Public Access is enabled, you will need to create another Policy if you would like to have authentication enabled for other Agent Groups than what is defined for Public Access.

For other authentication methods, you can specify multiple for the single Policy to allow different authentication methods for your API at the same time. Different authentication methods can also target different Agent Groups.

Logging Configuration

Finally, you can add a logging configuration to the API policy, to define whether or not API events should be logged for the targeted endpoints in specified Agent Groups, and what details are logged.

These can be useful to set up separately for development, testing and production uses, both to enable better debugging capabilities but also to then reduce logged data amounts from production use as well as for privacy and security reasons.

API logging configuration options.

Combining Policies

Combining the freely defined targeted endpoints, public access identity rule and logging options, the policies makes it possible to define purely logging-specific policies in addition to authentication policies. If multiple policies target the same endpoints, it is possible to separate authentication, logging and throttling options into multiple policies, as well as creating global policies that set up the default values for your Environments.

In the event that multiple policies overlap for same Agent Groups, the tighter definition will take priority. As an example, there could be two API Policies targeting two API URLs, with different API keys:

• ALL /api with API Key 1

• GET /api/test with API Key 2

In this setup, you will need to use API Key 2 to get access to endpoints under /api/test with GET method, and API Key 1 will not work for them.

API Key 1 would work for any other endpoint under /api URL, and also for any other method than GET, such as POST, for the endpoints under /api/test URL.

The priority for API Policies is in the following order:

1. More exact URL match

   • /api/test/v1/customers takes priority over /api/test, regardless of defined method

2. Method match

   • Defined method, such as GET or POST, take priority over ALL method, if the url definition is the same

Multiple Authentication Methods

Frends API Policies support adding multiple authentication methods — such as OAuth, Private Application, and API Key — within a single policy, allowing different callers to authenticate using the method best suited to them without requiring separate policies for each. When a request arrives, Frends evaluates the credentials in a fixed order, but only for the methods that have been configured in the policy:

1. OAuth token

2. API Key

3. Public Access

If a request includes a parseable OAuth token and OAuth is configured in the policy, that method is attempted and the result is final. An unparseable token is simply ignored and evaluation proceeds to the next configured method, or request is rejected with 401 Unauthorized error if there are no other methods configured.

For example, if both OAuth and API Key are configured on the same policy:

• A request carrying a valid OAuth token is authenticated via OAuth — the API Key check is skipped entirely.

• A request carrying a valid OAuth token with insufficient claims is rejected — even if a valid API Key is also present in the request.

• An unparseable or malformed OAuth token is ignored and evaluation proceeds to API Key.

• A request with no OAuth token but a valid API Key is authenticated via API Key.

If OAuth were not configured in the policy at all, but a valid OAuth token is still provided in the request, it may cause that the request is rejected with 403 Forbidden status code, even if a valid API Key is provided in the same request.

As a final step in the authentication chain, if public access is enabled for the API operation and no other authentication methods were provided, the request will be allowed to go through.

While the possible authentication methods are evaluated as a chain from Frends side, it does not enable the requestor to simply provide every authentication method at once and hope something passes. The system instead provides specifically alternative methods for requests to use.

This approach is particularly useful when an API serves different types of consumers simultaneously, such as internal services authenticating via OAuth and external partners or legacy systems using API Keys, all under the same policy and endpoints.

Note that if the Public Access toggle is enabled on a policy, it replaces all configured authentication methods for the targeted Agent Groups, so a separate policy should be used if authenticated access is still required for other groups.