mike.varley@securekey.com

pag3@nist.gov

OpenID iGov Working Group The OpenID Connect protocol defines an identity federation system that allows a relying party to request and receive authentication and profile information about an end user. This specification profiles the OpenID Connect protocol to increase baseline security, provide greater interoperability, and structure deployments in a manner specifically applicable to (but not limited to) government and public service domains. This profile builds on top of, and inherits all properties of, the OAUTH profile for iGov.

Government regulations for permitting users (citizens and non-citizens) online access to government resources vary greatly from region to region. There is a strong desire to leverage federated authentication and identity services for public access to government resources online to reduce 'password fatigue', increase overall account security, reduce cost, and provide reliable identity assurances from established and trusted sources when applicable. This specification aims to define an OpenID Connect profile that provides governments with a foundation for securing federated access to public services online.

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 . 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 specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 , the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT) , and the terms defined by OpenID Connect Core 1.0 .

This specification defines requirements for the following components: OpenID Connect 1.0 relying parties (also known as OpenID Clients) OpenID Connect 1.0 identity providers (also known as OpenID Providers) The specification also defines features for interaction between these components: Relying party to identity provider When an iGov-compliant component is interacting with other iGov-compliant components, in any valid combination, all components MUST fully conform to the features and requirements of this specification. All interaction with non-iGov components is outside the scope of this specification. An iGov-compliant OpenID Connect IdP MUST support all features as described in this specification. A general-purpose IdP MAY support additional features for use with non-iGov clients. An iGov-compliant OpenID Connect IdP MAY also provide iGov-compliant OAuth 2.0 authorization server functionality. In such cases, the authorization server MUST fully implement the OAuth 2.0 iGov profile. If an iGov-compliant OpenID Connect IdP does not provide iGov-compliant OAuth 2.0 authorization server services, all features related to interaction between the authorization server and protected resource are therefore OPTIONAL. An iGov-compliant OpenID Connect client MUST use all functions as described in this specification. A general-purpose client library MAY support additional features for use with non-iGov IdPs.

The iGov OAuth2 profile specifies requirements for requests to Authorization Endpoints - for example, when to use the PKCE parameters to secure token exchange. In addition to the requirements specified in Section 2.1.1 of the iGov OAuth2 profile, the following describes the supported OpenID Connect Authorization Code Flow parameters for use with iGov compatible IdPs. Request Parameters: REQUIRED. OAuth 2.0 Client Identifier valid at the Authorization Server. REQUIRED. MUST be set to code . REQUIRED. Indicates the attributes being requested. (See below) REQUIRED. Indicates a valid endpoint where the client will receive the authentication response. See (core section 3.1.2.1) REQUIRED. Unguessable random string generated by the RP, used to protect against CSRF attacks. Must contain a sufficient amount of entropy to avoid guessing. Returned to the RP in the authentication response. REQUIRED. This value must be set to select_account . REQUIRED. Unguessable random string generated by the client, used to protect against CSRF attacks. Must contain a sufficient amount of entropy to avoid guessing. Returned to the client in the ID Token. OPTIONAL. MUST be set to a value as described in Section 6.1 of Vectors of Trust vtr takes precedence over acr_values. OPTIONAL. Lists the acceptable LoAs for this authentication. See (below). MUST not be set if vtr is specified. OPTIONAL. If the PKCE protocol is being used by the client. See OAUTH profile for iGov. A sample request may look like:

In addition to the requirements specified in Section 2.1.2 of the iGov OAuth2 profile , the following claims MUST be included: The following parameters are specified: MUST be set to authorization_code . The value of the code parameter returned in the authorization response. MUST be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer . The value of the signed client authentication JWT generated as described below. The RP must generate a new assertion JWT for each call to the token endpoint.

All clients MUST validate the signature of an ID Token before accepting it using the public key of the issuing server, which is published in JSON Web Key (JWK) format. ID Tokens MAY be encrypted using the appropriate key of the requesting client. Clients MUST verify the following in received ID tokens: The "issuer" field is the Uniform Resource Locater (URL) of the expected issuer The "audience" field contains the client ID of the client The "expiration", "issued at", and "not before" timestamps for the token are dates (integer number of seconds since from 1970-01-01T00:00:00Z UTC) within acceptable ranges

Clients MAY optionally send requests to the authorization endpoint using the request parameter as defined by OpenID Connect . Clients MAY send requests to the authorization endpoint by reference using the request_uri parameter. Request objects MUST be signed by the client's registered key. Request objects MAY be encrypted to the authorization server's public key.

Clients and protected resources SHOULD cache OpenID provider metadata once an OP has been discovered and used by the client.

All ID Tokens MUST be signed by the OpenID Provider's private signature key. ID Tokens MAY be encrypted using the appropriate key of the requesting client. The ID Token MUST expire and SHOULD have an active lifetime no longer than five minutes. Since the ID token is consumed by the client and not presented to remote systems, much shorter expiration times are RECOMMENDED where possible. The token response includes an access token (which can be used to make a UserInfo request) and ID token (a signed and optionally encrypted JSON Web Token). ID Token values have the following meanings: REQUIRED. The "issuer" field is the Uniform Resource Locater (URL) of the expected issuer. REQUIRED. The "audience" field contains the client ID of the client. REQUIRED. The identifier of the user. SHOULD be a pairwize annonymous identifier, and be unique per client to prevent linkability and traceability between clients. OPTIONAL. The vector value as specified in Vectors of Trust . See Vectors of Trust for more details. vot takes precedence over acr. REQUIRED if vot is provided. The trustmark URI as specified in Vectors of Trust . See Vectors of Trust for more details. OPTIONAL. The LoA the user was authenticated at. MUST be a member of the acr_values list from the authentication request. The OP MUST NOT include if vot is provided. See Authentication Context for more details. The nonce value that was provided in the authentication request. MUST be Included if provided in authentication request. REQUIRED. A unique identifier for the token, which can be used to prevent reuse of the token. REQUIRED. The "expiration", "issued at", and "not before" timestamps for the token are dates (integer number of seconds since from 1970-01-01T00:00:00Z UTC) within acceptable ranges. This example ID token has been signed using the server's RSA key:

Its claims are as follows:

Servers MUST support the UserInfo Endpoint and, at a minimum, the sub (subject) claim. It is expected that the sub claim will remain pseudonymous in use cases where obtaining personal information is not needed. Support for a UserInfo Endpoint is important for maximum client implementation interoperability even if no additional user information is returned. Clients are not required to call the UserInfo Endpoint, but should not receive an error if they do. In an example transaction, the client sends a request to the UserInfo Endpoint like the following:

And receives a document in response like the following:

Servers MUST support the generation of JWT encoded responses from the UserInfo Endpoint in addition to unsigned JSON objects. Signed responses MUST be signed by the OpenID Provider's key, and encrypted responses MUST be encrypted with the authorized client's public key. The OpenID Provider MUST support the RS256 signature method (the Rivest, Shamir, and Adleman (RSA) signature algorithm with a 256-bit hash) and MAY use other asymmetric signature and encryption methods listed in the JSON Web Algorithms ( JWA ) specification.

Authorization servers MUST accept requests containing a request object signed by the client's private key. Servers MUST validate the signature on such requests against the client's registered public key. Servers MUST accept request objects encrypted with the server's public key. Servers MAY accept request objects by reference using the request_uri parameter. Both of these methods allow for clients to create a request that is protected from tampering through the browser, allowing for a higher security mode of operation for clients and applications that require it. Clients are not required to use request objects, but authorization servers are required to support requests using them.

Servers MUST check for the presence of the vtr parameter before acr in Requests. If both parameters are present the server will default to vtr as the request to respond to. acr MUST then be ignored. OpenID Providers MAY provide the vot and contain valid values from the Vectors of Trust standard. The vtr and contain valid values from the Vectors of Trust standard. It is out of scope of this document to determine how an organization maps their digital identity practices to valid VOT component values.

OpenID Providers MAY provide acr (authentication context class reference, equivalent to the Security Assertion Markup Language (SAML) element of the same name) and amr (authentication methods reference) values in ID tokens if vtr is not used.

OpenID Connect Discovery standard provides a standard, programatic way for Clients to obtain configuration details for communicating with Providers. Discovery is an important part of building scalable federation ecosystsems. Exposing a Discovery endpoint does NOT inherently put the Provider at risk to attack. Endpoints and parameters specified in the Discovery document SHOULD be considered public information regardless of the existence of the Doscovery document. Access to the Discovery document MAY be protected with existing web authentication methods if required by the Provider. Credentials for the Discovery document are then managed by the Provider. Support for these authentication methods is outside the scope of this specification. Endpoints described in the Discovery document MUST be secured in accordance with this specification and MAY have additonal controls the Provider wishes to support. All OpenID Connect servers are uniquely identified by a URL known as the issuer. This URL serves as the prefix of a service discovery endpoint as specified in the OpenID Connect Discovery standard . The discovery document MUST contain at minimum the following fields: The fully qualified issuer URL of the server The fully qualified URL of the server's authorization endpoint defined by The fully qualified URL of the server's token endpoint defined by The fully qualified URL of the server's introspection endpoint defined by OAuth Token Introspection The fully qualified URL of the server's revocation endpoint defined by OAuth Token Revocation The fully qualified URI of the server's public key in JWK Set format The list of iGov scopes the server supports The list of claims available in the supported scopes. See below The vectors supported. The following example shows the JSON document found at a discovery endpoint for an authorization server:

It is RECOMMENDED that servers provide cache information through HTTP headers and make the cache valid for at least one week. The server MUST provide its public key in JWK Set format, such as the following 2048-bit RSA key:

If the OP is acting as an iGov OAuth Authorization Server (iGov OAuth2 profile), then Dynamic Registration MUST be supported in accordance with that specification (see section 3.13).

The availability, quality, and reliability of an individual's identity attributes will vary greatly across jurisdictions and Provider systems. The following recommendations ensure maximum cross-jurisdictional interoperability, while setting Client expectations on the type of data they may acquire.

Discovery mandates the inclusion of the claims_supported field that defines the claims a client MAY expect to receive for the supported scopes. Servers MUST return claims on a best effort basis. However, a server asserting it can provide a user claim does not imply that this data is available for all its users: clients MUST be prepared to receive partial data. Servers MAY return claims outside of the claims_supported list, but they MUST still ensure that the extra claims to not violate the privacy policies set out by the federation.

In the interests of data minimization balanced with the requirement to successfully identify the individual signing in to a service, the default OpenID Connect profiles may not be appropriate. Matching of the identity assertion based on claims to a local identifier or ‘account’ related to the individual identity at a level of assurance is a requirement where the government in question is not able to provide a single identifier for all citizens based on an authoritative register of citizens. The requirement for matching is also of importance where a cross-border or cross-jurisdiction authentication is required and therefore the availability of a single identifier (e.g. social security number) cannot be guaranteed for the individual wishing to authenticate. This standard defines a set of common scope values that aim to provide maximum cross-jurisdictional identity matching while not being perscriptive on the exact attributes shared, as every jurisdiction will likely have varius levels of information available, and different policies for sharing personal data even if it is on file. The OpenID Connect Core defined profile provides baseline identity information. It is HIGHLY RECOMMENDED that the attributes for given_name, family_name, address, birthdate be supported by iGov Providers if possible, unless data quality requirements or privacy considerations prevent it. It is left to the Provider and the federation to set any further limitations on this profile data - see Privacy Considerations below. The identity document type(s) and associated "number" the Provider is capable of providing. Mutliple document types MAY be returned. This could be passport, driver's license, national ID card, health insurance no., and so on. The response should include: The document type. The value of the document identifier. Note that not all values are technically numeric. Biometric data related to the subject for physical verification at the Client side. This can include simple descriptions for eye and hair color, height, or may include a photograph: picture from OpenID Connect Core.

To support maximum interoperability and trust across (potentially) unassociated jurisdictions, the information regarding the claim type MUST be communicated within the protocol, so clients may properly interpret the claims they have been given. This is referred to as Claims Metadata. Claims Metadata is captured in a _claims_metadata member of the JSON object containing the Claims. As defined in OpenID Connect Core section 5.6.2. The list of claims that have metadata. A JSON Object containing the associated metadata for the claims listed in _claim_names. Metadata fields are defined below. The following defines the types of claims metadata that iGov supports: The locale format of the claim, indicating where the attribute originates from, represented as a space-separated list of BCP47 [RFC5646] language tag values: for example "en-US" or "ja" or "fr-CA" and so on. How the claim is encoded: raw, jwt.

In addition to the scope of the data provided, the UserInfo data must return some concept of the quality level of the attribute. This quality level is referred to as attribute meta data, and follows the guidelines in Vectors of Trust . The following must be considered when evaluating the quality of an attribute: The attribute Vector of Trust. The Trustmark Provider URL for the vot claim.

This example represents a request to a Department of Motor Vehicles (DMV) OP that is returning driver's license related information. The requested scope was profile, doc, bio. Only the driver's license related information is subject to this metadata: the email_address does not meet the same level of assurance.

This section covers recommendations and guidelines for protecting a user's right to privacy in circumstances where this is required. Government policies that protect an individual's right to privacy across jurisdictional boundires vary from geography to geography. Some geographies are looking to establish a global registry of basic citizen identity for digital use cases, and other geographies aim to supply only the bare minimum of an authentication assurances, ensuring participant systems cannot link or trace a citizen's actions across the federation. Most will fall somewhere in between these two extremes. This specification supports this wide range of scenarios and therefore the following are NOT REQUIRED by Providers to implement, but HIGHLY RECOMMENDED for Providers that implement some level of user privacy. sub fields MUST be "pairwise" as defined in OpenID Connect Core section 8.

All transactions MUST be protected in transit by TLS as described in BCP195 . All clients MUST conform to applicable recommendations found in the Security Considerations sections of and those found in the OAuth 2.0 Threat Model and Security Considerations document .

Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are widely used to protect data exchanged over application protocols such as HTTP, SMTP, IMAP, POP, SIP, and XMPP. Over the last few years, several serious attacks on TLS have emerged, including attacks on its most commonly used cipher suites and their modes of operation. This document provides recommendations for improving the security of deployed services that use TLS and DTLS. The recommendations are applicable to the majority of use cases. Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila

openid@justin.richer.org http://justin.richer.org/

openid@justin.richer.org http://justin.richer.org/

pag3@nist.gov

mike.varley@securekey.com

The OpenID Community would like to thank the following people for their contributions to this specification: Justin Ritcher, Paul Grassi, John Bradley, Adam Cooper, ...

Copyright (c) 2017 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.

-2017-05-29 -02 Removed Verifiable Claims definition (will go in another spec). Clarified Scope and Metadata. -2016-07-25 -01 Imported content from OpenID HEART 1.0 profile and Connect.Gov integration guide v 1.4