]> IDsec Solutions AB

Forskningsbyn Ideon Lund 223 70 SE sts@aaa-sec.com

IDsec Solutions AB

Forskningsbyn Ideon Lund 223 70 SE martin@litsec.se

certificate oidc authentication X.509 RFC 7773 defines the Authentication Context certificate extension, which carries information about how the subject of an X.509 certificate was authenticated when the certificate was issued. RFC 7773 defines one context information type, for subjects authenticated by means of a Security Assertion Markup Language (SAML) assertion. This document defines a second context information type for subjects authenticated by means of OpenID Connect, where the identity information is obtained from an ID Token, where applicable in combination with a UserInfo Response. The information is expressed as a JSON object and provides the OpenID Connect counterpart to the SAML Authentication Context Information defined in RFC 7773. This document also updates RFC 7773 by clarifying that an application processing the extension ignores context information types it does not support regardless of the criticality of the extension, and by recommending that the extension not be marked critical. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction The Authentication Context certificate extension allows a Certification Authority (CA) to record, in an issued certificate, information about the authentication event that preceded issuance. This is useful when the CA relies on an external identity provider to authenticate the subject, for example when certificates are issued on the fly to support electronic signatures, and relying parties need to understand the origin and assurance of the identity data placed in the certificate. The extension is a sequence of AuthenticationContext structures, each identified by a contextType URI that also determines the syntax of the accompanying contextInfo string. defines one context type, Security Assertion Markup Language (SAML) Authentication Context Information (SACI), for subjects authenticated by a SAML assertion, and explicitly provides for other documents to define additional context types. OpenID Connect has become a widely deployed alternative to SAML for federated authentication. An OpenID Connect authentication results in an ID Token, a JSON Web Token (JWT) containing claims about the authentication event and the authenticated End-User. Further claims about the End-User may be obtained from the UserInfo Endpoint of the OpenID Provider. This document defines OpenID Connect Authentication Context Information (OACI), a context type whose contextInfo is a JSON object carrying the information from the ID Token and, where applicable, the UserInfo Response that is relevant to the issuance of a certificate. OACI is deliberately structured as the OpenID Connect analogue of SACI. It records the issuer of the ID Token, the time of authentication, the authentication context class(es) asserted, a reference to the ID Token, the identity under which the CA acted as Relying Party, and a mapping from ID Token claims to the subject name attributes of the certificate that were derived from them. OACI is defined using the extensibility provided by Section 2 of . With a second context type in existence, the processing rule in that ties the handling of unsupported context types to the criticality of the extension becomes an obstacle to interoperability: an application that implements only SACI would be required to reject a certificate carrying OACI in a critical extension, although the two convey the same kind of information. This document therefore also updates as described in .

Conventions and Definitions 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 BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses the terms OpenID Provider (OP), Relying Party (RP), End-User, ID Token, Claim, UserInfo Endpoint and UserInfo Response as defined in . The RP of the OpenID Connect authentication is either the CA that issues the certificate or a Registration Authority (RA) acting on behalf of the CA, such as a signing service that authenticates the End-User and then requests a certificate from the CA, conveying the authentication information with the request. For brevity, this document refers to the CA as the RP; where an RA performs the authentication, statements about the CA's handling of the ID Token and UserInfo Response apply to the RA, and the CA is responsible for the information under its certificate policy and practices. The terms contextType, contextInfo and AuthenticationContext refer to the ASN.1 components defined in Section 2 of .

OpenID Connect Authentication Context Information

Context Type Identifier An AuthenticationContext carrying OpenID Connect Authentication Context Information in accordance with this specification MUST have a contextType with the following URI value: The contextInfo component of such an AuthenticationContext MUST be present and MUST contain a JSON object as specified in .

Encoding The contextInfo value is a UTF8String . Its content MUST be a single JSON text whose top-level value is an object. The JSON text MUST conform to the I-JSON message format . In particular, it MUST be encoded in UTF-8, MUST NOT begin with a byte order mark, and MUST NOT contain duplicate member names. Producers SHOULD serialize the object without insignificant whitespace in order to limit certificate size. Consumers MUST accept any serialization that is valid I-JSON. Consumers MUST ignore members of the top-level object, and of the objects in the claim_mappings array, that they do not recognize. This allows future documents and deployment profiles to add members without breaking existing implementations.

JSON Structure The top-level object contains the members defined below. The member names are chosen for readability by a reader of the certificate; where a member corresponds to an ID Token claim, the correspondence is stated. Unless otherwise specified, a member is OPTIONAL. This document places no requirement on the presence of any member whose source value is itself optional in . Deployment profiles of this document MAY require the presence of specific members, and relying parties decide which members they require in order to accept a certificate.

iss:

REQUIRED. String. The Issuer Identifier of the OpenID Provider that authenticated the End-User, as given by the iss claim of the ID Token. This is a URL using the https scheme with no query or fragment component, as specified in Section 2 of . This member corresponds to the IdentityProvider attribute of SACI.

auth_time:

Number. The time at which the End-User authentication occurred, as given by the auth_time claim of the ID Token. The value is a NumericDate as defined in Section 2 of : the number of seconds from 1970-01-01T00:00:00Z UTC until the time of authentication, ignoring leap seconds, expressed as a JSON number. This member corresponds to the AuthenticationInstant attribute of SACI.

acr:

String. The Authentication Context Class Reference of the authentication, as given by the acr claim of the ID Token. This member corresponds to the AuthnContextClassRef attribute of SACI.

amr:

Array of strings. The Authentication Methods References of the authentication, as given by the amr claim of the ID Token. Values are as registered in the "Authentication Method Reference Values" registry established by , or values defined by agreement between the OP and the RP. The array MUST contain at least one element when present. This member has no counterpart in SACI. See for the relationship between this member and acr.

jti:

String. A unique identifier of the ID Token, as given by the jti claim of the ID Token. This member corresponds to the AssertionRef attribute of SACI. Note that jti is OPTIONAL in an ID Token.

sub:

String. The Subject Identifier of the End-User at the OpenID Provider, as given by the sub claim of the ID Token. Together with iss, client_id and auth_time, this member allows the authentication event to be located in the records of the OpenID Provider, which is of particular use when the ID Token carried no jti claim. The value is opaque to the CA and to relying parties, and may be a pairwise identifier that is specific to the client_id. This member has no counterpart in SACI. See for considerations on including this member.

client_id:

String. The OAuth 2.0 client identifier under which the CA acted as Relying Party towards the OpenID Provider. This value appears as an audience of the ID Token (the aud claim). This member corresponds to the ServiceID attribute of SACI.

claim_mappings:

Array of objects. Each object describes how one claim about the End-User, obtained from the ID Token or from the UserInfo Response, was used to populate a subject name attribute in the certificate. The structure of each object is defined in . This member corresponds to the IdAttributes element of SACI. The array MUST contain at least one element when present.

Claim Mapping A claim mapping object records that the value of a certificate subject name attribute was derived from an End-User claim. In contrast to SACI, the claim value itself is not repeated in the mapping; the value is present in the certificate attribute to which the mapping refers. Each claim mapping object contains the following members:

type:

REQUIRED. String. One of the values rdn, san or sda, with the meaning defined for the Type attribute in Section 3.1.2 of :

• rdn - an attribute in a Relative Distinguished Name of the certificate subject field.
• san - a name in the Subject Alternative Name extension.
• sda - an attribute in the Subject Directory Attributes extension.

ref:

REQUIRED. String. Identifies the certificate attribute or name form, with the same content rules as the Ref attribute in Section 3.1.2 of :

• For type rdn and sda, the object identifier of the attribute type, in dotted-decimal notation (a sequence of decimal integers separated by periods, with no other characters).
• For type san, the decimal tag number of the GeneralName choice, e.g. 1 for rfc822Name and 2 for dNSName. For the otherName choice, the object identifier of the type-id in dotted-decimal notation.

claim:

REQUIRED. String. A JSON Pointer identifying the claim within the set of claims about the End-User, where the root of the pointer is the ID Token claims set (or the UserInfo Response, see source). For a standard top-level claim this is simply / followed by the claim name, e.g. /given_name. The pointer form allows reference to members of structured claims, e.g. /address/street_address, and to claims in aggregated or distributed claim sets.

source:

String. Indicates where the claim was obtained. The value id_token indicates the ID Token; the value userinfo indicates the UserInfo Response. When absent, the default value is id_token.

A single certificate attribute MAY be derived from more than one claim, in which case several claim mapping objects share the same type and ref values. A single claim MAY be mapped to more than one certificate attribute. shows a set of claim mappings for a typical certificate subject.

Schema The following schema, expressed in YAML using the vocabulary of , is a normative statement of the structure defined in and . In case of conflict between the prose and the schema, the prose takes precedence. Unrecognized members are permitted everywhere; the schema intentionally does not set additionalProperties to false.

Relationship to the ID Token and UserInfo Response The OACI object is produced by the CA from an ID Token, and where applicable a UserInfo Response, that the CA has validated according to Sections 3.1.3.7 and 5.3.4 of . The OACI object is not itself a token: it carries no signature and no exp or iat members, because its integrity and lifetime are those of the certificate in which it is embedded. A relying party that wishes to inspect the original ID Token may use the iss, client_id and jti members to locate it, if the CA retains tokens according to its practices.

Updates to RFC 7773

Processing of Unsupported Context Types Section 2 of states that an application that finds an authentication context information type it does not understand MUST ignore it if the extension is non-critical and MUST reject the certificate if the extension is marked critical. This rule conflates two separate matters: whether an application recognizes the Authentication Context extension, which is what the criticality flag of governs, and how an application that does recognize the extension treats individual AuthenticationContext entries. The information carried by the extension is descriptive. It allows a relying party that cares about the origin of the subject's identity to evaluate it against its own policy, but it requires no action from a relying party that does not. Requiring every relying party to support every context type present in a certificate therefore serves no security purpose, and it prevents a CA from including several context types in one certificate, for example to serve both legacy applications and new applications that support different versions of the same information. Accordingly, the rule is replaced by the following. An application that recognizes the Authentication Context extension MUST be able to parse the AuthenticationContexts structure. It processes each AuthenticationContext entry whose contextType it supports according to the specification of that context type, and MUST ignore each AuthenticationContext entry whose contextType it does not support. This applies irrespective of whether the extension is marked critical. The criticality flag of the extension retains only its meaning under Section 4.2 of : an application that does not recognize the Authentication Context extension at all MUST reject a certificate in which the extension is marked critical.

Criticality Section 2 of states that the extension MAY be marked critical. Since the extension carries descriptive information and mandates no action by a relying party, marking it critical excludes relying parties that do not implement the extension without providing any corresponding benefit. This document updates as follows: the Authentication Context extension SHOULD NOT be marked critical.

Security Considerations The security considerations of apply.

Trust in the Recorded Information The information in an OACI object is asserted by the CA, not by the OpenID Provider. The CA, or an RA acting on its behalf, copies values from an ID Token and UserInfo Response that it validated at the time of issuance; a relying party has no means of re-validating these from the certificate alone. A relying party therefore trusts the OACI content to exactly the extent that it trusts the CA, as expressed in the CA's certificate policy and practices. Where an RA performs the authentication, the CA's trust in the RA, and the means by which the authentication information is conveyed from the RA to the CA, are matters for the CA's practices and are outside the scope of this document.

Authentication Context Class References The value of the acr member is only meaningful within the trust framework that defines it. A relying party MUST NOT infer an assurance level from an acr value defined by a framework it does not recognize.

Authentication Methods References The amr member is informative. As noted in Section 4 of , amr values are asserted by the OP without any standardized means of verification and are not a substitute for an authentication context class. The member is provided so that the concrete methods used can be recorded for audit and troubleshooting, and because amr values, unlike acr values, are drawn from a public registry and remain interpretable outside the originating trust framework. The acr and amr members are complementary, not alternatives: acr is the OP's statement of the assurance achieved, and amr describes the methods used to achieve it. When both are present, acr governs. A relying party MUST NOT use amr values to raise or lower the assurance it attributes to the acr value, and SHOULD NOT base an assurance decision solely on amr values when acr is absent. An apparent inconsistency between the two, for example an acr value denoting a high assurance level together with amr values denoting a single weak factor, is a matter between the OP and the trust framework that governs it, and is not resolved by the relying party.

Privacy An OACI object reveals the identity of the OP that authenticated the subject, the time of authentication and, through claim_mappings, which identity attributes in the certificate were asserted by that OP. Together with the certificate serial number and jti, this allows a certificate to be correlated with an authentication event logged at the OP and the CA. CAs SHOULD include only members needed by the intended relying parties, and deployment profiles SHOULD consider whether jti and auth_time are required. The sub member is a persistent identifier of the End-User at the OpenID Provider. When the OpenID Provider issues pairwise Subject Identifiers (see Section 8 of ), the value is specific to the client_id and cannot be used to correlate the End-User across Relying Parties. When the OpenID Provider issues public Subject Identifiers, the value is the same for every Relying Party of that OpenID Provider, and including it in a certificate allows anyone holding the certificate to correlate its subject with the End-User's accounts at other Relying Parties of the same OpenID Provider. A CA SHOULD include sub only where the ability to locate the authentication record is needed by the intended relying parties, and deployment profiles SHOULD state whether sub is included and under which Subject Identifier type. Beyond sub, this document defines no member carrying End-User claim values. The claim values that were placed in the certificate are present in the certificate subject name; repeating them would increase the personal data carried by the certificate without adding information a relying party can verify.

Ignoring Unsupported Context Types Under , an application silently ignores context types it does not support. A relying party whose policy requires authentication context information of a particular type must therefore check for the presence of that type explicitly and treat its absence according to policy; the absence of a supported entry is not an error condition in itself.

IANA Considerations

X.509 Authentication Context Types Registry IANA is requested to create a new registry titled "X.509 Authentication Context Types" under a new "X.509 Authentication Context" registry group. The registry lists the URIs defined for use as contextType values in the Authentication Context certificate extension , together with the specification that defines the syntax of the corresponding contextInfo. The registration policy is Specification Required (see ). Each entry contains:

• Context Type URI: the URI used as the contextType value.
• Description: a short description of the context information type.
• Reference: the specification defining the contextInfo syntax.

Context type URIs are not required to be assigned under the Uniform Resource Name (URN) sub-namespace registered in ; any URI under the control of the registrant is acceptable. Registrations under the URN sub-namespace are expected to be made by IETF documents. The initial content of the registry is: Initial registry content

Context Type URI	Description	Reference
http://id.elegnamnden.se/auth-cont/1.0/saci	SAML Authentication Context Information	, Section 3
urn:ietf:params:x509-auth-context:oidc	OpenID Connect Authentication Context Information	This document,

IETF URN Sub-namespace Registration IANA is requested to register the following entry in the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry established by :

Registry name:

x509-auth-context

Specification:

This document.

Repository:

The "X.509 Authentication Context Types" registry ().

Index value:

The index value is the string following the prefix urn:ietf:params:x509-auth-context:. Values are registered as complete URIs in the "X.509 Authentication Context Types" registry; the entries of that registry beginning with the prefix constitute the values of this sub-namespace.

References Normative References This document describes a new sub-delegation for the 'ietf' URN namespace for registered protocol items. The 'ietf' URN namespace is defined in RFC 2648 as a root for persistent URIs that refer to IETF- defined resources. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. I-JSON (short for "Internet JSON") is a restricted profile of JSON designed to maximize interoperability and increase confidence that software can process it successfully with predictable results. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This document defines an extension to X.509 certificates. The extension defined in this document holds data about how the certificate subject was authenticated by the Certification Authority that issued the certificate in which this extension appears. This document also defines one data structure for inclusion in this extension. The data structure is designed to hold information when the subject is authenticated using a Security Assertion Markup Language (SAML) assertion. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Informative References The "amr" (Authentication Methods References) claim is defined and registered in the IANA "JSON Web Token Claims" registry, but no standard Authentication Method Reference values are currently defined. This specification establishes a registry for Authentication Method Reference values and defines an initial set of Authentication Method Reference values.

Examples

Example OACI Object The following OACI object records an authentication performed by the OpenID Provider https://op.example.com at a context class defined by an example trust framework. The certificate subject name contains the End-User's given name (object identifier (OID) 2.5.4.42), surname (OID 2.5.4.4) and serial number (OID 2.5.4.5), and an email address in the Subject Alternative Name extension, all derived from ID Token claims. Note that the third mapping refers to a claim whose name is itself a URI. Since / is the reference token separator in a JSON Pointer, the / characters inside the claim name are escaped as ~1 (see Section 3 of ). [[ Editor's note: claims with URI names are common in national profiles and the escaping makes them hard to read. Consider instead a plain claim name in claim with a separate OPTIONAL path member (a JSON Pointer relative to the claim) for members of structured claims. ]]

Example Extension The AuthenticationContext carrying the above object has contextType set to urn:ietf:params:x509-auth-context:oidc and contextInfo set to the compact serialization of the object. A Distinguished Encoding Rules (DER) rendering of the complete extension will be added in a future revision.

Design Notes [[ This section is intended to be removed before publication as an RFC. ]]

• Member names and value formats follow the ID Token claims where there is a direct correspondence (iss, auth_time, acr, amr, jti), so that a CA copies values without conversion, but the structure is not a JWT claims set and is not intended to be processed as one.
• Claim values are not repeated in claim_mappings, unlike SACI, because they are already present in the certificate and repeating them has not proven useful in practice.
• The update to RFC 7773 in is the reason this document carries "Updates: 7773". Without it, defining a new context type would not update RFC 7773, which already provides for additional types.

Acknowledgments TODO acknowledge.