International Government Assurance Profile (iGov) for OpenID Connect 1.0 - draft 04

2.2. Requests to the Token Endpoint

In addition to the requirements specified in Section 2.1.2 of the iGov OAuth2 profile [iGov.OAuth2] , the following claims MUST be included:¶

The following parameters are specified:¶

grant_type

MUST be set to authorization_code .¶

code

The value of the code parameter returned in the authorization response.¶

client_assertion_type

MUST be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer .¶

client_assertion

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.¶

3.2. Pairwise Identifiers

Pairwise identifiers specified in OpenID Connect Core [OpenID.Core] section 8 help protect an end user's privacy by allowing an OpenID Provider to represent a single user with a different subject identifier (sub) for every client the user connects to. This technique can help mitigate correlation of a user between multiple clients by preventing the clients from using the subject identifier (the sub claim) to track a user between different sites and applications. Use of pairwise identifiers does not prevent clients from correlating data based on other identifying attributes such as names, phone numbers, email addresses, document numbers, or other attributes. However, since not all transactions require access to these attributes, but a subject identifier is always required, a pairwise identifier will aid in protecting the privacy of end users as they navigate the system.¶

OpenID Providers MUST support pairwise identifiers for cases where clients require this functionality. OpenID Providers MAY support public identifiers for frameworks where public identifiers are required, or for cases where public identifiers are shared as attributes and the framework does not have a requirement for subject anonymity.¶

3.3. UserInfo Endpoint

OpenID Providers 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:¶

GET /userinfo HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTg3MDI0MTIsIm
F1ZCI6WyJjMWJjODRlNC00N2VlLTRiNjQtYmI1Mi01Y2RhNmM4MWY3ODgiXSwiaXNzIjo
iaHR0cHM6XC9cL2lkcC1wLmV4YW1wbGUuY29tXC8iLCJqdGkiOiJkM2Y3YjQ4Zi1iYzgx
LTQwZWMtYTE0MC05NzRhZjc0YzRkZTMiLCJpYXQiOjE0MTg2OTg4MTJ9i.HMz_tzZ90_b
0QZS-AXtQtvclZ7M4uDAs1WxCFxpgBfBanolW37X8h1ECrUJexbXMD6rrj_uuWEqPD738
oWRo0rOnoKJAgbF1GhXPAYnN5pZRygWSD1a6RcmN85SxUig0H0e7drmdmRkPQgbl2wMhu
-6h2Oqw-ize4dKmykN9UX_2drXrooSxpRZqFVYX8PkCvCCBuFy2O-HPRov_SwtJMk5qjU
WMyn2I4Nu2s-R20aCA-7T5dunr0iWCkLQnVnaXMfA22RlRiU87nl21zappYb1_EHF9ePy
q3Q353cDUY7vje8m2kKXYTgc_bUAYuW-W3SMSw5UlKaHtSZ6PQICoA
Accept: text/plain, application/json, application/*+json, */*
Host: idp-p.example.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.2.3 (java 1.5)

And receives a document in response like the following:¶

HTTP/1.1 200 OK
Date: Tue, 16 Dec 2014 03:00:12 GMT
Access-Control-Allow-Origin: *
Content-Type: application/json;charset=ISO-8859-1
Content-Language: en-US
Content-Length: 333
Connection: close

{
   "sub": "6WZQPpnQxV",
   "iss": "https://idp-p.example.com"
   "given_name": "Stephen",
   "family_name": "Emeritus",
}

OpenID Providers MUST support the generation of JWT [RFC7519] 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 [RFC7518]) specification.¶

3.4. Request Objects

OpenID Providers 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. OpenID Connect Providers MUST accept request objects encrypted with the server's public key.¶

OpenID Providers 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 OpenID Providers are required to support requests using them.¶

3.5. Vectors of Trust

If the vtr (Vectors of Trust Request) value is present in the authorization request as defined in the Vectors of Trust [RFC8485] standard, the OpenID Provider SHOULD respond with a valid vot value as defined in [section 3.1]. Both the vtr and vot MUST contain values in accordance with the Vectors of Trust [RFC8485] standard. These values MAY be those defined in the Vectors of Trust [RFC8485] standard directly or MAY be from a compatible standard. The OpenID Provider MAY require the user to re-authenticate, provide a second factor, or perform another action in order to fulfill the state requested in the vtr.¶

For backwards compatibility clients MAY send an acr_values parameter. If both the vtr and acr_values are in the request, the vtr MUST take precedence and the acr_values MUST be ignored.¶

It is out of scope of this document to determine how an organization maps their digital identity practices to valid VOT component values.¶

3.6. Authentication Context

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 only if vtr is not used.¶

3.7. Discovery

OpenID Connect Discovery standard [OpenID.Discovery] provides a standard, programatic way for clients to obtain configuration details for communicating with OpenID Providers. Discovery is an important part of building scalable federation ecosystsems.¶

Exposing a Discovery endpoint does NOT inherently put the OpenID Provider at risk to attack. Endpoints and parameters specified in the Discovery document SHOULD be considered public information regardless of the existence of the Discovery 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 Providers 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 [OpenID.Discovery]. The discovery document MUST contain at minimum the following fields:¶

issuer

REQUIRED. The fully qualified issuer URL of the OpenID Provider.¶

authorization_endpoint

REQUIRED. The fully qualified URL of the OpenID Provider's authorization endpoint defined by [RFC6749].¶

token_endpoint

REQUIRED. The fully qualified URL of the server's token endpoint defined by [RFC6749].¶

introspection_endpoint

OPTIONAL. The fully qualified URL of the server's introspection endpoint defined by OAuth Token Introspection [RFC7662].¶

revocation_endpoint

OPTIONAL. The fully qualified URL of the server's revocation endpoint defined by OAuth Token Revocation [RFC7009].¶

jwks_uri

REQUIRED. The fully qualified URI of the server's public key in JWK Set [RFC7517] format. For verifying the signatures on the id_token.¶

scopes_supported

REQUIRED. The list of scopes, including iGov scopes, the server supports.¶

claims_supported

REQUIRED. The list of claims available in the supported scopes. See below.¶

vot

OPTIONAL. The vectors supported.¶

acr_values_supported

OPTIONAL. The acrs supported.¶

The following example shows the JSON document found at a discovery endpoint for an authorization server:¶

{
  "issuer": "https://idp-p.example.com/",
  "registration_endpoint": "https://idp-p.example.com/register",
  "require_request_uri_registration": false,
  "request_parameter_supported": true,
  "request_uri_parameter_supported": false,
  "request_object_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512",
    "A128CBC+HS256", "A256CBC-HS512",
    "A128CBC-HS256", "A128GCM", "A256GCM"
  ],
  "request_object_signing_alg_values_supported": [
    "RS256", "RS384", "RS512"
  ],
  "claims_parameter_supported": true,
  "claim_types_supported": [
    "normal"
  ],
  "grant_types_supported": [
    "authorization_code",
  ],
  "scopes_supported": [
    "profile", "openid", "doc"
  ],
  "code_challenge_methods_supported":["S256"],
  "authorization_endpoint": "https://idp-p.example.com/authorize",
  "request_object_encryption_alg_values_supported": [
    "RSA-OAEP", "RSA-OAEP-256"
  ],
  "response_types_supported": [
    "code"
  ],
  "subject_types_supported": [
    "public", "pairwise"
  ],
  "token_endpoint": "https://idp-p.example.com/token",
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "RS256", "RS384", "RS512"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256", "RS384", "RS512"
  ],
  "id_token_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512",
    "A128CBC+HS256", "A256CBC-HS512", "A128CBC-HS256",
    "A128GCM", "A256GCM"
  ],
  "id_token_encryption_alg_values_supported": [
    "RSA-OAEP", "RSA-OAEP-256"
  ],
  "userinfo_endpoint": "https://idp-p.example.com/userinfo",
  "userinfo_signing_alg_values_supported": ["RS256"],
  "userinfo_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512","A128CBC+HS256",
    "A256CBC-HS512", "A128CBC-HS256", "A128GCM", "A256GCM"
  ],
  "userinfo_encryption_alg_values_supported": [
    "RSA-OAEP", "RSA-OAEP-256"
  ],
  "userinfo_signing_alg_values_supported": [
    "RS256", "RS384", "RS512"
  ],
  "jwks_uri": "https://idp-p.example.com/jwks.jose",
  "introspection_endpoint": "https://idp-p.example.com/introspect",
  "revocation_endpoint": "https://idp-p.example.com/revoke",
  "introspection_endpoint": "https://idp-p.example.com/introspect",
  "op_tos_uri": "https://idp-p.example.com/about",
  "op_policy_uri": "https://idp-p.example.com/about",
  "service_documentation": "https://idp-p.example.com/about",
  "claims_supported": [
    "sub", "name", "vot", "acr"
  ],
  "acr_values_supported": ["gold", "silver", "bronze"],
}

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 [RFC7517] format, such as the following 2048-bit RSA key:¶

{
  "keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "n": "o80vbR0ZfMhjZWfqwPUGNkcIeUcweFyzB2S2T-hje83IOVct8gVg9Fx
            vHPK1ReEW3-p7-A8GNcLAuFP_8jPhiL6LyJC3F10aV9KPQFF-w6Eq6V
            tpEgYSfzvFegNiPtpMWd7C43EDwjQ-GrXMVCLrBYxZC-P1ShyxVBOze
            R_5MTC0JGiDTecr_2YT6o_3aE2SIJu4iNPgGh9MnyxdBo0Uf0TmrqEI
            abquXA1-V8iUihwfI8qjf3EujkYi7gXXelIo4_gipQYNjr4DBNl
            E0__RI0kDU-27mb6esswnP2WgHZQPsk779fTcNDBIcYgyLujlcUATEq
            fCaPDNp00J6AbY6w",
      "kty": "RSA",
      "kid": "rsa1"
    }
  ]
}

3.8. Dynamic Registration

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