Request (Regular-device Flow)

The request contains scope, response_type and client_id as query string parameters for backward compatibility with the OAuth2 specification [[!RFC6749]]. response_type MUST be id_token and client_id MUST specify the callback URL of the RP (as per [[!OIDC.Core]]). All other OIDC request parameters MUST be provided in an Request Object as per [[!OIDC.Core]] which is encoded as a JWT. This enables the RP to authenticate against the SIOP using the RP's DID. The Request Object can be passed by value in the request request parameter, or by reference using the request_uri parameter.

The Request Object follows the OIDC specification, e.g., adding nonce, state, response_type, and client_id parameters.

This specification introduces additional rules for request parameters and claims in the Request Object:

• REQUIRED. iss MUST contain the DID of the RP that can be resolved to a DID Document. The DID Document MUST contain a verification method in the authentication section, e.g., public key, that allows the SIOP to verify the Request Object.

By default, the iss claim refers to the client_id but SIOP assumes that client_id is the callback URL of the RP. That is the reason why the DID is not encoded in the client_id. It is compliant with the OIDC specification to use different values for iss and client_id.

• REQUIRED. kid MUST be a DID URL referring to a verification method in the authentication section in the RP's DID Document, e.g., did:example:0xab#key1. The SIOP MUST be able to use that verification method to verify the Request Object directly or indirectly. Additionally, the referred JWKS in the registration parameter MUST contain an entry with the same kid.
• REQUIRED. scope MUST include did_authn to indicate the SIOP DID profile is used.
• REQUIRED. registration MUST be included in the Request Object
• REQUIRED. client_id MUST be repeated in the Request Object
• OPTIONAL. did_doc MUST contain the DID Document that corresponds to the DID in the iss claim.
• OPTIONAL. response_mode specifies how the response is returned to the callback URL by the SIOP. SIOP implementing this specification MAY set the response_mode to form_post. fragment is the default Response Mode. RPs MUST take into consideration the platform of the User-Agent when specifying this request parameter.

See OAuth 2.0 Form Post Response Mode [[?OAuth2.FormPost]] and OAuth 2.0 Multiple Response Type Encoding Practices [[?OAuth2.ResponseTypes]] for more information about response_mode.

The following is a non-normative example of the JWT header of a Request Object:

                {
                   "alg": "ES256K",
                   "typ": "JWT",
                   "kid": "did:example:0xab#veri-key1"
                }
            

The following is a non-normative example of the JWT payload of a Request Object without requesting <SIOP DID Response> encryption:

                {
                    "iss": "did:example:0xab",
                    "response_type": "id_token",
                    "client_id": "https://my.rp.com/cb",
                    "scope": "openid did_authn",
                    "state": "af0ifjsldkj",
                    "nonce": "n-0S6_WzA2Mj",
                    "response_mode" : "form_post",
                    "registration" : {
                        "jwks_uri" : "https://uniresolver.io/1.0/identifiers/did:example:0xab;transform-keys=jwks",
                        "id_token_signed_response_alg" : [ "ES256K", "EdDSA", "RS256" ]
                    }
                }
            

The following is a non-normative example HTTP 302 redirect response by the RP, which triggers the User-Agent to make an SIOP DID Authentication Request using Request Object by value to the SIOP (with line wraps within values for display purposes only):

                HTTP/1.1 302 Found
                Location: openid://?
                    &client_id=https%3A%2F%2Frp.example.com%2Fcb
                    &scope=openid%20did_authn
                    &request=<JWT>
            

The following is a non-normative example HTTP 302 redirect response by the RP, which triggers the User-Agent to make an SIOP DID Authentication Request using Request Object by reference to the SIOP (with line wraps within values for display purposes only):

                HTTP/1.1 302 Found
                Location: openid://?
                    response_type=id_token
                    &client_id=https%3A%2F%2Frp.example.com%2Fcb
                    &scope=openid%20did_authn
                    &request_uri=https%3A%2F%2Frp.example.com%2F90ce0b8a-a910-4dd0
            

Request Validation (Regular-device Flow)

The SIOP MUST validate the <SIOP DID Request> by following the Self-Issued ID Token Validation rules as per [[!OIDC.Core]].

The step described above ensures that the Request Object is verified according to the OIDC specification. This includes basic JWS verification.

If scope contains the did_authn scope, the receiving SIOP MUST further validate the <SIOP DID Request> as follows in no particular order:

• If no did_doc is present, resolve the DID Document from the RP's DID specified in the iss request parameter.
• If did_doc is present, ensure this is a viable channel to exchange the RP's DID Document according to the applicable DID method.
• If jwks_uri is present, ensure that the DID in the jwks_uri matches the DID in the iss claim.
• Determine the verification method from the RP's DID Document that matches the kid of the <SIOP DID Request>.
• Verify the <SIOP DID Request> according to the verification method above. This step depends on the verification method in the authentication section in the DID Document and is out-of-scope of this specification.

If the key pair that signed the <SIOP DID Request> refers to the same key as indicated by the verification method, then no additional verification has to be done as the SIOP validation will verify the signature of the JWS.

Response (Regular-device Flow)

The SIOP MUST generate and send the <SIOP DID Response> to the RP as described in the Self-Issued OpenID Provider Response section in [[!OIDC.Core]]. The id_token represents the <SIOP DID Response> encoded as a JWS, or nested JWS/JWE.

This specification introduces additional rules for claims in the id_token:

• REQUIRED. sub_jwk MUST contain a kid that is a DID URL referring to the verification method in the SIOP's DID Document that can be used to verify the JWS of the id_token directly or indirectly.
• REQUIRED. did MUST be the SIOP's DID.
• OPTIONAL. did_doc MUST be the SIOP's DID Document corresponding to did in JSON encoding.

The sub_jwk claim has to be provided for backward compatibility reasons. The verification method in the DID Document can be different from a public key and can use a publicKey property value other than publicKeyJwk.

The following is a non-normative example of the JWT header of an id_token using no encryption:

                {
                    "alg": "ES256K",
                    "typ": "JWT",
                    "kid": "did:example:0xab#key-1"
                }
            

The following is a non-normative example of the unencrypted JWT payload of an id_token:

                {
                   "iss": "https://self-issued.me",
                   "nonce": "n-0S6_WzA2Mj",
                   "exp": 1311281970,
                   "iat": 1311280970,
                   "sub_jwk" : {
                      "crv":"secp256k1",
                      "kid":"did:example:0xcd#verikey-1",
                      "kty":"EC",
                      "x":"7KEKZa5xJPh7WVqHJyUpb2MgEe3nA8Rk7eUlXsmBl-M",
                      "y":"3zIgl_ml4RhapyEm5J7lvU-4f5jiBvZr4KgxUjEhl9o"
                   },
                   "sub": "9-aYUQ7mgL2SWQ_LNTeVN2rtw7xFP-3Y2EO9WV22cF0",
                   "did": "did:example:0xcd"
                }
            

Response Validation (Regular-device Flow)

The RP MUST validate the <SIOP DID Response> as described in the Self-Issued ID Token Validation section in [[!OIDC.Core]]. This includes:

• Optionally decrypting the JWE to obtain the JWS which contains the id_token.
• Verifying that the id_token was signed by the key specified in the sub_jwk claim.

Additionally, the RP MUST validate the id_token against the SIOP's DID Document as follows:

• If no did_doc is present, resolve the DID Document from the SIOP's DID specified in the did claim.
• If did_doc is present, ensure this is a viable channel to exchange the SIOP's DID Document according to the applicable DID method.
• Determine the verification method from the SIOP's DID Document that matches the kid of the sub_jwk claim in the id_token.
• Verify the id_token according to the verification method above. This step depends on the verification method in the authentication section in the DID Document and is out-of-scope of this specification.

If the key pair that signed the id_token refers to the same key as indicated by the verification method, then no additional verification has to be done as the SIOP validation will verify the signature of the JWS.

Request (Multi-device Flow)

The RP MUST follow the rules in Request (Regular Flow) to generate the <SIOP DID Request>.

Additionally, the Request Object in the <SIOP DID Request> MUST contain the following parameters:

• REQUIRED. verification_uri MUST contain the verification URI that points to an endpoint on the RP to check whether the user has repeated the user_code. The presence of verification_uri also indicates the Multi-device flow is requested. The details of the interface is described in Device Binding.
• REQUIRED. device_code MUST contain the device verification code. The RP SHOULD use the device_code to authorize the <Device Binding Requests> from the SIOP. As the device_code is not displayed to the user and thus there are no usability considerations on the length, a very high entropy code SHOULD be used.
• REQUIRED. expires_in MUST contain the lifetime in seconds of the device_code after when the SIOP MUST stop polling requests to the verification URI.
• OPTIONAL. interval MUST contain the minimum amount of time in seconds that the client SHOULD wait between polling requests to the verification URI. If no value is provided, clients MUST use 5 as the default.

See Device Binding for more details on the usage of verification_uri, device_code, expires_in and interval.

Request Validation (Multi-device Flow)

The SIOP MUST follow the rules in Request Validation (Regular Flow) to validate the <SIOP DID Request>.

Additionally, the following validation rules MUST be applied:

• If no verification_uri is present, then continue with the Regular-device Flow.
• If verification_uri is present, then Device Binding has to be performed before the <SIOP DID Response> is sent to the RP.

Device Binding (Multi-device Flow)

The SIOP extracts the parameters from the <SIOP DID Request> that were described in Request (Multi-device Flow).

Then, the SIOP generates a user_code. The user_code is typed by the user. For this reason, shorter codes are more desirable for usability reasons. This means the entropy is typically less than would be used for the device_code where the code length does not impact usability. Therefore, it is RECOMMENDED that the server rate-limit user_code attempts. The user_code SHOULD have enough entropy that, when combined with rate-limiting and other mitigations, a brute-force attack becomes infeasible.

The SIOP SHOULD then continuously poll the verification_uri endpoint with the device_code and user_code as detailed in Device Binding Request and Device Binding Response, until the user completes the interaction, the user_code or device_code expires, or another error occurs.

RPs supporting this specification MUST implement a user interaction sequence that allows users to supply the user_code at some stage during the interaction. Other than that, the exact sequence and implementation of the user interaction is up to the RP.

Device Binding Request

The SIOP sends the <Device Binding Request> to the verification URI. Between polling requests to the verification URI, the SIOP considers the device binding parameters enclosed in the <SIOP DID Request> which are detailed in Request (Multi-device Flow).

All requests from the SIOP MUST use the Transport Layer Security (TLS) protocol [[RFC8446]] and implement the best practices of BCP 195 [[RFC7525]].

The verification URI endpoint MUST support HTTP POST and MUST accept the <Device Binding Request> provided as a JSON object with Content-Type of the HTTP request set to application/json.

The <Device Binding Request> MUST contain the following parameters:

• REQUIRED. device_code MUST contain the device verification code as described in Request (Multi-device Flow).
• REQUIRED. user_code MUST contain the user code as described in Device Binding.
• REQUIRED. expires_in MUST contain the expiration date of the user_code in seconds, after when RPs MUST reject the <Device Binding Request>.

Parameters sent without a value MUST be treated as if they were omitted from the request. The RP MUST ignore unrecognized request parameters. Request and response parameters MUST NOT be included more than once.

For example, the SIOP makes the following HTTPS request:

                POST /device_verification HTTP/1.1
                Host: server.example.com
                Content-Type: application/json

                {
                  "device_code" : "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
                  "user_code" : "WDJB-MJHT",
                  "expires_in" : 1800
                }
            

Device Binding Response

If the user has repeated the user_code for the device_code on time, the verification URI endpoint MUST respond with a success response with a 200 (OK) status code in case the Device Binding was successful; otherwise, it MUST respond with an error response, as defined in Section 5.2 of [[RFC6749]]. Instead of the error codes defined in Section 5.2 of [[RFC6749]], the following error codes are specified for use with the Device Binding:

• authorization_pending: The RP request is still pending as the end user hasn't yet completed the user-interaction steps. The SIOP SHOULD repeat the request to the verification URI endpoint (a process known as polling). Before each new request, the SIOP MUST wait at least the number of seconds specified by the interval parameter of the <SIOP DID Request>, or 5 seconds if none was provided, and respect any increase in the polling interval required by the slow_down error.
• slow_down: A variant of authorization_pending, the <Device Binding Request> is still pending and polling should continue, but the interval MUST be increased by 5 seconds for this and all subsequent requests.
• expired_token: The device_code has expired and the device binding session has concluded. The SIOP SHOULD stop polling and send the <SIOP DID Response>.
• access_denied: The end user denied the request and the SIOP SHOULD stop polling and send the <SIOP DID Response>.

The authorization_pending and slow_down error codes define particularly unique behavior, as they indicate that the SIOP should continue to poll the verification URI by repeating the <Device Binding Request> (implementing the precise behavior defined above). If the SIOP receives an error response with any other error code, it MUST stop polling and SHOULD react accordingly, for example, by displaying an error to the user.

On encountering a connection timeout, SIOPs MUST unilaterally reduce their polling frequency before retrying. The use of an exponential backoff algorithm to achieve this, such as by doubling the polling interval on each such connection timeout, is RECOMMENDED.

The assumption of this specification is that the RP does not have a way to communicate back to the SIOP. This protocol only requires a one-way channel in order to maximise the viability of the protocol in restricted environments, like a SIOP on a mobile phone that is only capable of outbound requests. If a return channel were to exist for the chosen user interaction interface, then the SIOP MAY wait until notified on that channel that the user has completed the action before sending the <SIOP DID Response> (as an alternative to polling). Such behavior is, however, outside the scope of this specification.

For example, the RP responds the following HTTPS response in case the request was successful:

                HTTP/1.1 200 OK
                Cache-Control: no-store
                Pragma: no-cache
            

For example, the RP responds the following HTTPS response in case of an error:

                HTTP/1.1 400 Bad Request
                Content-Type: application/json;charset=UTF-8
                Cache-Control: no-store
                Pragma: no-cache

                {
                  "error" : "invalid_request",
                  "error_description" : "Some error description"
                }
            

Response (Multi-device Flow)

The SIOP MUST perform Device Binding. Then, the SIOP MUST follow the rules in Response (Regular Flow) to generate the <SIOP DID Response>.

Response Validation (Multi-device Flow)

The RP MUST follow the rules in Response Validation (Regular Flow) to validate the <SIOP DID Response>. Additionally, RPs implementing this specification MUST reject the <SIOP DID Response> without prior successful Device Binding.