| openid-connect-4-authentication-context- | March 2026 | |
| Vicente, et al. | Standards Track | [Page] |
This specification defines an extension to OpenID Connect that enables Relying Parties to obtain detailed information about the Authentication Methods used to authenticate the End-User. In addition, it allows Clients to request the use of specific Authentication Methods and to express requirements associated with those methods during the authentication process.¶
This document is not an OIDF International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard.¶
Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.¶
The OpenID Foundation (OIDF) promotes, protects and nurtures the OpenID community and technologies. As a non-profit international standardizing body, it is comprised by over 160 participating entities (workgroup participants). The work of preparing implementer drafts and final international standards is carried out through OIDF workgroups in accordance with the OpenID Process. Participants interested in a subject for which a workgroup has been established has the right to be represented in that workgroup. International organizations, governmental and non-governmental, in liaison with OIDF, also take part in the work. OIDF collaborates closely with other standardizing bodies in the related fields.¶
OpenID Connect (OIDC) enables Relying Parties (RPs) to obtain information about an Authentication Event performed by an OpenID Provider (OP) through a small set of standardized Claims. Among these, the Authentication Methods Reference (amr) Claim, identifies the Authentication Methods that were used to authenticate the End-User. While widely deployed, the amr Claim provides information at a coarse level of granularity and does not support the representation of method-specific properties, contextual information, or assurance-related characteristics. Consequently, RPs are unable to express or evaluate detailed Authentication Requirements in a interoperable manner.¶
This specification defines an extension to OpenID Connect that introduces a structured framework for representing Authentication Methods and their associated metadata. The extension further enables Clients to request the use of specific Authentication Methods and to express constraints on their characteristics using standardized protocol elements. These capabilities enable consistent interpretation of Authentication Events across heterogeneous identity systems and support the enforcement of security, assurance, and compliance requirements.¶
The extension defined in this document is designed to be fully compatible with existing OpenID Connect flows and does not modify underlying authentication mechanisms, token formats, or authorization interactions defined by OpenID Connect. Implementations that do not support this extension continue to operate as specified by OpenID Connect, ignoring the additional elements introduced herein. Implementations that support this extension gain a standardized, machine-interpretable mechanism for representing and requesting Authentication Method information.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.¶
In the .txt version of this specification, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. In the HTML version of this specification, values to be taken literally are indicated by the use of this fixed-width font.¶
All uses of JSON Web Signature (JWS) and JSON Web Encryption (JWE) data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.¶
This document defines technical mechanisms that enable a Relying Party to request the use of specific Authentication Methods together with associated requirements, and that enable an OpenID Provider to represent and convey Authentication Method information in a structured and interoperable manner. These mechanisms support the evaluation of Authentication Events based on Authentication Method characteristics, contextual information, and assurance-related properties.¶
This specification does not define non-technical aspects required for the deployment of a complete authentication assurance framework, including, but not limited to, legal considerations, liability models, trust frameworks, operational policies, or commercial agreements. Deployments are expected to complement the technical mechanisms defined in this document with appropriate policy, regulatory, and contractual definitions. Although such considerations are out of scope, this specification is designed to provide sufficient flexibility to support deployment in environments subject to diverse legal, regulatory, and commercial requirements across jurisdictions. References to such requirements may be included in this document for illustrative purposes only.¶
The terminology defined in OpenID Connect Core 1.0, OAuth 2.0, and JSON Web Token (JWT) specifications applies throughout this document. In addition, this document defines the following terms, which are used with the meanings specified herein.¶
A procedure by which an End-User authenticates to the OP. Examples include password, one-time password, and biometrics.¶
A standardized identifier that references the Authentication Method typically derived from registered values, such as those defined in RFC 8176, or from values defined by local policy.¶
The execution of one or more Authentication Methods resulting in the OP establishing the End-User's identity for the purposes of an OpenID Connect flow. An Authentication Event may comprise multiple Authentication Methods performed sequentially or in combination.¶
Structured information associated with an Authentication Method employed during an Authentication Event that describes method-specific properties, configuration parameters, or security characteristics.¶
Structured information associated with an Authentication Method that describes method-independent attributes, such as time and location, operational context, or assurance-related characteristics. Interpretation of such information, including its relevance to assurance, policy, or compliance evaluation, is delegated to the applicable trust framework, regulatory environment, or deployment-specific policy. Each Authentication Method employed in an Authentication Event has its associated Authentication Method Metadata.¶
The aggregate set of Authentication Methods, Authentication Method Properties, and Authentication Method Metadata associated with an Authentication Event.¶
A condition expressed by a Client that specifies which Authentication Methods, Authentication Method Properties or Authentication Method Metadata are required for an Authentication Event to be considered acceptable. Authentication Requirements are conveyed using request structures defined by this specification.¶
This section defines the framework used by an OP to represent Authentication Methods and their associated Authentication Method Properties and Authentication Method Metadata.¶
The representation defined in this document is intended to complement, and not replace, existing OpenID Connect constructs such as the amr Claim defined in OpenID Connect Core. While the amr Claim identifies which Authentication Methods were used, it does not provide a mechanism to express method-level properties and metadata. This framework standardizes the representation of such information and enables RPs to evaluate Authentication Events based on Authentication Method Properties and Authentication Method Metadata rather than solely on method identifiers.¶
Authentication Methods employed in an Authentication Event are represented using AMR Details Objects, each of which corresponds to a single Authentication Method executed by the OP. A complete Authentication Event is represented as a list of AMR Details Objects conveyed using a Claim named amr_details. This representation enables RPs to perform deterministic evaluation of Authentication Events, assess conformance with method-level requirements, and interpret contextual attributes relevant to assurance, compliance, and policy evaluation.¶
This specification explicitly separates the concept of which Authentication Methods were performed, as conveyed by the amr Claim, from the concept of how those Authentication Methods were executed, as conveyed by the amr_details Claim. This separation preserves backward compatibility with existing OpenID Connect deployments while enabling richer semantics.¶
An OP implementing this specification MUST produce AMR Details Objects that conform to the structural and processing rules defined in this document. A RP implementing this specification MUST be capable of processing AMR Details Objects and, when applicable, evaluating them against Authentication Requirements expressed in authorization requests (see Section 3).¶
The amr_details Claim conveys the complete set of AMR Details Objects generated during an Authentication Event. The value of the amr_details Claim MUST be a JSON array, where each array element represents a single Authentication Method performed as part of the Authentication Event. Each AMR Details Object is composed of three components: an Authentication Method Identifier, Authentication Method Metadata, and Authentication Method Properties.¶
The following non-normative example illustrates an amr_details Claim representing an Authentication Event where the End-User authenticated using a password method governed by the eIDAS trust framework. The example includes source/contextual information indicating the OP as the issuer of the Authentication Method, along with method-specific metadata such as the password hashing algorithm and policy identifier.¶
{
"amr" : [ "pwd" ],
"amr_details": [
{
"amr_identifier": "pwd",
"amr_metadata" : {
"iss" : "https://idp.gov.com",
"trust_framework": "eidas",
"assurance_level": "low",
"time" : "2025-09-30T18:23:41Z"
},
"amr_properties": {
"pwd_derivation_algorithm": "argon2id",
"pwd_policy_id" : "govbr-password-v2"
}
}
]
}
¶
See Appendix A.1 for additional non-normative examples of amr_details representations.¶
The normative schema for the amr_details Claim is defined below.¶
amr_detailsREQUIRED. An array of JSON objects, each corresponding to an AMR Details Object. Each object is composed of the following top-level members:¶
amr_identifierREQUIRED. A standardized Authentication Method Identifier string referencing the Authentication Method employed. This value MUST correspond to one of the values listed in the amr Claim.¶
amr_metadataREQUIRED. A JSON object containing Authentication Method Metadata. The structure and content of this object are defined in Section 2.1.1.¶
amr_propertiesOPTIONAL. A JSON object containing Authentication Method Properties. The structure and content of this object are defined in Section 2.1.2.¶
Note: Implementations shall ignore any sub-element not defined in this specification or extensions of this specification. Extensions to this specification that specify additional sub-elements under the amr_details element may be created by the OpenID Foundation, ecosystem or scheme operators or singular implementers using this specification.¶
Extensions of this specification, including trust framework definitions, can define further constraints on the data structure.¶
Each AMR Details Object MAY include exactly one Authentication Method Metadata object, conveyed using the amr_metadata member. this object contains source and contextual information about the Authentication Method execution. This information provides provenance and situational context that may be relevant for assurance evaluation, compliance checks, or policy enforcement by the RP.¶
It is noteworthy that this specification allows the OP to report Authentication Methods executed by external authenticators or brokers. In such cases, the amr_metadata attribute indicates the issuer of the Authentication Method, which may differ from the OP itself. In these scenarios, the OP acts as the aggregator and reporter of the Authentication Context. The OP includes the relevant information of the external authenticator in the amr_metadata element and MAY perform validations on the reported data based on its own security policies or trust frameworks. Regardless of the validation level performed by the OP, the RP MUST independently evaluate whether it trusts the reported issuers (amr_metadata.iss) before granting access to sensitive resources.¶
If present, the value of the amr_metadata member MUST be a JSON object. The following members are defined for the amr_metadata object:¶
issOPTIONAL. A string identifier of the entity that performed the Authentication Method (for example, the OP itself, or an external authenticator or broker). If present, the value MUST be a case-sensitive URL containing a scheme and host, and MAY include a port number and path components. The URL MUST NOT include query or fragment components. If this member is not present, the OP indicates that it itself performed the Authentication Method.¶
trust_frameworkOPTIONAL. A string identifier referencing the trust framework under which the Authentication Method was executed. The value MUST correspond to a trust framework defined and governed by a trust framework authority, such as a regulatory body, standards organization, or federation operator, that is applicable to the transaction context. An example value is eidas, which denotes an Authentication Method executed under the European eIDAS framework.¶
assurance_levelOPTIONAL. A string indicating the assurance level associated with the Authentication Method execution. The value MUST correspond to an assurance level defined by the referenced trust framework, local policy, or in a recognized trust framework registry, such as the IANA Trust Frameworks registry. Examples include eidas-loa-high and REFEDS-MFA.¶
timeREQUIRED. A timestamp indicating when the Authentication Method was executed. The value MUST be represented in RFC 3339 format.¶
locationOPTIONAL. A JSON object providing contextual information about the geographic or network origin of the authentication. Location-related data is considered sensitive and SHOULD be conveyed only when explicitly requested by the RP or required by an applicable policy or trust framework. While this specification enables the representation of high-precision information, OPs SHOULD apply data minimization practices where possible, such as truncating IP addresses or reducing the precision of geospatial coordinates. In certain high-assurance use cases, including regulated financial transaction environments, precise origin information MAY be required in order to satisfy security or compliance requirements. This object MAY include the standard address elements defined in Section 5.1.1 of OIDC Core, and MAY additionally include network-related and geospatial attributes, as defined by this specification.¶
ip_addressOPTIONAL. A string representing the IP address from which the Authentication Method was executed, in either IPv4 or IPv6 format.¶
latitudeOPTIONAL. A number representing the latitude coordinate of the location where the Authentication Method was executed, in decimal degrees.¶
longitudeOPTIONAL. A number representing the longitude coordinate of the location where the Authentication Method was executed, in decimal degrees.¶
precisionOPTIONAL. A number indicating the precision of the latitude and longitude coordinates, in meters.¶
Each AMR Details Object MAY include exactly one Authentication Method Properties object, conveyed using the amr_properties member. Authentication Method Properties provide structured, machine-interpretable information describing how the corresponding Authentication Method was performed. These properties complement the Authentication Method Identifier conveyed by the amr_identifier member and the provenance and contextual information conveyed by Authentication Method Metadata in the amr_metadata member.¶
The amr_properties member is OPTIONAL, as not all Authentication Methods expose meaningful properties and some deployments MAY restrict the disclosure of such information due to privacy, policy, or regulatory considerations. If present, the value of the amr_properties member MUST be a JSON object.¶
Unless otherwise stated by a method-specific profile, the following processing rules apply:¶
Each member of amr_properties MUST be a JSON value whose type is consistent with the definitions in this section (string, number, boolean, object, or array). Time-related values SHOULD use the same formatting requirements as amr_metadata.time (see Section 2.1.1).¶
The set of members that MAY appear within amr_properties is bound to the value of amr_identifier. An OP MUST NOT emit Authentication Method Properties that are unrelated to the referenced Authentication Method.¶
An OP MUST NOT include secrets, raw authenticators, replayable artifacts, or values that would enable offline attacks or impersonation. Prohibited content includes, but is not limited to, password hashes or salts, OTP values or seeds, biometric templates, private keys, or full device identifiers that are stable and enable cross-context correlation. When disclosure is necessary for auditability, the OP SHOULD prefer policy identifiers, coarse configuration descriptors, or non-sensitive measurements.¶
Member names and values in amr_properties SHOULD be stable over time and, where feasible, shared across implementations. Deployments defining additional members (see Section 2.1.2.1) SHOULD avoid introducing semantics that overlap with definitions established by this specification.¶
RPs processing amr_properties MUST be tolerant of members not defined in this specification and MUST ignore any member that they do not process. The presence of additional members MUST NOT cause an RP to reject a token.¶
This specification defines a baseline vocabulary for amr_properties applicable to a subset of commonly deployed Authentication Methods. Trust frameworks, scheme operators, and deployments MAY define additional Authentication Method Properties to support new Authentication Methods or to address additional assurance requirements.¶
Extensions SHOULD follow these conventions:¶
Extensions SHOULD avoid defining Authentication Method Properties whose semantics overlap with those defined by other specifications, except where such overlap is strictly necessary to achieve interoperability or clarity.¶
Extensions MUST be designed to disclose no more Authentication Method Properties than are necessary for the intended evaluation, in accordance with privacy-by-design principles and applicable deployment policies.¶
When OpenID Connect Discovery is used, OPs SHOULD advertise supported Authentication Method Properties using the capability advertisement mechanisms defined by this specification (see Section 4), enabling RPs to determine which properties may be conveyed for a given amr_identifier.¶
This section defines baseline vocabularies for method-specific amr_properties. The set of Authentication Methods addressed by this specification is derived from commonly deployed methods as described in RFC 8176. Not all Authentication Methods defined therein are associated with a distinct profile in this section.¶
Where multiple identifiers represent Authentication Methods with substantially overlapping functionality or semantics, this specification defines a profile for a representative identifier only. For example, while both hwk and sc denote hardware-based key mechanisms, a profile is defined for hwk, and the same profile MAY be applied to sc or equivalent identifiers by trust frameworks or deployments. Additionally, methods such as mfa or mca are intentionally omitted as they represent multi-factor or multi-channel constructs rather than standalone methods.¶
Each profile defined below applies when the value of amr_identifier equals the corresponding identifier. The profiles defined in this section are non-exhaustive and MAY be extended by trust frameworks or deployments as needed (see Section 2.1.2.1).¶
face)
Biometric Facial Recognition methods involve the use of facial features to authenticate an End-User. When amr_identifier is face, the amr_properties object MAY contain:¶
face_recognition_algorithmREQUIRED. A string indicating the facial recognition algorithm used during the Authentication Event. Acceptable values include (non-exhaustive):¶
face_sensor_typeOPTIONAL. A string indicating the type of sensor used for facial recognition. Acceptable values include (non-exhaustive):¶
face_match_scoreOPTIONAL. A number representing the confidence score of the facial recognition match. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates a perfect match.¶
face_image_qualityOPTIONAL. A number representing the quality of the facial image used for recognition. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates the highest quality.¶
face_lighting_conditionsOPTIONAL. A number representing the lighting conditions during the facial recognition process. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates optimal lighting.¶
face_pose_variationOPTIONAL. A string indicating the degree of pose variation during the facial recognition process. Acceptable values include (non-exhaustive):¶
face_occlusion_levelOPTIONAL. A number representing the level of occlusion during the facial recognition process. This could include obstructions such as glasses, masks, or other objects partially covering the face. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates no occlusion.¶
face_liveness_detectionOPTIONAL. A boolean indicating whether liveness detection was performed during the facial recognition process. A value of true indicates that liveness detection was employed to ensure that the face being recognized is from a live person rather than a static image or video.¶
face_liveness_detection_methodOPTIONAL. An array of strings indicating the methods used for liveness detection during the facial recognition process. Acceptable values include (non-exhaustive):¶
face_policy_idOPTIONAL. A string identifier referencing the facial recognition policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
fpt)
Fingerprint Recognition methods involve the use of fingerprint patterns to authenticate an End-User. When amr_identifier is fpt, the amr_properties object MAY contain:¶
fpt_recognition_algorithmREQUIRED. A string indicating the fingerprint recognition algorithm used during the Authentication Event. Acceptable values include (non-exhaustive):¶
fpt_sensor_typeOPTIONAL. A string indicating the type of sensor used for fingerprint recognition. Acceptable values include (non-exhaustive):¶
fpt_match_scoreOPTIONAL. A number representing the confidence score of the fingerprint recognition match. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates a perfect match.¶
fpt_image_qualityOPTIONAL. A number representing the quality of the fingerprint image used for recognition. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates the highest quality.¶
fpt_finger_positionOPTIONAL. A string indicating the position of the finger used for recognition. Acceptable values include (non-exhaustive):¶
fpt_pressure_levelOPTIONAL. A number representing the pressure level applied during the fingerprint recognition process. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates optimal pressure.¶
fpt_liveness_detectionOPTIONAL. A boolean indicating whether liveness detection was performed during the fingerprint recognition process. A value of true indicates that liveness detection was employed to ensure that the fingerprint being recognized is from a live person rather than a static image or artificial replica.¶
fpt_liveness_methodOPTIONAL. An array of strings indicating the methods used for liveness detection during the fingerprint recognition process. Acceptable values include (non-exhaustive):¶
fpt_policy_idOPTIONAL. A string identifier referencing the fingerprint recognition policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
hwk)
Hardware Secured Key Proof-of-Possession methods involve the use of cryptographic keys stored in secure hardware modules, such as Hardware Security Modules (HSMs), Trusted Platform Modules (TPMs), embedded Secure Elements, and other tamper-resistant cryptographic processors that ensure private keys remain within hardware boundaries. When amr_identifier is hwk, the amr_properties object MAY contain:¶
hwk_key_idREQUIRED. A string identifier representing the specific hardware key used during the Authentication Event. This identifier MUST be unique within the context of the OP and SHOULD be stable across Authentication Events to facilitate key management and auditing.¶
hwk_key_typeREQUIRED. A string indicating the type of cryptographic key used. Acceptable values include (non-exhaustive):¶
hwk_key_sizeOPTIONAL. A number indicating the size of the cryptographic key in bits. For example, 2048 for RSA keys or 256 for certain elliptic curve keys. This value MUST be a positive integer.¶
hwk_key_usageOPTIONAL. A string indicating the intended usage of the hardware key. Acceptable values include (non-exhaustive):¶
hwk_key_algorithmOPTIONAL. A string indicating the cryptographic algorithm associated with the hardware key. Acceptable values include (non-exhaustive):¶
hwk_aaguidOPTIONAL. The Authenticator Attestation Globally Unique Identifier (AAGUID), as defined in FIDO specifications, if applicable. When present, this value MUST be represented as a lowercase hexadecimal string formatted in the standard 8-4-4-4-12 pattern (e.g., 123e4567-e89b-12d3-a456-426614174000).¶
hwk_fips_complianceOPTIONAL. A string indicating the FIPS (Federal Information Processing Standards) compliance level of the hardware key or its containing module. Acceptable values include (non-exhaustive):¶
hwk_cert_subjectOPTIONAL. A string representing the subject distinguished name (DN) of the X.509 certificate associated with the hardware key, if applicable.¶
hwk_cert_issuerOPTIONAL. A string representing the issuer distinguished name (DN) of the X.509 certificate associated with the hardware key, if applicable.¶
hwk_cert_serial_numberOPTIONAL. A string representing the serial number of the X.509 certificate associated with the hardware key, if applicable.¶
hwk_cert_valid_fromOPTIONAL. A timestamp indicating the start of the validity period of the X.509 certificate associated with the hardware key, if applicable. The value MUST be represented in RFC 3339 format.¶
hwk_cert_valid_toOPTIONAL. A timestamp indicating the end of the validity period of the X.509 certificate associated with the hardware key, if applicable. The value MUST be represented in RFC 3339 format.¶
hwk_policy_idOPTIONAL. A string identifier referencing the hardware key policy under which the key was created or is governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
iris)
Iris Scan Recognition methods involve the use of iris patterns to authenticate an End-User. When amr_identifier is iris, the amr_properties object MAY contain:¶
iris_recognition_algorithmREQUIRED. A string indicating the iris recognition algorithm used during the Authentication Event. Acceptable values include (non-exhaustive):¶
iris_match_scoreOPTIONAL. A number representing the confidence score of the iris recognition match. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates a perfect match.¶
iris_image_qualityOPTIONAL. A number representing the quality of the iris image used for recognition. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates the highest quality.¶
iris_lighting_conditionsOPTIONAL. A number representing the lighting conditions during the iris recognition process. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates optimal lighting.¶
iris_occlusion_levelOPTIONAL. A number representing the level of occlusion during the iris recognition process. This could include obstructions such as glasses or eyelids partially covering the iris. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates no occlusion.¶
iris_liveness_detectionOPTIONAL. A boolean indicating whether liveness detection was performed during the iris recognition process. A value of true indicates that liveness detection was employed to ensure that the iris being recognized is from a live person rather than a static image or video.¶
iris_liveness_methodOPTIONAL. An array of strings indicating the methods used for liveness detection during the iris recognition process. Acceptable values include (non-exhaustive):¶
iris_policy_idOPTIONAL. A string identifier referencing the iris recognition policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
kba)
The attributes set for Knowledge-Based Authentication (KBA) methods can vary significantly based on the implementation, governing policies, and assurance requirements. These attributes are designed to provide insights into the nature and quality of the KBA process without exposing sensitive question or answer material. When amr_identifier is kba, the amr_properties object MAY contain:¶
kba_question_countREQUIRED. A number indicating the total count of knowledge-based questions presented to the End-User during the Authentication Event. This value MUST be a positive integer.¶
kba_required_correct_answersREQUIRED. A number indicating the minimum number of correct answers required for successful authentication. This value MUST be a positive integer and MUST be less than or equal to kba_question_count.¶
kba_question_categoryOPTIONAL. A string indicating the category or type of knowledge-based questions used. Acceptable values include (non-exhaustive):¶
static: Questions based on static personal information typically shared during registration processes (e.g., "what is your mother's maiden name?", "what is your date of birth?").¶
dynamic: Dynamically generated questions based on recent or contextual information (e.g., "what was the amount of your last transaction?", "which service did you access most recently?").¶
behavioral: Questions based on behavioral patterns or habits of the End-User (e.g., "which of these locations have you visited in the last month?").¶
kba_question_sourceOPTIONAL. String identifier of the authority or dataset from which the knowledge questions were derived. OPs may define custom values to represent the provenance of knowledge questions. Examples include credit_bureau, internal, or third_party_provider.¶
kba_max_attemptsOPTIONAL. A number indicating the maximum number of attempts allowed for answering the knowledge-based questions during the Authentication Event. This value MUST be a positive integer.¶
kba_last_updated_atOPTIONAL. A timestamp indicating when the knowledge-based questions were last updated or reviewed for accuracy and relevance. The value MUST be represented in RFC 3339 format.¶
kba_created_atOPTIONAL. A timestamp indicating when the knowledge-based questions were initially created or registered. The value MUST be represented in RFC 3339 format.¶
kba_policy_idOPTIONAL. A string identifier referencing the KBA policy under which the questions were created or are governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
otp)
One-Time Password (OTP) authentication involves the use of a temporary, single-use code generated by an authenticator. OTPs can be delivered through various channels, including hardware tokens, mobile applications, or SMS messages. When amr_identifier is otp, the amr_properties object MAY contain:¶
otp_lengthREQUIRED. A number indicating the length of the OTP used during the Authentication Event. This value MUST be a positive integer.¶
otp_algorithmREQUIRED. A string indicating the OTP generation algorithm used. Acceptable values include (non-exhaustive):¶
otp_formatOPTIONAL. A string indicating the format of the OTP. Acceptable values include (non-exhaustive):¶
otp_delivery_methodOPTIONAL. A string indicating the delivery method used to transmit the OTP to the End-User. Acceptable values include (non-exhaustive):¶
sms: The OTP was delivered via SMS message.¶
email: The OTP was delivered via email.¶
app: The OTP was generated and displayed by a mobile or desktop application.¶
push: The OTP was delivered via a push notification to a registered device.¶
hardware_token: The OTP was generated by a hardware token device.¶
otp_time_to_liveOPTIONAL. Integer value representing the duration, in seconds, during which the OTP remains valid. For TOTP, this corresponds to the time-step size; for HOTP, this represents the acceptable counter window defined by the verifier. It MUST be a positive integer.¶
otp_delivery_timeOPTIONAL. A timestamp indicating when the OTP was delivered to the End-User. The value MUST be represented in RFC 3339 format. This attribute MUST only be used if the OTP was delivered through an out-of-band channel.¶
otp_max_attemptsOPTIONAL. A number indicating the maximum number of attempts allowed for entering the OTP during the Authentication Event. This value MUST be a positive integer.¶
otp_attemptsOPTIONAL. A number indicating the actual number of attempts made by the End-User to enter the OTP during the Authentication Event. This value MUST be a positive integer.¶
otp_policy_idOPTIONAL. A string identifier referencing the OTP policy under which the OTP was created or is governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
pin)
Personal Identification Number (PIN) refers to knowledge-based authentication using a short numeric or alphanumeric code. While similar in nature to password-based verification, PIN authentication typically applies to constrained environments such as hardware tokens, mobile devices, or secure elements, where short secrets are locally verified and managed under stricter retry and locking policies. When amr_identifier is pin, the amr_properties object MAY contain:¶
pin_lengthREQUIRED. A number indicating the length of the PIN used during the Authentication Event. This value MUST be a positive integer.¶
pin_formatREQUIRED. A string indicating the format of the PIN. Acceptable values include (non-exhaustive):¶
pin_max_attemptsOPTIONAL. A number indicating the maximum number of attempts allowed for entering the PIN during the Authentication Event. This value MUST be a positive integer.¶
pin_attemptsOPTIONAL. A number indicating the actual number of attempts made by the End-User to enter the PIN during the Authentication Event. This value MUST be a positive integer.¶
pin_last_updated_atOPTIONAL. A timestamp indicating when the PIN was last set or updated. The value MUST be represented in RFC 3339 format.¶
pin_created_atOPTIONAL. A timestamp indicating when the PIN was initially created. The value MUST be represented in RFC 3339 format.¶
pin_policy_idOPTIONAL. A string identifier referencing the PIN policy under which the PIN was created or is governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
pwd)
Password metadata is primarily intended to support auditability and assurance evaluation (e.g., algorithm family and governing policy), without exposing sensitive password material. When amr_identifier is pwd, the amr_properties object MAY contain:¶
pwd_derivation_algorithmrithmREQUIRED. A string indicating the password hashing or derivation algorithm used to store or verify the password. The value must correspond to a standardized password-based key derivation or hash function defined in relevant specifications. Acceptable may values include (non-exhaustive):¶
pwd_iterationsOPTIONAL. A number indicating the iteration count or work factor used by the password derivation algorithm. This value is relevant for algorithms that support configurable iteration counts, such as PBKDF2 or Argon2. It MUST be a positive integer.¶
pwd_salt_lengthOPTIONAL. A number indicating the length, in bytes, of the salt used in the password hashing or derivation process. This value MUST be a positive integer.¶
pwd_last_updated_atOPTIONAL. A timestamp indicating when the password was last set or updated. The value MUST be represented in RFC 3339 format.¶
pwd_created_atOPTIONAL. A timestamp indicating when the password was initially created. The value MUST be represented in RFC 3339 format.¶
pwd_policy_idOPTIONAL. A string identifier referencing the password policy under which the password was created or is governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
retina)
Similar to Iris Scan Recognition, Retina Scan Recognition methods involve the use of retina patterns to authenticate an End-User. When amr_identifier is retina, the amr_properties object MAY contain:¶
retina_recognition_algorithmREQUIRED. A string indicating the retina recognition algorithm used during the Authentication Event. Acceptable values include (non-exhaustive):¶
retina_match_scoreOPTIONAL. A number representing the confidence score of the retina recognition match. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates a perfect match.¶
retina_image_qualityOPTIONAL. A number representing the quality of the retina image used for recognition. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates the highest quality.¶
retina_lighting_conditionsOPTIONAL. A number representing the lighting conditions during the retina recognition process. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates optimal lighting.¶
retina_occlusion_levelOPTIONAL. A number representing the level of occlusion during the retina recognition process. This could include obstructions such as glasses or eyelids partially covering the retina. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates no occlusion.¶
retina_liveness_detectionOPTIONAL. A boolean indicating whether liveness detection was performed during the retina recognition process. A value of true indicates that liveness detection was employed to ensure that the retina being recognized is from a live person rather than a static image or video.¶
retina_liveness_methodOPTIONAL. An array of strings indicating the methods used for liveness detection during the retina recognition process. Acceptable values include (non-exhaustive):¶
retina_policy_idOPTIONAL. A string identifier referencing the retina recognition policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
sms)
Short Message Service (SMS)-based authentication is a widely adopted method for delivering one-time codes or verification messages to users' mobile devices. This delivery mechanism is classified as an out-of-band factor, complementing the core otp Authentication Method. SMS-based authentication introduces specific risks, such as SIM swapping and message interception. Given that, this specification focuses on conveying metadata that enhances the auditability and assurance evaluation of SMS delivery without exposing sensitive content. When amr_identifier is sms, the amr_properties object MAY contain:¶
sms_gatewayREQUIRED. A string identifier representing the SMS gateway or service provider used to send the authentication messages. This value MUST correspond to a recognized identifier for the SMS service, such as a domain name or service name. Values MAY include:¶
sms_delivery_timeOPTIONAL. A timestamp indicating when the SMS message containing the authentication code was sent to the End-User. The value MUST be represented in RFC 3339 format.¶
sms_originOPTIONAL. A string value identifying the sender identity used for SMS transmission, allowing for origin validation. Values MAY include:¶
sms_origin_typeOPTIONAL. A string indicating the type of sender identity used for SMS transmission. Acceptable values include (non-exhaustive):¶
sms_policy_idOPTIONAL. A string identifier referencing the SMS authentication policy under which the SMS messages were sent or are governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
When amr_identifier is sms, and the authentication occurred through an OTP code, the OP SHOULD also include an entry for the otp method to represent the one-time code delivered via SMS. This dual representation allows RPs to evaluate both the OTP characteristics and the SMS delivery context for a comprehensive assurance assessment.¶
swk)
Similar to Hardware Secured Key methods, Software Secured Key Proof-of-Possession methods involve the use of cryptographic keys stored in software-based secure environments, such as software keystores, encrypted files, or secure enclaves within the operating system. These methods ensure that private keys are protected through software mechanisms, although they may not provide the same level of tamper resistance as hardware-based solutions. When amr_identifier is swk, the amr_properties object MAY contain:¶
swk_key_idREQUIRED. A string identifier representing the specific software key used during the Authentication Event. This identifier MUST be unique within the context of the OP and SHOULD be stable across Authentication Events to facilitate key management and auditing.¶
swk_key_typeREQUIRED. A string indicating the type of cryptographic key used. Acceptable values include (non-exhaustive):¶
swk_key_sizeOPTIONAL. A number indicating the size of the cryptographic key in bits. For example, 2048 for RSA keys or 256 for certain elliptic curve keys. This value MUST be a positive integer.¶
swk_key_usageOPTIONAL. A string indicating the intended usage of the software key. Acceptable values include (non-exhaustive):¶
swk_key_algorithmOPTIONAL. A string indicating the cryptographic algorithm associated with the software key. Acceptable values include (non-exhaustive):¶
swk_attestation_typeOPTIONAL. A string indicating the level of isolation provided by the software environment. Acceptable values include (non-exhaustive):¶
swk_fips_complianceOPTIONAL. A string indicating the FIPS (Federal Information Processing Standards) compliance level of the software key or its containing environment. Acceptable values include (non-exhaustive):¶
swk_cert_subjectOPTIONAL. A string representing the subject distinguished name (DN) of the X.509 certificate associated with the software key, if applicable.¶
swk_cert_issuerOPTIONAL. A string representing the issuer distinguished name (DN) of the X.509 certificate associated with the software key, if applicable.¶
swk_cert_serial_numberOPTIONAL. A string representing the serial number of the X.509 certificate associated with the software key, if applicable.¶
swk_cert_valid_fromOPTIONAL. A timestamp indicating the start of the validity period of the X.509 certificate associated with the software key, if applicable. The value MUST be represented in RFC 3339 format.¶
swk_cert_valid_toOPTIONAL. A timestamp indicating the end of the validity period of the X.509 certificate associated with the software key, if applicable. The value MUST be represented in RFC 3339 format.¶
swk_policy_idOPTIONAL. A string identifier referencing the software key policy under which the key was created or is governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
tel)
Telephone-based Authentication Methods utilize telephony channels to verify the identity of the End-User. These methods often involve delivery of OTPs, user confirmation through Dual-Tone Multi-Frequency (DTMF) input, or out-of-band verification calls. This category encompasses both Interactive Voice Response (IVR) systems and human-operator-based confirmations, offering auditability of telephony-mediated authentication flows. When amr_identifier is tel, the amr_properties object MAY contain:¶
tel_gatewayREQUIRED. A string identifier representing the telephony gateway or service provider used to facilitate the authentication process. This value MUST correspond to a recognized identifier for the telephony service, such as a domain name or service name. Values MAY include:¶
tel_call_typeOPTIONAL. A string indicating the type of telephone call used for authentication. Acceptable values include (non-exhaustive):¶
tel_call_timeOPTIONAL. A timestamp indicating when the telephone call for authentication was initiated or received. The value MUST be represented in RFC 3339 format.¶
tel_call_durationOPTIONAL. A number indicating the duration of the telephone call used for authentication, measured in seconds. This value MUST be a positive integer.¶
tel_call_recordedOPTIONAL. A boolean indicating whether the telephone call was recorded for audit or verification purposes. A value of true indicates that the call was recorded.¶
tel_call_confirmation_methodOPTIONAL. A string indicating the method used for user confirmation during the telephone-based authentication. Acceptable values include (non-exhaustive):¶
tel_voice_qualityOPTIONAL. A numeric value representing the perceived audio quality during the authentication call, typically measured using a Mean Opinion Score (MOS) or derived using ITU-T~P.862 (PESQ). This value MUST be a number between 1 and 5, where higher values indicate better quality.¶
tel_policy_idOPTIONAL. A string identifier referencing the telephone authentication policy under which the telephony interactions were conducted or are governed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
When amr_identifier is tel, and the authentication occurred through an OTP code delivered via telephone, the OP SHOULD also include an entry for the otp method to represent the one-time code delivered through the telephony channel. The same applies when the telephone method is used to conduct knowledge-based authentication; in such cases, the OP SHOULD also include an entry for the kba method.¶
user)
User Presence Test methods involve simple interactions by the End-User to confirm their presence during the Authentication Event. When amr_identifier is user, the amr_properties object MAY contain:¶
user_test_typeREQUIRED. A string indicating the type of user presence test performed. Acceptable values include (non-exhaustive):¶
user_test_durationOPTIONAL. A number indicating the duration of the user presence test, measured in seconds. This value MUST be a positive integer.¶
user_policy_idOPTIONAL. A string identifier referencing the user presence test policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
vbm)
Voiceprint Recognition methods involve the use of voice patterns to authenticate an End-User. When amr_identifier is vbm, the amr_properties object MAY contain:¶
vbm_recognition_algorithmREQUIRED. A string indicating the voiceprint recognition algorithm used during the Authentication Event. Acceptable values include (non-exhaustive):¶
vbm_match_scoreOPTIONAL. A number representing the confidence score of the voiceprint recognition match. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates a perfect match.¶
vbm_audio_qualityOPTIONAL. A number representing the quality of the audio sample used for recognition. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates the highest quality.¶
vbm_background_noise_levelOPTIONAL. A number representing the level of background noise during the voiceprint recognition process. The value MUST be a floating-point number between 0.0 and 1.0, where 1.0 indicates no background noise.¶
vbm_liveness_detectionOPTIONAL. A boolean indicating whether liveness detection was performed during the voiceprint recognition process. A value of true indicates that liveness detection was employed to ensure that the voice being recognized is from a live person rather than a recording.¶
vbm_liveness_methodOPTIONAL. An array of strings indicating the methods used for liveness detection during the voiceprint recognition process. Acceptable values include (non-exhaustive):¶
vbm_policy_idOPTIONAL. A string identifier referencing the voiceprint recognition policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
wia)
Windows Integrated Authentication (WIA) leverages the authentication mechanisms provided by Windows operating systems, such as Kerberos or NTLM, to authenticate users seamlessly within a Windows domain environment. When amr_identifier is wia, the amr_properties object MAY contain:¶
wia_protocolREQUIRED. A string indicating the specific Windows authentication protocol used during the Authentication Event. Acceptable values include (non-exhaustive):¶
wia_domainOPTIONAL. A string representing the Windows domain in which the End-User's account resides. This value MUST correspond to the domain name used in the Windows environment.¶
wia_workstationOPTIONAL. A string representing the name of the workstation or computer from which the End-User initiated the authentication. This value MUST correspond to the NetBIOS name or fully qualified domain name (FQDN) of the workstation.¶
wia_policy_idOPTIONAL. A string identifier referencing the Windows Integrated Authentication policy under which the method was executed. The value MUST correspond to a policy registered in a recognized policy registry or defined by local policy.¶
amr_details Delivery
This section defines the rules governing when and how the amr_details Claim is returned by the OP.¶
The delivery of the amr_details Claim follows the general OIDC principles for Claims issuance defined in Section 5 of OIDC Core, allowing OPs to apply internal policies, trust frameworks, and regulatory requirements while ensuring deterministic behavior when the Claim is explicitly requested by the RP.¶
amr_details Claim
An OP is not required to return the amr_details Claim unless it is explicitly requested by the RP.¶
When requested, the OP MUST evaluate the request according to its declared capabilities and the processing rules defined in this specification (see Section 3.3).¶
Notwithstanding the above, an OP MAY return the amr_details Claim without an explicit request from the RP, based on internal policies, trust frameworks, regulatory obligations, or default Claim issuance rules. The determination of such policies is outside the scope of this specification.¶
When a RP explicitly requests the amr_details Claim, the OP MUST return the Claim in the location(s) specified in the request, such as within the ID Token or via the UserInfo Endpoint, as defined by OIDC Core. If the OP is unable to populate the amr_details Claim for a given Authentication Event, due to lack of available information, policy restrictions, or other operational limitations, the OP MAY omit the claim. However, it SHOULD try to provide at least partial information whenever possible.¶
If the RP does not explicitly request the amr_details Claim and the OP elects to return it based on internal policy, the OP MAY choose the delivery location.¶
The content of the amr_details Claim returned via different delivery mechanisms MUST be semantically equivalent.¶
Given that the amr_details Claim may reveal sensitive information about the Authentication Context, OPs and RPs are encouraged to apply data minimization principles when requesting or returning this Claim.¶
RPs SHOULD request amr_details only when strictly necessary for their security or compliance requirements. OPs SHOULD avoid returning amr_details by default unless required by policy or trust framework obligations.¶
Below is an example of an ID Token payload including the amr_details Claim:¶
{
"iss" : "https://server.example.com",
"sub" : "248289761",
"aud" : "https://rs.example.com/",
"exp" : 1544645174,
"client_id" : "client",
"amr" : [ "pwd", "otp" ],
"amr_details": [
{
"amr_identifier": "pwd",
"amr_metadata" : {
"iss" : "https://idp.gov.com",
"trust_framework": "eidas",
"assurance_level": "low",
"time" : "2025-09-30T18:23:41Z"
},
"amr_properties": {
"pwd_derivation_algorithm": "argon2id",
"pwd_policy_id" : "govbr-password-v2"
}
},
{
"amr_identifier": "otp",
"amr_metadata" : {
"iss" : "https://broker.example.org",
"trust_framework": "eidas",
"assurance_level": "substantial",
"time" : "2025-09-30T18:23:55Z"
},
"amr_properties": {
"otp_algorithm" : "TOTP",
"otp_length" : 6,
"otp_time_to_live": 60
}
}
]
}
¶
Authentication Methods and their properties are requested during the authentication process using the amr_details Claim within the claims parameter, as defined in Section 5.5 of OIDC Core. This mechanism allows RPs to express their assurance requirements and policy constraints in a standardized manner, granting them greater control over the Authentication Event. Clients can specify not only which Authentication Methods are required but also how those methods should be executed.¶
Unlike the representation of Authentication Methods used in the authentication response (which is a JSON Array), the amr_details Claim within the authentication request MUST be a JSON Object. This object serves as a logical template or filter that the OP MUST satisfy to issue the token.¶
Within the amr_details expression object, the RP MAY:¶
null values;¶
value and essential operators;¶
all_of and one_of.¶
A non-normative example of negotiating Authentication Methods and attributes using the claims parameter is provided below:¶
{
"id_token": {
"amr_details": {
"amr_identifier": { "value": "pwd", "location": null },
"amr_properties": {
"pwd_derivation_algorithm": null,
"pwd_policy_id" : null
}
}
}
}
¶
Besides including the amr_details Claim within the claims parameter in authentication requests, this specification does not define any other means for requesting Authentication Methods. However, some deployments MAY choose to negotiate or request Authentication Methods through scope values (e.g., scope=pwd+otp) provided there is prior agreement between the RP and the OP regarding the semantics of such scopes. Such approaches are possible under OIDC Core but fall outside the normative scope of this specification.¶
The request structure for amr_details introduces a set of operators and constraints that extend OIDC's expressiveness for authentication negotiation.¶
one_of and all_of
Logical operators for combining multiple Authentication Methods or attributes within a single request element. By using these operators, RPs can request combinations of methods and attributes with specific logical relationships: for example, requiring at least one method from a set (one_of) or mandating that all specified methods be used (all_of). These operators MUST only be used to group JSON objects rather than primitive values. If RPs need to express logical combinations of primitive values, they MUST use the one_of and all_of operators at the parent object level and make use of the value attribute within each grouped object. For example, to request either TOTP or HOTP as the OTP algorithm, the following structure would be used:¶
{
"otp_algorithm": {
"one_of": [
{ "value": "TOTP" },
{ "value": "HOTP" }
]
}
}
¶
min and max
Quantitative constraints applicable to numeric attributes. These operators MUST only be evaluated when the target attribute is a JSON Number. If a type mismatch occurs (e.g., applying min to a JSON String), or if the attribute value does not satisfy the constraint, the OP MUST ignore the constraint for processing purposes, consistent with the treatment of descriptive attributes described in Section 3.2.¶
max_ageTemporal constraint indicating the maximum allowable age, in seconds, of an Authentication Method execution relative to the current request processing time. If the elapsed time since amr_metadata.time exceeds this value, the OP SHOULD NOT generate an error; instead, it MUST report the actual amr_metadata.time in the response, allowing the RP to enforce its own freshness policy.¶
These operators and constraints allow RPs to express complex Authentication Requirements in a structured and machine-interpretable manner, enhancing the negotiation capabilities of the OIDC protocol. The following non-normative example illustrate the use of these operators to express an authentication proccess where biometric authentication is required along with either a password or another OTP:¶
{
"claims": {
"id_token": {
"amr_details": {
"all_of": [
{
"amr_identifier": { "value": "face" }
},
{
"one_of": [
{
"amr_identifier": { "value": "pwd" }
},
{
"amr_identifier": { "value": "otp" },
"amr_properties": { "otp_length": null, "otp_algorithm": null }
}
]
}
]
}
}
}
}
¶
More examples of requesting Authentication Methods and attributes using the claims parameter are provided in Appendix A.2.¶
essential Clause
The semantic interpretation of the essential parameter within logical structures is defined as follows:¶
When essential is applied to the amr_details claim as a whole, or to descriptive attributes of Authentication Methods (such as metadata or properties), its behavior follows the behavior described in Section 5.5.1 of OIDC Core. In such cases, the Authorization Server MUST NOT generate an error if the requested information is not returned, regardless of whether it is marked as Essential or Voluntary.¶
When essential is applied to a specific Authentication Method, identified through the amr_identifier element, it expresses a strict Authentication Requirement. If the Authorization Server is unable to authenticate the End-User using the specified Authentication Method, the Authorization Server MUST treat that outcome as a failed authentication attempt. The following rules apply when evaluating essential within different contexts of the requirement expression:¶
all_ofAll elements marked as essential within an all_of group MUST be satisfied. Failure to satisfy any essential element results in an authentication failure.¶
one_ofIf a one_of group is required, the OP MUST satisfy at least one path that meets the essentiality requirements. If the RP marks specific elements within a one_of group as essential, it indicates a mandatory preference. If none of the essential elements within the group can be satisfied, the OP MUST treat the attempt as a failure, even if non-essential elements are available.¶
Note: This distinction allows RPs to strictly require specific Authentication Methods when necessary, while preserving OpenID Connect compatibility and avoiding unnecessary authentication failures when only descriptive authentication information is unavailable.¶
A non-normative example of requesting a password-based Authentication Method as essential is provided below:¶
{
"claims": {
"id_token": {
"amr_details": {
"amr_identifier": {
"value" : "pwd",
"essential": true
}
}
}
}
}
¶
When processing an amr_details request, the Authorization Server MUST evaluate the requirement expression as follows:¶
The OP MUST attempt to satisfy the logical tree of the expression, prioritizing Authentication Methods that fulfill essential: true criteria applied to the amr_identifier element.¶
For all other attributes, including metadata in amr_properties or contextual info in amr_metadata, the OP SHOULD perform a "best-effort" satisfaction of the constraints. Type mismatches or unsatisfied quantitative/temporal constraints on these descriptive attributes MUST NOT result in an authentication failure at the OP level.¶
The OP MAY provide more information than requested if such data is mandatory under its own policy, or less information if some parameters are optional or unsupported.¶
If an Authentication Method explicitly identified through the amr_identifier element is marked as essential and cannot be satisfied, the Authorization Server MUST return an error as defined in Section 3.4.¶
In all other cases, the OP SHOULD proceed with the authentication and return the amr_details claim reflecting the methods and metadata employed, enabling the RP to perform its own final policy evaluation.¶
This behavior preserves continuity of authentication while maintaining transparency for the RP, which can then evaluate the returned amr_details against its own acceptance criteria. If the RP requires strict adherence to its requested Authentication Methods, it MUST implement its own logic to assess the returned amr_details and decide whether to accept or reject the authentication based on the actual methods employed. The OP is not responsible for enforcing the RP's policies beyond attempting to meet the requested conditions.¶
This specification does not introduce new error codes, error responses, or error handling mechanisms beyond those defined by OpenID Connect Core and related specifications. However, specific error conditions arise from the processing of amr_details requests and Authentication Method requirements:¶
If a requirement expression contains Authentication Methods or constraints marked as essential that cannot be satisfied (due to OP limitations, End-User unavailability of factors, or verification failure), the Authorization Server MUST interrupt the flow and return an error to the RP.¶
The OP MUST use the access_denied error code, as defined in Section 4.1.2.1 of RFC 6749. The OP SHOULD include an error_description parameter detailing which part of the requirement expression (e.g., which amr_identifier) could not be satisfied to assist the RP in guiding the End-User.¶
All other error conditions arising from the processing of amr_details requests and Authentication Method requirements MUST be handled in accordance with the error handling rules defined by OIDC, including those applicable to the Authorization Endpoint, Token Endpoint, and other relevant protocol endpoints.¶
If the Authorization Server does not support processing Authentication Method requirements conveyed through the claims parameter, as indicated by the absence of support declaration in its metadata, the Authorization Server MUST NOT treat such requests as an error. In this case, the Authorization Server SHOULD ignore the Authentication Method requirements and proceed with authentication according to its default behavior, subject to its internal policies and capabilities.¶
This specification defines additional OpenID Provider Metadata parameters (see OpenID Connect Discovery 1.0) that allow RPs to determine the level of support for the amr_details Claim and for Authentication Method requests.¶
Support for this specification is intentionally divided into two distinct and independent capabilities:¶
Which indicates the ability of the OP to return the amr_details Claim describing the Authentication Methods used during an Authentication Event.¶
Which indicates the ability of the OP to process Authentication Method requirements expressed by the RP through the claims parameter.¶
Note: This separation allows OPs to adopt this specification incrementally, supporting the emission of amr_details as an informational claim without necessarily implementing Authentication Method negotiation.¶
amr_details
An OP that is capable of returning the amr_details Claim as part of an ID Token or via the UserInfo Endpoint MUST declare this capability by including amr_details in the claims_supported metadata parameter defined by OpenID Connect Discovery.¶
The presence of amr_details in claims_supported indicates that the OP MAY return the amr_details Claim when requested, describing the Authentication Methods used during the authentication of the End-User.¶
This declaration does not imply that the OP supports processing Authentication Method requirements expressed by the RP.¶
An OP that supports processing Authentication Method requirements expressed through the claims parameter, including constraints and essentiality applied to Authentication Methods, MUST declare this capability using the following metadata parameter:¶
amr_details_request_supportedOPTIONAL. Boolean value indicating whether the OP supports processing Authentication Method requests conveyed via the claims parameter, as defined in this specification. If omitted or set to false, the OP does not process Authentication Method requirements and treats any such request as informational only. An OP that sets amr_details_request_supported to true MUST comply with the processing rules defined in this specification for Authentication Method requests, including the handling of essential authentication factors and authentication failure conditions.¶
RPs that require strict enforcement of Authentication Method requirements MUST verify that amr_details_request_supported is set to true before issuing such requests.¶
The following metadata parameters are OPTIONAL and provide additional information about the Authentication Methods and constraints supported by the OP. When present, they MUST accurately reflect the provider's capabilities.¶
amr_identifiers_supportedOPTIONAL. JSON array of strings. Enumerates Authentication Methods supported by the OP, preferably using identifiers registered in RFC 8176 (e.g., pwd, otp, face, hwk).¶
<amr>_properties_supportedOPTIONAL. For each Authentication Method <amr> listed in amr_identifiers_supported, the OP MAY declare a corresponding metadata field named <amr>_properties_supported. This field is a JSON array of strings enumerating the specific metadata supported by the OP for that Authentication Method. For example, if otp is listed in amr_identifiers_supported, the OP SHOULD declare otp_properties_supported to indicate which OTP-related attributes (e.g., otp_length, otp_algorithm) it can process or provide. The OP SHOULD use the attribute names defined in Section 2.1.2 of this specification.¶
<amr_properties>_values_supportedOPTIONAL. For each amr_properties parameter defined in Section 2.1.2, the OP MAY declare a corresponding metadata field named <amr_properties>_values_supported. This field is a JSON array of strings enumerating the specific values supported by the OP for that amr_properties parameter. For example, if otp_algorithm is defined (i.e., otp_properties_supported contains otp_algorithm), the OP MUST declare otp_algorithm_values_supported to indicate which OTP algorithms (e.g., TOTP, HOTP) it can process or provide. The OP SHOULD use the value names defined in Section 2.1.2 of this specification whenever possible.¶
trust_framework_values_supportedOPTIONAL. JSON array of strings. Enumerates trust frameworks recognized or supported by the OP for contextual information (e.g., eIDAS, NIST SP 800-63).¶
assurance_level_values_supportedOPTIONAL. JSON array of strings. Enumerates assurance levels recognized or supported by the OP for contextual information (e.g., low, medium, high). Its values MUST correspond to those defined by relevant trust frameworks declared in trust_framework_values_supported.¶
location_types_supportedOPTIONAL. JSON array of strings. List of supported location-related attributes within the amr_metadata.location object. It MAY include any combination of the following values: formatted, street_address, locality, region, postal_code, country, ip_address, latitude, longitude, precision.¶
An example OP Metadata declaration including these parameters is provided in Appendix A.3.¶
This specification introduces new mechanisms for representing and requesting Authentication Methods and attributes. Implementers MUST consider the privacy implications of exposing detailed Authentication Method information, as this could potentially reveal sensitive information about users' authentication practices or capabilities.¶
OPs and RPs MUST ensure that their use of the mechanisms defined in this specification complies with applicable data protection and privacy regulations. The interpretation and application of such regulations are outside the scope of this specification.¶
RPs and OPs SHOULD also implement appropriate safeguards to protect user privacy, such as minimizing the amount of information shared and adhering to relevant data protection regulations.¶
This specification does not define requirements for user consent, notification, or user interface behavior. Such mechanisms, when applicable, are deployment-specific and may be governed by trust frameworks, contractual agreements, or regulatory requirements.¶
OPs and RPs SHOULD limit the retention of such information to what is necessary for their intended purposes and SHOULD avoid secondary use of Authentication Context information beyond the scope for which it was collected.¶
The disclosure of network and geospatial location data facilitates advanced fraud detection but introduces significant privacy risks. This specification provides the mechanisms for such disclosure but does not encourage its inadvertent or default use.¶
Implementers MUST recognize that the collection and transmission of location data are subject to regional laws, regulations, and privacy standards which are outside the scope of this document. It is the responsibility of the OP and RP to ensure that the level of detail provided is proportionate to the risk, justified by a valid legal basis, and compliant with applicable data protection requirements.¶
Data minimization remains a core principle; OPs SHOULD only provide the minimum level of location precision necessary to satisfy the RP's security or compliance objectives.¶
The amr_details Claim provides structured information about the Authentication Context and therefore introduces additional security and privacy considerations beyond those associated with the amr Claim.¶
RPs MUST treat the amr_details Claim as trustworthy only when it is obtained through mechanisms that provide integrity and authenticity guarantees equivalent to those defined by OIDC.¶
Specifically, a RP MUST only rely on amr_details when the Claim is:¶
Included in a valid ID Token issued by the OP and whose signature, issuer (iss), audience (aud), and temporal Claims (such as exp and iat) have been successfully validated; or¶
Returned by the UserInfo Endpoint over a secure transport channel and bound to a valid access token issued by the same OP.¶
RPs MUST NOT rely on amr_details obtained outside these contexts or without performing the appropriate validation steps defined by OIDC.¶
When Authentication Method requirements are expressed by the RP, the OP may authenticate the End-User using the best available Authentication Method according to its capabilities and policies, unless strict requirements are explicitly enforced as defined in this specification.¶
Regardless of the OP behavior, RPs MUST evaluate the returned amr_details Claim against their local authentication policies.¶
If the Authentication Methods used do not satisfy the RP's requirements, the RP MUST treat the Authentication Event as incomplete and MUST NOT grant access solely based on the successful completion of the OpenID Connect flow.¶
This specification intentionally assigns the final enforcement of Authentication Requirements to the RP in order to prevent downgrade attacks and to preserve compatibility with OPs that support informational reporting without Authentication Method negotiation.¶
The amr_details Claim may include authentication information originating from different issuers, such as in federated, brokered, or delegated authentication scenarios.¶
The inclusion of an issuer identifier (amr_metadata.iss) within the authentication descriptor does not inherently imply trust. RPs MUST maintain a list of trusted issuers or rely on a shared trust framework to evaluate the validity of methods performed by third-party authenticators. An OP reporting a third-party Authentication Method effectively acts as a relayer; the ultimate security decision regarding the provenance of the factor remains with the RP.¶
This specification does not define trust frameworks, federation policies, or mechanisms for establishing trust between RPs and external authentication sources. Such trust decisions are outside the scope of this specification and MUST be established through out-of-band agreements, federation metadata, or applicable trust frameworks.¶
The information conveyed by the amr_details Claim may reveal characteristics of the End-User's authentication capabilities and environment, which could enable correlation or fingerprinting across RPs.¶
OPs SHOULD apply data minimization principles when returning amr_details, limiting the information provided to what is necessary to describe the Authentication Context.¶
RPs SHOULD request amr_details only when required to meet security, regulatory, or compliance objectives. OPs SHOULD NOT return highly identifying or fine-grained authentication details by default unless required by internal policy, trust frameworks, or regulatory obligations.¶
The amr_details Claim include temporal information describing when Authentication Methods were performed or validated. RPs MAY use such information to evaluate the freshness of the Authentication Context according to their security policies.¶
RPs SHOULD evaluate the temporal attributes of Authentication Methods to mitigate replay attacks and ensure that the Authentication Context remains valid for the duration of the session or transaction. If the temporal information indicates that Authentication Methods are stale or outdated, the RP MAY require re-authentication or additional verification steps.¶
This specification does not define specific temporal thresholds or policies; such decisions MUST be made by the RP based on its security requirements.¶
This specification is designed to be fully compatible with existing OpenID Connect implementations. RPs and OPs that do not support the extensions defined in this document will continue to operate according to the base OpenID Connect specifications, ignoring any additional parameters or claims introduced here. Implementers MUST ensure that their systems can gracefully handle cases where the other party does not support these extensions.¶
All examples in this appendix are non-normative and provided for illustrative purposes only.¶
The following non-normative example illustrates an amr_details Claim representing an Authentication Event where the End-User authenticated using a password alongside a one-time password method provided by an external authentication broker. The example includes source/contextual information indicating the broker as the issuer of the OTP method including method-specific metadata such as OTP length and algorithm.¶
{
"amr" : [ "pwd", "otp" ],
"amr_details": [
{
"amr_identifier": "pwd",
"amr_metadata" : {
"iss" : "https://idp.gov.com",
"trust_framework": "eidas",
"assurance_level": "low",
"time" : "2025-09-30T18:23:41Z",
"location" : { "ip_address": "192.0.2.1", "country": "US" }
},
"amr_properties": {
"pwd_derivation_algorithm": "argon2id",
"pwd_policy_id" : "govbr-password-v2"
}
},
{
"amr_identifier": "otp",
"amr_metadata" : {
"iss" : "https://authbroker.com",
"trust_framework": "custom-broker-framework",
"assurance_level": "substantial",
"time" : "2025-09-30T18:23:45Z",
"location" : { "ip_address": "192.0.2.1", "country": "US" }
},
"amr_properties": { "otp_length": 6, "otp_algorithm": "TOTP" }
}
]
}
¶
These examples illustrate how a RP can request specific Authentication Methods and attributes using the claims parameter in an OpenID Connect authentication request.¶
This example demonstrates how to request an OTP Authentication Method with specific length constraints and algorithm via the UserInfo endpoint:¶
{
"claims": {
"userinfo": {
"amr_details": {
"amr_identifier": { "value": "otp" },
"amr_properties": {
"otp_length" : null,
"otp_algorithm": { "value": "TOTP" }
}
}
}
}
}
¶
all_of and one_of Operators
In the scenario below, the RP requests that the End-User authenticate using biometric authentication (face) along with either a password (pwd). Both methods are marked as essential:¶
{
"claims": {
"id_token": {
"amr_details": {
"all_of": [
{
"amr_identifier": {
"value": "face",
"essential": true
}
}, {
"amr_identifier": {
"value": "pwd",
"essential": true
}
}
]
}
}
}
}
¶
By using the one_of operator, the RP can request that the End-User authenticate using either a password (pwd) or a one-time password (otp):¶
{
"claims": {
"id_token": {
"amr_details": {
"one_of": [
{
"amr_identifier": {
"value": "pwd"
}
},
{
"amr_identifier": {
"value": "otp"
}
}
]
}
}
}
}
¶
all_of and one_of with Method Metadata
It is also possible to combine the all_of and one_of operators with method metadata. In the following example, the RP requests OTP authentication with either numeric or alphanumeric format, along with biometric authentication:¶
{
"claims": {
"id_token": {
"amr_details": {
"all_of": [
{
"amr_identifier": { "value": "otp" },
"amr_properties": {
"one_of": [
{
"otp_format": { "value": "alphanumeric" }
},
{
"otp_format": { "value": "numeric" }
}
]
}
},
{
"amr_identifier": { "value": "face" }
}
]
}
}
}
}
¶
max and min Operators
The following example demonstrates how to request an OTP Authentication Method with specific length constraints using the min and max operators:¶
{
"claims": {
"id_token": {
"amr_details": {
"amr_identifier": { "value": "otp" },
"amr_properties": {
"otp_length": { "min": 6, "max": 10 }
}
}
}
}
}
¶
max_age Operator
The following example demonstrates how to request a biometric Authentication Method (face) with a requirement that the verification must have occurred within the last 300 seconds relative to the current processing time:¶
{
"claims": {
"id_token": {
"amr_details": {
"amr_identifier": { "value": "face" },
"amr_metadata" : {
"time": { "max_age": 300 }
}
}
}
}
}
¶
In this example, the RP expresses a complex Authentication Requirement where the End-User must authenticate using a password (pwd) and either a one-time password (otp) or facial recognition (face) with specific constraints:¶
{
"claims": {
"id_token": {
"amr_details": {
"all_of": [
{
"amr_identifier": { "value": "pwd", "essential": true }
},
{
"one_of": [
{
"amr_identifier": { "value": "otp" },
"amr_properties": {
"otp_length" : { "min": 6, "max": 10 },
"otp_algorithm": { "value": "TOTP" }
}
},
{
"amr_identifier": { "value": "face" },
"amr_metadata" : {
"time": { "max_age": 300 }
}
}
]
}
]
}
}
}
}
¶
The following example illustrates an OP metadata document indicating support for the amr_details Claim and Authentication Method request processing:¶
{
"issuer": "https://op.example.com",
"authorization_endpoint": "https://op.example.com/authorize",
"token_endpoint": "https://op.example.com/token",
"userinfo_endpoint": "https://op.example.com/userinfo",
"jwks_uri": "https://op.example.com/jwks",
"claims_supported": [ "sub", "name", "email", "amr_details" ],
"amr_details_request_supported": true,
"amr_identifiers_supported": [ "pwd", "otp", "face" ],
"pwd_properties_supported": [ "pwd_derivation_algorithm", "pwd_policy_id" ],
"otp_properties_supported": [ "otp_length", "otp_algorithm" ],
"face_properties_supported": [ "face_recognition_algorithm", "face_image_quality" ],
"pwd_derivation_algorithm_values_supported": [ "argon2id", "bcrypt", "scrypt" ],
"pwd_policy_id_values_supported": [ "gov-password-v1", "gov-password-v2" ],
"otp_algorithm_values_supported": [ "TOTP", "HOTP" ],
"face_recognition_algorithm_values_supported": [ "cnn", "eigenfaces", "fisherfaces" ],
"trust_framework_values_supported": [ "eidas" ],
"assurance_level_values_supported": [ "low", "substantial", "high" ],
"location_types_supported": [ "ip_address", "country" ]
}
¶
Copyright (c) 2019 The OpenID Foundation.¶
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶
The authors wish to acknowledge the contributions of the following individuals to the development of this specification: Frederik Krogsdal Jacobsen, and Andy Barlow. Their feedback and insights were included in the final version of this document.¶
[[ To be removed from the final specification ]]¶
-00 (WG document)¶