Skip to main content
For Authlete 2.x documentation, see 2.x version.

​
Overview

This document explains how to use the FAPI feature in Authlete. Authlete supports FAPI 1.0 and FAPI 2.0, and the way you tell Authlete which profile to apply is the same for both.

​
Where each profile is documented

​
Introduction

​
FAPI support in Authlete

Authlete supports both FAPI 1.0 and FAPI 2.0. Each of them defines several security profiles. The requirements an authorization server has to meet differ from profile to profile, so the server behaves differently depending on which one applies. To use the FAPI feature, configure your service and client to meet the requirements of the profile you want, then tell Authlete which profile to apply.

​
How to specify a profile

There are two ways. A static configuration applies the same profile to every request of that service or client. To host clients with different conformance levels on one authorization server, set FAPI Modes per client, or use scope attributes.
FAPI Modes is a service and client setting added in Authlete 3.0. Authlete 2.x has scope attributes only.

​
The order in which Authlete resolves the profile

Authlete decides the profile per request in the following order. The first condition that matches wins, and nothing below it is evaluated.
  1. If the FAPI feature is not enabled on the Authlete server, the request follows plain OAuth 2.0 / OpenID Connect.
  2. If FAPI Profile is not enabled on the service, the request follows plain OAuth 2.0 / OpenID Connect.
  3. If the service has FAPI Modes set, its value applies.
  4. If the client has FAPI Modes set, its value applies.
  5. Otherwise the attributes of the scopes carried by, or associated with, the request apply.
  6. If none of the above matches, the request follows plain OAuth 2.0 / OpenID Connect.
Setting FAPI Modes on the service makes every request to that service use that mode, and neither the client’s FAPI Modes nor any scope attribute is consulted. Leave the service-level mode unset if you need per-client conformance levels.

​
FAPI modes and their scope attributes

The fapi2 values baseline, advanced-jar and advanced-jarm are legacy and now deprecated. Use the values in the table above for new configurations.

​
When scope attributes point at more than one profile

Scope attributes are collected from every scope carried by, or associated with, the request, so one request can carry attributes belonging to different profiles. Authlete then resolves them in this order. The first group that matches wins, and nothing below it is evaluated. Only the members of the winning group apply together. FAPI 2.0 message signing can apply several requirements at once if several of its attributes are present. Ranks 2 to 4 are mutually exclusive — exactly one of them is chosen. For example, on a request where one scope carries fapi = rw and another carries fapi2 = sp, only the FAPI 2.0 Security Profile applies; the FAPI 1.0 Advanced attribute is ignored.
Groups cannot be combined. If a single scope attribute pointing at FAPI 2.0 message signing is present, fapi2 = sp and fapi = rw on the same request are not evaluated.

​
Where the FAPI settings live in the console

The service settings are on the Endpoints > Advanced > FAPI tab of the service. FAPI Profile enables the FAPI profiles for the service, and FAPI Modes selects the mode that applies to it. Choosing FAPI 2.0 Message Signing there makes FAPI 2.0 Message Signing Requirements available, where you pick which requirements apply. The FAPI tab of the service settings The FAPI tab of the service settings The client settings are on the Endpoints > Advanced > FAPI tab of the client, which carries FAPI 1.0 Modes and FAPI 2.0 Modes. The FAPI tab of the client settings The FAPI tab of the client settings Scope attributes are set on the Tokens and Claims > Advanced > Scope tab of the service.

​
Which FAPI modes can be combined

Only the FAPI 2.0 message signing modes can be selected together. Each of the following can only be selected on its own:
  • FAPI 1.0 Baseline
  • FAPI 1.0 Advanced
  • FAPI 2.0 Security Profile
So FAPI 2.0 Message Signing - Auth Request and FAPI 2.0 Message Signing - Auth Response can be selected together and both take effect, while FAPI 2.0 Security Profile and FAPI 2.0 Message Signing - Auth Request cannot. For the settings each FAPI 1.0 profile needs, see Configuring FAPI 1.0. For FAPI 2.0, see the pages listed under “Where each profile is documented” above.