Skip to content

ACR

ACR stands for Authentication Context Class Reference. It's a way to standardize the level of security of an access token depending on how the user authenticated.

Why this is useful?

In web applications, users usually logs in a first time with their email and password. When they come back, the application will use a cookie to remember their session so they don't have to authenticate again.

While convenient for the user, we cannot consider the cookie as safe as the email and password authentication: a malicious user could be behind the device, taking advantage of the existing session. In this context, sensitive operations like changing the password or initiating a money transfer should be avoided and we should ask again for the user's password.

That's exactly what ACR are for: properly define and prioritize the different ways a user can be authenticated, so we can allow or disallow sensitive operations.

How it's used in Fief?

Fief defines two levels of ACR:

  • Level 0: the user was authenticated through an existing session or a refresh token. They didn't authenticate with their email and password.
  • Level 1: the user authenticated using their email and password.

Other levels will be introduced in the future

We plan to support more robust ways of authenticating in Fief, like multi-factor authentication (MFA) or passkeys. As a result, we'll have even higher levels of ACR.

The ACR level is contained in the access token generated by Fief. Thus, the Fief API or your app can check for this parameter to allow or disallow an operation.

The Fief API requires an ACR of at least level 1 to:

  • Change the user's password
  • Change the user's email
  • Verify the user's email

Authenticate the user with a specific ACR level

After the user has successfully authenticated with their email and password a first time, Fief will maintain a session on its side so they don't have to enter their credentials again. As a result, while this session is valid, the access token you'll get will have and ACR Level 0.

If you require a higher ACR level, you can add the acr_values parameter to the Authorize URL. For example:

https://fief.mydomain.com/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Fcallback&scope=openid&acr_values=1

By doing this, even if there is a valid session on Fief's side, the server will force the user to authenticate again to match the desired ACR level.