ACR and AMR claims - What They Are
Authentication Context Class Reference (ACR) and Authentication Methods Reference (AMR) are optional or - in some cases, for example some Open Banking specifications - mandatory claims in the JSON Web Token (JWT) standard that convey information about the authentication methods and strength of the authentication used to obtain the token.
The ACR claim provides information about the strength of the authentication mechanism
or process. The value of the ACR claim is a URI that identifies the authentication context class reference.
The possible values for the claim can differ between services and standards. Supported ACR values are presented
by Authorization Server as an array of strings (
acr_values_supported) during the OIDC IDP discovery process.
ACR claim is defined in the Section 2 of OpenID Connect Core specification
OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. (…) Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The acr value is a case sensitive string.
Each ecosystem requires different ACR claims. Usually this information is part of a security profile.
For example security profile of OB Brazil defines the
in the Authorization server
section of Open Finance Brasil Financial-grade API Security Profile,
while in the section Requesting the “urn:brasil:openbanking:loa2” or “urn:brasil:openbanking:loa3” Authentication Context Request
it specifies what authentication factors are required for each of these ACRs.
In contrast, the AMR claim communicates the specific authentication methods or processes used during the authentication event. Section 2 of OpenID Connect Core specification describes AMR claim as:
OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. (…) Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The amr value is an array of case sensitive strings.
The value of the AMR claim is an array of strings, where each string represents a specific authentication method used during the authentication event. The possible values for the AMR claim are defined in the RFC8176 specification on Authentication Method Reference Values.
Cloudentity offers advanced settings for Identity Providers, so it is possible to map custom IDP attributes to ACR and AMR claims and overwrite AMR obtained from authentication method, as seen on the image below:
Example Usage of ACR and AMR Claims
OpenID Connect specification describe usage of ACR and AMR claims primarily in the context of Authentication. In short, the authentication server provides support for specific ACR values. During the request, the application passes the requested values to the server, allowing it to determine the required authentication factors. Then, the ACR and AMR values are returned in the ID token. Ultimately, the application can utilize this information for authorization and access control.
That being so, the use of AMR and ACR claims can help ensure that the appropriate authentication methods are used and that the strength of authentication meets the required level to access certain resources. However, just propagating both ACR and AMR claims is not enough - it is advisable to also implement proper access control mechanisms that check the values of both claims and enforce it. For instance, it could be an authorization policy that checks if the ACR or AMR claim is set to a desired value and based on that allow or deny access to a certain API.
In the context of Open Banking, banks can offer multiple authentication methods (passwords, biometrics, security tokens) and different levels of authentication strength when accessing different financial information.
For example, to access resources using read-only APIs (such as a bank accounts listing API), a bank
might require a certain authentication method, like a password. In this case, the AMR claim can indicate
this by containing a
pwd value. However, read-write APIs (such as those for viewing or updating
certain bank account details) might require a more secure method, like OTP (one-time password).
In this case, the AMR claim should contain an
Moreover, a bank may require a higher level of authentication strength, such as multi-factor authentication, to protect certain APIs or other resources. This requirement can be indicated by the ACR claim, which informs Identity Provider what authentication level is essential for a user in the given context.
Different Open Banking standards define different possible values for this claim, therefore the Authorization Server needs to provide option to configure it with ease. For instance, Open Finance Brasil supports ACR URIs according to following Levels of Assurance:
- LoA2: Authentication performed using a single factor -
- LoA3: Authentication performed using multi-factor authentication (MFA) -
Therefore, if the bank requires multi-factor authentication, the ACR claim’s value
All of these measures are taken, so the client application (for example a budgeting app) can consume APIs exposed by the resource server responsible for handling authenticated requests. The server permits access to APIs solely upon successful user authentication with use of certain authentication methods (like the ones mentioned above), leading to the obtaining of an access token.
Energy companies deal with access management to various confidential data and critical tasks that require a high level of security. In this context, ACR and AMR claims can be used to ensure that only authorized individuals (like personnel of an energy company, its clients or other involved parties) can access resources in question.
Furthermore, energy companies are subject to various regulations, such as the North American Electric Reliability Corporation (NERC) Critical Infrastructure Protection (CIP) standards or the Consumer Data Right (CDR) for Energy developed by the Australian government. These standards require energy companies to implement specific authentication methods to ensure the security of their systems. The ACR and AMR claims can be used to ensure compliance with these regulations by specifying the required authentication methods and levels of assurance.
Cloudentity’s offers OAuth, Consent, and API Security compliant with Australian Customer Data Right (CDR) standard. In context of ACR, it means that for CDR workspaces, supported ACR URIs are defined according to Levels of Assurance described in official regulations (LoA2 and LoA3, as described in an Open Banking section above).
"acr_values_supported": [ "urn:cds.au:cdr:2", "urn:cds.au:cdr:3" ],
When it comes to the AMR claim, it can specify the acceptable authentication methods based on the level of risk associated with the data being accessed. For example, if the data being accessed is not highly sensitive, the consumer can be required to use password-based authentication (a password that meets specific complexity requirements) to access the resources:
"amr": [ "pwd" ],
ACR and AMR claims can be used to protect any API containing sensitive patient information or providing access to healthcare services. By using these claims in JWT, healthcare organizations can ensure that only authorized individuals can access these APIs, thus protecting patient privacy and confidentiality.
For example, let’s say that to issue a prescription using a certain prescription API, a medical professional
must be verified by scanning a physical card with a smart card reader located by their workstation. In this scenario,
to access the API, the issued JWT token should contain an AMR claim containing a
smartcard value and/or
an ACR claim containing a standardized value indicating authentication by a smartcard (eg. standardized according to SAML 2.0.
urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard), which is more secure than username and password.
This approach can ensure that only authorized healthcare providers can prescribe medications using the workstation.
Furthermore, accessing certain APIs intended for patients (for example API used to view blood test results on an online
platform) can also be protected by requiring appropriate authentication methods
and/or their strength. For instance, it might require a two-factor authentication using for example a username with password
and an OTP aquired from a mobile device with the same phone number as the one figuring in
patient’s data stored by their clinic or hospital. In order to ensure that, JWT Token used to access
this API should contain an ACR claim with a proper URI, eg.
(standardized according to SAML 2.0.).
AMR and ACR claims are essential in ensuring secure access to sensitive data and actions. The versatility of these claims makes them useful in a variety of industries and use cases beyond those mentioned in the article. For example, e-commerce companies can use AMR and ACR claims to ensure secure online transactions, while government agencies can use them in their authorization policies to make decisions on providing access to resources. Overall, AMR and ACR claims are a crucial component of authentication protocols, and their widespread applicability makes them an essential tool for ensuring secure access across various industries and use cases.
Cloudentity provides pre-defined workspaces tailored to meet the specific requirements of various open standards. Our solution includes preconfigured support for ACRs in different ecosystems, relieving you of the burden of ensuring compliance while developing solutions that enable Open Banking, Open Finance, or Open Insurance.
If you want to set your own ACRs in the underlying workspace’s Authorization Server, you can easily do so through the workspace settings.
Cloudentity provides workspace profiles with authorization servers that comply out-of-the-box with many different Open Finance initiatives. Need FAPI 2.0? FAPI Advanced? No problem.
Do not worry about keeping your internal authentication/authorization/consent solutions compliant with the specs - it’s much better to use our solution and spend your time and resources working on the core of your business!