Difference between revisions of "Self-issued OpenID Picker"

From MgmtWiki
Jump to: navigation, search
(Full Title)
 
(103 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
==Full Title==
 
==Full Title==
Self-issued Identifiers in an OpenID Connect Context where there is a choice between providers..
+
Self-issued Identifiers in an OpenID Connect Context where there is a large choice among OpenID providers..
 +
 
 +
Also known as chooser or selector spec or as the Joint Authentication Management (JAM) specification or as a [[Vendor Relationship Manager]].
 +
 
 +
===Goals===
 +
# Allow users the choice of which identifier to use with a [[Relying Party]] in a world where thee number of options makes it hard for the [[Relying Party]] to list them all.
 +
# Allow users to easily navigate back to a [[Relying Party]] without having to remember their choice when they registered, which could easily be over a year in the past.
 +
 
 +
===Justification===
 +
There has never been much interest in [[User Experience]] among identifier standards developers. This wiki page attempts to address that. Some Commentary follows:
 +
* David Cahdwick<blockquote>I think the whole direction of this Picker is misguided because it assumes that users will be knowledgeable about their numerous identifiers and will want to manage them. I don't believe that users will want to choose identifiers or know anything about them. I believe that users are interested in their electronic credentials (the equivalent of today’s plastic cards) and the identities that go with these. Users typically don't care a jot about what identifier is being used to cryptographically link their identity attributes to an identifier: transient identifiers are the best at protecting the user’s privacy and the user won't have any idea what the identifier is in any particular transaction. So the user will not be choosing identifiers as this draft assumes.</blockquote>
 +
* Tom Jones<blockquote>I believe that there is a great deal of truth in David’s assertions about human’s desire for multiple identifier. The sad fact is i have ~100 of them today in spite of my desires to have none (they are typically called user names and each has their own lexical requirements). Without the help of a p/w manager i would not even be on atlassian at all. There are now ~100 DID methods. RPs will never to interested in supporting so many. How then to manage a world with ~100 digital identifiers per person? Doc Searls proposed a [[Vendor Relationship Manager]] (VRM) app, perhaps that would be a better word for what we are about?</blockquote>
 +
 
 
==Context==
 
==Context==
* Report of a method to improve a sign in [[User Experience]] from an RP site for first time signin with a DID that they can get with, say, Google or FB.
+
# Report of a method to improve a sign in [[User Experience]] from an RP site for first time signin with a self-issued ID than they can get with, say, Google or FB.
 +
# Report of a method to improve a sign in when the user returns to the same site.
 +
In both cases the user is given a choice on a "Selection" menu where options are related to something the user knows, which should be the identifiers that the user has enabled.
 +
===Terms and Abbreviations===
  
==Contents==
+
{|border="1" padding="2" width="799px"
* This is from a 2020-10 version of a DIF doc.
+
| Term || Description
This specification defines the "SIOP DID Profile" (SIOP DID) that is a DID AuthN flavor to use OpenID Connect (OIDC) together with the strong decentralization, privacy and security guarantees of Decentralized Identifiers (DID) for everyone who wants to have a generic way to integrate Identity Wallets into their web applications.
+
|-
 +
|User || An organic human being operating a computing device, typically a smartphone or laptop.
 +
|-
 +
| DID || Decentralized Identifier as per DID.Core<ref name=DID>W3C, ''Decentralized Identifiers (DIDs) v1.0.'' https://www.w3.org/TR/did-core</ref>
 +
|-
 +
| DID Document || DID Document as per [DID.Core]
 +
|-
 +
|SIOP DID || Self-Issued OpenID Connect Provider DID profile. Refers to a specific flavor(s) of Verification Method used in the OIDC SIOP flow.
 +
|-
 +
| JWT || JSON Web Token as per [RFC7797]
 +
|-
 +
|  JWE || JSON Web Encryption as per [RFC7516]
 +
|-
 +
| JWS || JSON Web Signature as per [RFC7515]
 +
|-
 +
| JWK || JSON Web Key as per [RFC7517]
 +
|-
 +
|  JWKS || JWK Set as per [RFC7517]
 +
|-
 +
|  OIDC || OpenID Connect as per [OIDC.Core]
 +
|-
 +
|OAuth client || Used synonymously with Relying Party (see RP)
 +
|-
 +
| OP || OpenID Provider as per [OIDC.Core]
 +
|-
 +
|SIOP || Self-Issued OpenID Provider as per [OIDC.Core] section 7.
 +
|-
 +
|RP || Relying Party, as used in [OIDC.Core] for any website the relies on claims produced by a CP for example an OP.
 +
|-
 +
| CP || Claims provider, Certificate Provider, Credential Provider, Credential Service Provider (CSP), etc.
 +
|-
 +
| Identity Wallet || An application that is under the control and acts on behalf of the key credential holder. aka identity agent. can be a mobile app, browser extension/ plugin etc.
 +
|-
 +
| DID AuthN || Refers to a method of proofing control over a DID for the purpose of authentication.
 +
|-
 +
|Verification Method || a more recent name for one instance of a DID AuthN
 +
|-
 +
| Trust Authority || A URL endpoint that contains the references that define, inter alia, the operation of the picker and of the wallets
 +
|-
 +
|Trusted Wallet || code trusted by one or more Trust Authorities to protect user secrets and perhaps to validate user presence.
 +
|-
 +
| Identity Wallet || An application that is under the control and acts on behalf of the key credential holder. aka identity agent. can be a mobile app, browser extension/ plugin etc.
 +
|-
 +
|JAM session || The period of time from when the user clicks on a link in the RP until the UI for the wallet is accepted by the user.
 +
|}
  
Status of This Document
+
More items, especially those related to the meaning of origin or site are on the wiki page [[PWA initiators]].
SIOP DID is a draft specification being developed within the Decentralized Identity Foundation (DIF). This spec will be updated to reflect relevant changes, and participants are encouraged to contribute at the following repository location: https://github.com/decentralized-identity/did-siop
 
  
Table of Contents
+
===Scope of Picker===
#Terminology
+
There really is not any one location or scope of control that needs to be determined.  A picker can be at one one of these levels of control.
# Introduction
+
# Family
## Purpose
+
# Individual
## Goals
+
# Platform (Android, Apple, etc.)
# Protocol Flow
+
# Device
## Generate SIOP Request
+
# Wallet
## Request (Regular-device Flow)
+
# Identifier Friendly Name.
### Request Validation (Regular-device Flow)
+
Also sync can be performed at the high levels so that an individual can sync all devices and wallets, or a platform can sync all devices (and keystores) that share that platform.
### SIOP Request Validation
 
### Generate SIOP Response
 
### SIOP Response Validation
 
### SIOP Discovery
 
## UX Considerations
 
## Security Considerations
 
## IANA Considerations
 
## OIDC Considerations
 
#.References
 
## Normative references
 
## Informative references
 
# Terminology
 
This section is non-normative.
 
  
Term Description
+
==Problems==
DID Decentralized Identifier as per [DID]
+
# As originally specified in section 7 of the [[OpenID Connect]] specification, there was a single end-point specified for the user. The implicit assumption here is that a user would only have a single wallet. That is not the way the world evolved.
DID Document DID Document as per [DID]
+
# The [[Relying Party]]. RP cannot know all of the identifier providers at the user's disposal when the user first goes to the site. (Or returns anonymously.)
SIOP DID Self-Issued OpenID Connect Provider DID profile. Refers to a specific flavor of DID AuthN used in the OIDC SIOP flow.
+
# The user may not remember if they have already registered at the RP or which identifier they used when they last went to the RP. (The assumption is that there is on RP cookie on the users device.
JWT JSON Web Token as per [RFC7797]
+
# The user may have a wide range of devices that they want to use as and where convenient to them.
JWE JSON Web Encryption as per [RFC7516]
+
# The current [Did.core] model does not address the user experience of having a number of identifiers that are completely unhelpful for user choice without some selection method they can understand.
JWS JSON Web Signature as per [RFC7515]
 
JWK JSON Web Key as per [RFC7517]
 
JWKS JWK Set as per [RFC7517]
 
OIDC OpenID Connect as per [OIDC.Core]
 
OIDC client Used synonymously with Relying Party (see RP)
 
OP OpenID Provider as per [OIDC.Core]
 
SIOP Self-Issued OpenID Provider as per [OIDC.Core]
 
RP Relying Party, as used in [OIDC.Core]
 
Identity Wallet An Identity Wallet refers to a application that is under the control and acts on behalf of the DID holder. This Also known as an identity agent. The Identity Wallet can have different form factors such as a mobile app, browser extension/ plugin etc.
 
DID AuthN Refers to a method of proofing control over a DID for the purpose of authentication.
 
2. Introduction
 
This section is non-normative.
 
  
An everyday use case that the Decentralized Identity community identified is the sign-up or login with web applications. Nowadays, this is often achieved through social login schemes such as Google Sign-In. While the Decentralized Identity community has serious concerns about social login, the underlying protocol, OIDC, does not have these flaws by design. SIOP DID provides great potential by leveraging an Identity Wallet, e.g., as a smartphone app, on the web. This will increase and preserve the user’s privacy by preventing third-parties from having the ability to track which web applications a user is interacting with.
+
==User Experience==
 +
This section addresses an optimal user experience with no consideration of where the picker resides or how is is implemented.  The following are the expected steps to use the picker, or chooser as it is now known.
 +
# User determines that they want to have one or more self-issued identifiers.
 +
# User will have already selected at least a few credentials that they wish to store. We will assume these two as a base use case:
 +
## Driver's license
 +
## Health card in SHC format
 +
# User will chose a smart phone and a wallet or user agent app to begin the process. This choice may be dictated by their required credentials.
 +
# The wallet will give the user the option to enable one (or more) federated choices, perhaps based on the federation logo on their favorite web sites. The user will be given an option to list one or more of their personal self-issued identifiers. NOTE - all of the federation data can (optionally) be stored on the user's device and not on the the chooser site. (At a future time we might be able to include the sharing of that data on multiple devices owned by the user.)
 +
# The next time the user goes to a web site where they have no active cookie, that site should list the particular federation logos that they have joined.
 +
# The user clicks on the logo and one of several actions will occur:
 +
## The user as a single wallet with a single ID that is selected and the user is given the consent menu.
 +
## The user may have more than one ID on more than one wallet that are known to be part of that federation and so the user is give a choice as to which ID to use with this web site.
 +
# The user consent dialog will be presented by the wallet with a list of the data types that were requested by the web site. (It's possible in the future that some of the data elements that are not required can be de-selected by the user as is required by, at least, the California privacy legislation).
 +
# The user clicks "OK" and the user is connected to the web site as a fully registered user.
  
NOTE
 
While this specification focuses on the integration of Identity Wallets in the form of browser extensions/ plugins, or smartphone apps, it does not prevent implementers using the proposed flow in different scenarios as well, e.g., between two web services with pre-populated DIDs.
 
  
2.1 Purpose
+
[[File:FrameworkChooser.png]]
This section is non-normative.
+
 
 +
==Solutions==
 +
* This document describes a picker which can intercept a AuthZ request flowing from an RP and help the user select the appropriate wallet and perhaps even the appropriate identifier.
 +
* In all cases the user on a user agent (assumed here, without prejudice, to be a brewer) navigates to the [[Relying Party]] which displays one or more buttons that take the user to a picker which can be of any type located on any accessible site, include the device hosting the browser.
 +
 
 +
===Device Based===
  
The main purpose is to sign up with/ login to an RP, i.e., web application. It assumes the user operates a mobile or desktop browser or a browser-based app that can respond to SIOP requests according to this specification.
+
* The ideal place for the picker is the [[Password Manager]] in the browser, which can be loaded by the user, but that is painful at the start of 2021, so other solutions are needed in the short term.
 +
* The picker can be in a native app that assumes ownership of openid:// and sorts out the user choice on their own device. Unless a sharing solution were created, this would only work if the user had the app on every devices and initialized every device with their preferences.
  
NOTE
+
===Cloud Based===
The SIOP flow is conducted peer-to-peer between the RP and the SIOP. This could be used to authenticate holders based on their DID, to setup/ bootstrap a DID Comm connection with any DID routing that you may need, or to provide the login_hint to an OpenID Connect service in the DID Document supporting the Client-Initiated Backend Channel (CIBA) as per [OIDC.CIBA].
+
a cloud based solution is proposed for the sort term. The following discussion is based on a full could implementation but a web app solution would be a natural extension.
  
2.2 Goals
+
An everyday use case that the Decentralized Identity community identified is the sign-up or login with web applications. Nowadays, this is often achieved through social login schemes such as Google Sign-In. While the Decentralized Identity community has serious concerns about social login, the underlying protocol, OIDC, does not have these flaws by design. SIOP DID provides great potential by leveraging an Identity Wallet, e.g., as a smartphone app, on the web. This will increase and preserve the user’s privacy by preventing third-parties from having the ability to track which web applications a user is interacting with. SIOP focuses on the integration of Identity Wallets in the form of browser extensions/ plugins, or smartphone apps, it does not prevent implementers using the proposed flow in different scenarios as well, e.g., between two web services.
This section is non-normative.
 
  
The main goals of this specification are:
+
The main use case is to sign up with/ login (aka register) to an RP, i.e., website. It assumes the user operates a mobile or desktop browser or a browser-based app that can respond to SIOP requests.
  
Staying backward compatible with existing OIDC clients and OPs that implement the SIOP specification which is part of the OIDC core specification as per [OIDC.Core] to reach a broader community.
+
The SIOP picker will eithe generate or pass trough the <SIOP Response> based on the specific DID method that the user choses. If required it can reconstitute or amend the request for transmission to the SIOP (wallet).The primary use case will install one or more identity wallets on the user smartphone.
Adding validation rules for OIDC clients that have DID AuthN support to make full use of DIDs.
 
Not relying on any intermediary such as a traditional centralized public or private OP while still being OIDC-compliant.
 
3. Protocol Flow
 
This specification assumes, the user is operating a mobile or desktop browser to visit a web application or uses a browser-based app.
 
  
First, the user clicks on the sign up or login UX element. The RP will then generate the redirect to openid://<SIOP Request> which will be handled by the SIOP.
+
This specification does not explicitly support any particular location for the picker. It is expected that both cloud-based and device based pickers will be enabled.
  
NOTE
+
===User Creates Choices===
On the mobile device, this would open the Identity Wallet app, e.g., uport, connect.me. On the desktop browser, this would either show a QR code which can be scanned by the Identity Wallet app or a redirect to openid://<SIOP Request> that for instance could be handled by a browser extension/ plugin implementing the SIOP.
+
This is a series of actions that can involve:
 +
# More that one device that protect user secrets in what is called here a '''Wallet'''.
 +
# User may create any number of '''Identifiers''' on each '''wallet'''.
 +
# User may wish to migrate or back-up the wallet on a number or devices.
 +
# User may choose to include or exclude each '''Wallet''' on any one of the user-controlled '''Wallets'';
 +
# No assumptions is made here about whether the devices are (1) smartphone (2) laptops, (3) user controlled servers, or (4) Wallet as a service. (Also called Mobile as a Service in the EU.
 +
# Each '''Wallet''' is trusted on one ore more '''Trust Authorities'''.
 +
# The RP gets to select the '''Trust Authorities''' that have the characteristics that will allow the RP to make a trust decsiion about users that seek to register with the RP.
  
The SIOP will generate the <SIOP Response> based on the specific DID method that is supported. The <SIOP Response> will be signed and optionally encrypted and will be provided according to the requested response mode.
+
=== Generate SIOP Request at the RP===
 +
The Redirect 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.
  
This specification does not explicitly support any intermediate hubs or cloud agents. It is meant to be a protocol to exchange the DID. You could then interact with a hub/ cloud agent using the service endpoint in the DID Document.
+
The following are taken directly from the OIDC. It is not clear that the RP will know or even care whether the request is to be filled by a SIOP when a picker is used. It may not even be necessary for the picker to be limited to SIOP requests.
  
Unlike the OIDC Authorization Code Flow as per [OIDC.Core], the SIOP will not return an access token to the RP. If this is desired, this could be achieved by following the aforementioned CIBA flow as per [OIDC.CIBA] in addition. SIOP also differs from Authorization Code Flow by not relying on a centralized and known OP. The SIOP can be unknown to the RP until the user starts to interact with the RP using its Identity Wallet. OIDC Authorization Code Flow is still a useful approach and should be used whenever the OP is known, and OP discovery is possible, e.g., exchanged or pre-populated DID Document containing an openid element in the service section. The SIOP flow allows to integrate Identity Wallets with plain OIDC clients if they implemented the SIOP specification. In contrast, using DID AuthN as the authentication means in the OIDC Authorization Code Flow would require integration with the OP vendor itself.
+
The following is a non-normative example HTTP 302 redirect response from the Client, which flows through the picker to the User Agent to make an Authentication Request to the Authorization Endpoint.
 +
  HTTP/1.1 302 Found
 +
  Location: https://server.example.com/authorize?
 +
    response_type=code
 +
    &scope=openid%20profile%20email
 +
    &client_id=s6BhdRkqt3
 +
    &state=af0ifjsldkj
 +
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
  
Example SIOP flow with a mobile browser as the User-Agent
+
The following is the non-normative example request that would be redirected through the User Agent to the Authorization Server in response to the HTTP 302 redirect response by the Client above:
              and an Identity Wallet app as the SIOP.
 
Figure 1 Example SIOP flow with a mobile browser as the User-Agent and an Identity Wallet app as the SIOP.
 
3.1 Generate SIOP Request
 
Redirect Request
 
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.
 
  
EXAMPLE 1
+
  GET /authorize?
openid://?response_type=id_token
+
    response_type=code
     &client_id=https%3A%2F%2Frp.example.com%2Fcb
+
    &scope=openid%20profile%20email
    &scope=openid%20did_authn
+
     &client_id=s6BhdRkqt3
    &request=<JWT>
+
    &state=af0ifjsldkj
In the example above the DID AuthN <SIOP Request> is initiated by the RP using Request Object by value.
+
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
 +
  Host: server.example.com
  
EXAMPLE 2
 
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
 
In the example above the DID AuthN <SIOP Request> is initiated by the RP using Request Object by reference.
 
  
RP Meta-data
+
'''RP Meta-data'''
 
In contrast to other OIDC flows, e.g., Authorization Code Flow, RPs can provide client meta-data in the registration request parameter.
 
In contrast to other OIDC flows, e.g., Authorization Code Flow, RPs can provide client meta-data in the registration request parameter.
  
In addition to RS256, an SIOP according to this specification MUST support EdDSA and ES256K [draft-ietf-cose-webauthn-algorithms-03] for request_object_signing_alg and request_object_signing_alg can be omitted. RPs implementing the DID AuthN profile MUST not use none for request_object_signing_alg.
+
Request_object_signing_alg can be omitted. RPs implementing the DID AuthN profile MUST not use none for request_object_signing_alg.
  
The Request Object MUST be directly or indirectly verifiable by a verification method in the RP's DID Document and directly by the RP's JWKS. The JWKS MUST be provided in the jwks_uri or jwks entry of the registration parameter. The JWKS MUST contain an entry with a kid that matches the kid in the Request Object. jwks_uri MUST use the HTTP(S) DID Resolution Binding as per [DID.Resolution] for backward compatibility reasons with plain SIOP OPs. The jwks request parameter SHOULD be used only if the public key cannot be directly obtained from the DID Document.
+
There is no limitation placed on the ULR used by the client for identification. The JWKS MUST be provided in the jwks_uri or jwks entry of the registration parameter. Alternatively this can be handled by a DID doc.
  
RPs can decide to receive the SIOP Response encrypted. To enable encryption, the registration parameter MUST use id_token_encrypted_response_alg and id_token_encrypted_response_enc according to OIDC Client Metadata [OIDC.Registration]. This specification RECOMMENDS the use of ECDH-ES with the X25519 curve for JWE as explained in section Encryption and described in [draft-amringer-jose-chacha-00].
+
RPs can decide to receive the SIOP Response encrypted. To enable encryption, the registration parameter MUST use id_token_encrypted_response_alg and id_token_encrypted_response_enc according to OIDC Client Metadata [OIDC.Registration].
  
Request Object
+
'''Request Object'''
 
The Request Object follows the OIDC specification, e.g., adding nonce, state, response_type, and client_id parameters.
 
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:
+
The SIOP specification introduces additional rules for request parameters and claims in the Request Object:
 +
 
 +
Regular flow using a smartphone.
  
Regular flow using mobile phone.
+
'''Request (Regular-device Flow)'''
Figure 2 : Regular Flow with a mobile browser as the User-Agent and an Identity Wallet app as the SIOP.
 
3.1.1 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 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.
  
Line 132: Line 182:
 
This specification introduces additional rules for request parameters and claims in the Request Object:
 
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.
+
REQUIRED. iss MAY 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.
NOTE
+
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.
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. scope MUST include did_authn to indicate the SIOP DID profile is used.
 
+
REQUIRED. registration MUST be included in the Request Object
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. client_id MUST be repeated in the Request Object
REQUIRED. scope MUST include did_authn to indicate the SIOP DID profile is used.
+
OPTIONAL. did_doc MUST contain the DID Document that corresponds to the DID in the iss claim.
REQUIRED. registration MUST be included in the Request Object
+
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.
REQUIRED. client_id MUST be repeated in the Request Object
+
OPTIONAL. response_context specifies whether the response should be returned to the callback URL in the context of an existing system browser session, or whether the response can be returned in a new/empty context (requested with a response_context of wallet). The default response_context is rp, indicating that the response should be submitted in the conext of the RP's existing system browser session.
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.
 
NOTE
 
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.
 
 
 
OPTIONAL. response_context specifies whether the response should be returned to the callback URL in the context of an existing system browser session, or whether the response can be returned in a new/empty context (requested with a response_context of wallet). The default response_context is rp, indicating that the response should be submitted in the conext of the RP's existing system browser session.
 
NOTE
 
A response_mode of wallet indicates to the SIOP that the user flow should end in the SIOP, without any in-band redirection back to the RP. This behavior is useful in cross-device workflows where it's appropriate for the mobile portion of the flow to terminate in the wallet.
 
  
 
The following is a non-normative example of the JWT header of a Request Object:
 
The following is a non-normative example of the JWT header of a Request Object:
  
 
EXAMPLE 3
 
EXAMPLE 3
{
+
{
 
   "alg": "ES256K",
 
   "alg": "ES256K",
 
   "typ": "JWT",
 
   "typ": "JWT",
Line 160: Line 202:
  
 
EXAMPLE 4
 
EXAMPLE 4
{
+
{
 
     "iss": "did:example:0xab",
 
     "iss": "did:example:0xab",
 
     "response_type": "id_token",
 
     "response_type": "id_token",
Line 172: Line 214:
 
         "id_token_signed_response_alg" : "ES256K"
 
         "id_token_signed_response_alg" : "ES256K"
 
     }
 
     }
}
+
}
 
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):
 
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):
  
 
EXAMPLE 5
 
EXAMPLE 5
HTTP/1.1 302 Found
+
HTTP/1.1 302 Found
Location: openid://?
+
Location: openid://?
 
     &client_id=https%3A%2F%2Frp.example.com%2Fcb
 
     &client_id=https%3A%2F%2Frp.example.com%2Fcb
 
     &scope=openid%20did_authn
 
     &scope=openid%20did_authn
Line 184: Line 226:
  
 
EXAMPLE 6
 
EXAMPLE 6
HTTP/1.1 302 Found
+
HTTP/1.1 302 Found
Location: openid://?
+
Location: openid://?
 
     response_type=id_token
 
     response_type=id_token
 
     &client_id=https%3A%2F%2Frp.example.com%2Fcb
 
     &client_id=https%3A%2F%2Frp.example.com%2Fcb
 
     &scope=openid%20did_authn
 
     &scope=openid%20did_authn
 
     &request_uri=https%3A%2F%2Frp.example.com%2F90ce0b8a-a910-4dd0
 
     &request_uri=https%3A%2F%2Frp.example.com%2F90ce0b8a-a910-4dd0
3.1.2 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].
 
  
NOTE
 
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
 
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.
 
NOTE
 
 
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.
 
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.
  
Line 207: Line 238:
  
 
EXAMPLE 7
 
EXAMPLE 7
{
+
{
 
   "alg": "ES256K",
 
   "alg": "ES256K",
 
   "typ": "JWT",
 
   "typ": "JWT",
 
   "kid": "did:example:0xab#veri-key1"
 
   "kid": "did:example:0xab#veri-key1"
}
+
}
 
The following is a non-normative example of the JWT payload of a Request Object without requesting <SIOP Response> encryption:
 
The following is a non-normative example of the JWT payload of a Request Object without requesting <SIOP Response> encryption:
  
 
EXAMPLE 8
 
EXAMPLE 8
{
+
{
 
     "iss": "did:example:0xab",
 
     "iss": "did:example:0xab",
 
     "response_type": "id_token",
 
     "response_type": "id_token",
Line 227: Line 258:
 
         "id_token_signed_response_alg" : [ "ES256K", "EdDSA", "RS256" ]
 
         "id_token_signed_response_alg" : [ "ES256K", "EdDSA", "RS256" ]
 
     }
 
     }
}
+
}
 
Encryption
 
Encryption
 
JWE encryption MUST use Diffie-Hellman key agreement, i.e., algorithm ECDH-ES using the X25519 curve which uses direct key agreement with an ephemeral key. This means that a symmetric key is derived using Diffie-Hellman from the RP's public key and a randomly generated ephemeral private key. The corresponding ephemeral public key is included in the header of the JWE in the epk and the derived symmetric key is used to directly encrypt the JWT content. For symmetrically encrypting the content XChaCha20Poly1305 is used which has algorithm code XC20P.
 
JWE encryption MUST use Diffie-Hellman key agreement, i.e., algorithm ECDH-ES using the X25519 curve which uses direct key agreement with an ephemeral key. This means that a symmetric key is derived using Diffie-Hellman from the RP's public key and a randomly generated ephemeral private key. The corresponding ephemeral public key is included in the header of the JWE in the epk and the derived symmetric key is used to directly encrypt the JWT content. For symmetrically encrypting the content XChaCha20Poly1305 is used which has algorithm code XC20P.
Line 234: Line 265:
  
 
EXAMPLE 9
 
EXAMPLE 9
{
+
{
 
   "alg": "ECDH-ES",
 
   "alg": "ECDH-ES",
 
   "epk":
 
   "epk":
Line 244: Line 275:
 
   "enc": "XC20P",
 
   "enc": "XC20P",
 
   "kid": "did:example:0xab#key-1"
 
   "kid": "did:example:0xab#key-1"
}
+
}
 
Note that the kid above denotes the DID and key of the RP, i.e., this public key is the key used by the sender together with the ephemeral private key in order to derive the shared secret. For the encryption the 24 bytes nonce field in the XChaCha20 algorithm is used as the initialization vector. The authentication tag is the MAC computed by the Poly1305 function. It is 16 bytes long.
 
Note that the kid above denotes the DID and key of the RP, i.e., this public key is the key used by the sender together with the ephemeral private key in order to derive the shared secret. For the encryption the 24 bytes nonce field in the XChaCha20 algorithm is used as the initialization vector. The authentication tag is the MAC computed by the Poly1305 function. It is 16 bytes long.
  
Line 251: Line 282:
 
For the final encoding of the JWE the JWE Compact Serialization outlined in [RFC7516] is used. The structure of the message is as follows:
 
For the final encoding of the JWE the JWE Compact Serialization outlined in [RFC7516] is used. The structure of the message is as follows:
  
EXAMPLE 10
+
EXAMPLE 10
BASE64URL(JWE Protected Header) || '.' || '.' ||
+
BASE64URL(JWE Protected Header) || '.' || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
+
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
+
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)
+
BASE64URL(JWE Authentication Tag)
Note the two '.' characters above which indicates that the encrypted key is empty since we are using direct key agreement.
+
Note the two '.' characters above which indicates that the encrypted key is empty since we are using direct key agreement.
 
 
3.1.3 SIOP Request Validation
 
The SIOP MUST validate the <SIOP Request> by following the Self-Issued ID Token Validation rules as per [OIDC.Core].
 
  
 +
=== Processing the SIOP Request at the Picker===
 +
The Picker MUST validate the <SIOP Request> by following the Self-Issued ID Token Validation rules as per [OIDC.Core].
 
NOTE
 
NOTE
 
The step described above ensures that the Request Object is verified according to the OIDC specification. This includes basic JWS verification.
 
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 Request as follows in no particular order:
+
If scope contains the did_authn scope, the receiving Picker or SIOP MUST further validate the SIOP 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 no did_doc is present, resolve the DID Document from the RP's DID specified in the iss request parameter.
Line 270: Line 300:
 
If jwks_uri is present, ensure that the DID in the jwks_uri matches the DID in the iss claim.
 
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 Request.
 
Determine the verification method from the RP's DID Document that matches the kid of the SIOP Request.
Verify the SIOP 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.
+
Verify the SIOP 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 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.
NOTE
 
If the key pair that signed the SIOP 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.
 
  
3.1.4 Generate SIOP Response
+
===API for syncing picker data from the wallet to the picker===
The SIOP MUST generate and send the <SIOP Response> to the RP as described in the Self-Issued OpenID Provider Response section in [OIDC.Core]. The id_token represents the <SIOP Response> encoded as a JWS, or nested JWS/JWE.
+
The need for a spec at this level seems helpful. No effort has been started by 2021-04-01
  
This specification introduces additional rules for claims in the id_token:
+
===UX Considerations===
 
 
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.
 
NOTE
 
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:
 
 
 
EXAMPLE 11
 
{
 
    "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:
 
EXAMPLE 12
 
{
 
  "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"
 
}
 
3.1.5 SIOP Response Validation
 
The RP MUST validate the <SIOP 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.
 
NOTE
 
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.
 
 
 
3.1.6 SIOP Discovery
 
The SIOP specification assumes the following OP discovery meta-data:
 
 
 
"id_token_signing_alg_values_supported": ["RS256"],
 
"request_object_signing_alg_values_supported": ["none", "RS256"]
 
The DID AuthN profile assumes the following OP discovery meta-data:
 
 
 
"id_token_signing_alg_values_supported": ["RS256", "ES256K", "EdDSA"],
 
"request_object_signing_alg_values_supported":
 
  ["none", "RS256", "ES256K", "EdDSA"]
 
This change will allow DID AuthN enabled RPs to use additional signature algorithms commonly used amongst members of the SSI community.
 
 
 
NOTE
 
"Self-Issued OpenID Provider Discovery" IS NOT normative and does not contain any MUST, SHOULD, or MAY statements. Therefore, using a different signing algorithmn than RS256 shouldn't break the SIOP specification. An DID AuthN enabled RP would provide id_token_signed_response_alg to indicate which signature algorithms other than RS256 are supported, and can assume that SIOP implementing the DID AuthN profile support any of the additional algorithms.
 
  
3.2 UX Considerations
+
The Picker will provide a UX with the user choices. This requires that a user (or user wallet) register their options the the picker. It is expected that such a registration API can be defined in some spec at a later time..
This section is non-normative.
 
  
SIOP uses the custom URL scheme openid://. Mobile browsers would open the app that registered that scheme. Desktop browser extensions/ plugins have support for similar functionality. It is out of the scope of the spec under which circumstances a QR code will be rendered. One option will be to provide the QR code if the user is using the desktop browser, and no browser extension/ plugin is available.
+
SIOP defines a custom URL scheme openid://. Mobile browsers would open the app that registered that scheme. Desktop browser extensions/ plugins have support for similar functionality. It is out of the scope of the spec under which circumstances a QR code will be rendered. One option will be to provide the QR code if the user is using the desktop browser, and no browser extension/ plugin is available.
  
 
On Android, the user can choose which app should open if multiple apps registered the same custom URL scheme. On iOS, the behavior is undefined. One approach would be to check if the user is on an iOS device and then, won't render the button if this is a concern. A fallback on iOS could be the use of custom mime types, but unusual UX has to be considered. Note, this issue is not specific to SIOP only but affects all apps using custom URL schemes. In case a QR Code is used where the user has to open the app first and has to scan the QR Code, this issue is mitigated.
 
On Android, the user can choose which app should open if multiple apps registered the same custom URL scheme. On iOS, the behavior is undefined. One approach would be to check if the user is on an iOS device and then, won't render the button if this is a concern. A fallback on iOS could be the use of custom mime types, but unusual UX has to be considered. Note, this issue is not specific to SIOP only but affects all apps using custom URL schemes. In case a QR Code is used where the user has to open the app first and has to scan the QR Code, this issue is mitigated.
  
 
===Security Considerations===
 
===Security Considerations===
This section is non-normative.
 
  
Threat: Interception of the Redirect URI
+
'''Threat:''' Interception of the Redirect URI
 
If an attacker can cause the <SIOP Response> to be sent a URI under his control, he will directly get access to the fragment carrying the id_token.
 
If an attacker can cause the <SIOP Response> to be sent a URI under his control, he will directly get access to the fragment carrying the id_token.
  
 
This attack can be mitigated by hardening the RP, e.g., no support for the open redirector pattern.
 
This attack can be mitigated by hardening the RP, e.g., no support for the open redirector pattern.
  
Threat: Identity Token Leak in Browser History
+
'''Threat:''' Identity Token Leak in Browser History
 
An attacker could obtain the <SIOP Response> from the browser's history.
 
An attacker could obtain the <SIOP Response> from the browser's history.
  
 
This attack cannot be fully mitigated. It is RECOMMENDED to use short expiration times for id_token, and indicating that browsers should not cache the response.
 
This attack cannot be fully mitigated. It is RECOMMENDED to use short expiration times for id_token, and indicating that browsers should not cache the response.
  
Threat: Identity Token Leak to Third Party Scripts
+
'''Threat:''' Identity Token Leak to Third Party Scripts
 
It is relatively common to use third-party scripts on RP pages, such as analytics tools, crash reporting. The author of the application may not be able to be fully aware of the entirety of the code running in the application. When a <SIOP Response> is returned in the fragment, it is visible to any third-party scripts on the page.
 
It is relatively common to use third-party scripts on RP pages, such as analytics tools, crash reporting. The author of the application may not be able to be fully aware of the entirety of the code running in the application. When a <SIOP Response> is returned in the fragment, it is visible to any third-party scripts on the page.
  
Line 367: Line 333:
 
Use response_mode=form_post whenever possible to mitigate the risks described above. Under some circumstances, e.g., this will not be possible as such in the case of purely decentralized apps (dApp).
 
Use response_mode=form_post whenever possible to mitigate the risks described above. Under some circumstances, e.g., this will not be possible as such in the case of purely decentralized apps (dApp).
  
Threat: Session Fixation in Cross-Device Flow
+
'''Threat:''' Session Fixation in Cross-Device Flow
 
When the protocol begins on one device and ends on another, there is a risk that the cross-device transfer can be hijacked. For example, consider a flow that begins with the display of a QR code by the RP transfers to a mobile wallet when the user scans the QR code. In this scenario, an attacker can trick the user into scanning a QR code associated with a legitimate RP's sign-in request, thereby causing the user to authenticate within the context of the attacker's session.
 
When the protocol begins on one device and ends on another, there is a risk that the cross-device transfer can be hijacked. For example, consider a flow that begins with the display of a QR code by the RP transfers to a mobile wallet when the user scans the QR code. In this scenario, an attacker can trick the user into scanning a QR code associated with a legitimate RP's sign-in request, thereby causing the user to authenticate within the context of the attacker's session.
  
Line 373: Line 339:
 
Validate that the browser session in which the DID SIOP Response is submitted belongs to the same user as the browser session in which the DID SIOP Request was displayed. Even if these sessions are on different devices, the RP can take steps to ensure these belong to the same user (e.g., by checking whether an existing session exists or by asking the user to sign in through a non-SIOP means).
 
Validate that the browser session in which the DID SIOP Response is submitted belongs to the same user as the browser session in which the DID SIOP Request was displayed. Even if these sessions are on different devices, the RP can take steps to ensure these belong to the same user (e.g., by checking whether an existing session exists or by asking the user to sign in through a non-SIOP means).
  
Additional Security Considerations
+
'''Additional Security Considerations'''
The OWASP Foundation maintains a set of security recommendations and best practices for web applications, and it is RECOMMENDED to follow these best practices when creating an SIOP or RP based on this specification.
+
* Putting user information in a central location creates a rich source of data that attackers can target. Metamask performed similar function crytocurrency that created a paradigm that attackers could follow to acquire user trust maleciously.<ref>Datid Canellis, ''PSA: MetaMask reveals your Ethereum address to sites you visit, here’s how to hide it'' Hard Fork | The Next Web (2019-03-22)  https://thenextweb.com/hardfork/2019/03/22/metamask-ethereum-privacy-address/</ref>
 +
*The OWASP Foundation maintains a set of security recommendations and best practices for web applications, and it is RECOMMENDED to follow these best practices when creating an SIOP or RP based on this specification.
  
 
===UX Considerations===
 
===UX Considerations===
 +
* It is expected that each trust federation will create their own picker, although a federation of federations is a distinct possibility.
 +
* The RP will need little change as the picker will appear to be a normal OIDC URL. It is expected that there will be additional text provided by the RP to inform the user as the the expectation on clicking a picker (federation) button.
 
* For Native apps the URL Schema redirect can be overridden the the last app to request access.
 
* For Native apps the URL Schema redirect can be overridden the the last app to request access.
 
* For PWA (web apps) the URL is bound to the web site that installed the PWA, leading to exacerbations of the NASCAR logo problem.
 
* For PWA (web apps) the URL is bound to the web site that installed the PWA, leading to exacerbations of the NASCAR logo problem.
Line 382: Line 351:
  
 
===OIDC Considerations===
 
===OIDC Considerations===
This section is non-normative.
 
  
This specification aims to be backward compatible with existing OIDC clients and OPs that implement the SIOP specification. Although the SIOP specification is part of the OIDC core specification, it is not widely adopted yet. One of the reasons was that not many apps existed that provided functionality we can find in Identity Wallets. Nevertheless, SIOP uses the same or similar request and response messages and should be easy to allow OIDC vendors to upgrade existing OIDC clients to support SIOP.
+
This work aims to be backward compatible with existing OIDC clients and OPs that implement the SIOP specification. Although the SIOP specification is part of the OIDC core specification, it is not widely adopted yet. One of the reasons was that not many apps existed that provided functionality we can find in Identity Wallets. Nevertheless, SIOP uses the same or similar request and response messages and should be easy to allow OIDC vendors to upgrade existing OIDC clients to support SIOP.
  
 
==References==
 
==References==
 +
<references />
 
===Normative references===
 
===Normative references===
[DID.Resolution]
+
* [DID.Resolution] Decentralized Identifier Resolution. Markus Sabadello; Dmitri Zagidulin. Credentials Community Group. Draft Community Group Report. URL: https://w3c-ccg.github.io/did-resolution/
Decentralized Identifier Resolution. Markus Sabadello; Dmitri Zagidulin. Credentials Community Group. Draft Community Group Report. URL: https://w3c-ccg.github.io/did-resolution/
+
* [draft-amringer-jose-chacha-00] Chacha derived AEAD algorithms in JSON Object Signing and Encryption (JOSE). G. Amringer. 2018. URL: https://tools.ietf.org/html/draft-amringer-jose-chacha-00
[draft-amringer-jose-chacha-00]
+
* [draft-ietf-cose-webauthn-algorithms-03] COSE and JOSE Registrations for WebAuthn Algorithms. M. Jones. 2019. URL: https://tools.ietf.org/html/draft-ietf-cose-webauthn-algorithms-03
Chacha derived AEAD algorithms in JSON Object Signing and Encryption (JOSE). G. Amringer. 2018. URL: https://tools.ietf.org/html/draft-amringer-jose-chacha-00
+
* [OIDC.Core] OpenID Connect Core 1.0 incorporating errata set 1. N. Sakimura; J. Bradley; M. Jones; B. de Medeiros; C. Mortimore. 2014. URL: https://openid.net/specs/openid-connect-core-1_0.html
[draft-ietf-cose-webauthn-algorithms-03]
+
* [OIDC.Registration] OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1. N. Sakimura; J. Bradley; M. Jones. 2014. URL: https://openid.net/specs/openid-connect-registration-1_0.html
COSE and JOSE Registrations for WebAuthn Algorithms. M. Jones. 2019. URL: https://tools.ietf.org/html/draft-ietf-cose-webauthn-algorithms-03
+
* [RFC6749] The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6749
[OIDC.Core]
+
* [RFC7516] JSON Web Encryption (JWE). M. Jones; J. Hildebrand. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7516
OpenID Connect Core 1.0 incorporating errata set 1. N. Sakimura; J. Bradley; M. Jones; B. de Medeiros; C. Mortimore. 2014. URL: https://openid.net/specs/openid-connect-core-1_0.html
+
 
[OIDC.Registration]
 
OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1. N. Sakimura; J. Bradley; M. Jones. 2014. URL: https://openid.net/specs/openid-connect-registration-1_0.html
 
[RFC6749]
 
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6749
 
[RFC7516]
 
JSON Web Encryption (JWE). M. Jones; J. Hildebrand. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7516
 
 
===Informative references===
 
===Informative references===
* [https://identity.foundation/did-siop/ Self-Issued OpenID Connect Provider DID Profile] DIF Working Group Draft
+
* [https://identity.foundation/did-siop/ Self-Issued OpenID Connect Provider DID Profile] DIF Working Group Draft DID https://www.w3.org/TR/did-core/. Drummond Reed; Manu Sporny; Dave Longley; Christopher Allen; Ryan Grant; Markus Sabadello. Decentralized Identifier Working Group. Working Draft. URL: https://www.w3.org/TR/did-core/
* DID https://www.w3.org/TR/did-core/. Drummond Reed; Manu Sporny; Dave Longley; Christopher Allen; Ryan Grant; Markus Sabadello. Decentralized Identifier Working Group. Working Draft. URL: https://www.w3.org/TR/did-core/
+
* [OAuth2.FormPost] OAuth 2.0 Form Post Response Mode. M. Jones; B. Campbell. 2015. URL: https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html
[OAuth2.FormPost]
+
*[OAuth2.ResponseTypes] OAuth 2.0 Multiple Response Type Encoding Practices. B. de Medeiros, Ed.; M. Scurtescu; P. Tarjan; M. Jones. 2014. URL: https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html
*OAuth 2.0 Form Post Response Mode. M. Jones; B. Campbell. 2015. URL: https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html
+
*[OIDC.CIBA] OpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0 draft-02. G. Fernandez; F. Walter; A. Nennker; D. Tonge; B. Campbell. 2019. URL: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-ID1.html
*[OAuth2.ResponseTypes]
+
* [RFC7515] JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7515
OAuth 2.0 Multiple Response Type Encoding Practices. B. de Medeiros, Ed.; M. Scurtescu; P. Tarjan; M. Jones. 2014. URL: https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html
+
*[RFC7517] JSON Web Key (JWK). M. Jones. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7517
*[OIDC.CIBA]
+
*[RFC7797] JSON Web Signature (JWS) Unencoded Payload Option. M. Jones. IETF. February 2016. Proposed Standard. URL: https://tools.ietf.org/html/rf
OpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0 draft-02. G. Fernandez; F. Walter; A. Nennker; D. Tonge; B. Campbell. 2019. URL: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-ID1.html
 
[RFC7515]
 
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7515
 
[RFC7517]
 
JSON Web Key (JWK). M. Jones. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7517
 
[RFC7797]
 
JSON Web Signature (JWS) Unencoded Payload Option. M. Jones. IETF. February 2016. Proposed Standard. URL: https://tools.ietf.org/html/rf
 
  
 
===Other Material===
 
===Other Material===
 +
* The use case [https://wiki.idesg.org/wiki/index.php/User_Agent_in_the_Cloud User Agent in the Cloud] explores the deployment of a picker and perhaps more for the user in the cloud.
 
* [https://bitbucket.org/openid/connect/src/master/SIOP/draft-jones-self_issued_identifier.md Alternative version on OpenID] from Tom Jones
 
* [https://bitbucket.org/openid/connect/src/master/SIOP/draft-jones-self_issued_identifier.md Alternative version on OpenID] from Tom Jones
 
* [https://bitbucket.org/openid/connect/src/master/SIOP/ parent folder for SIOP docs on OpenID.net]
 
* [https://bitbucket.org/openid/connect/src/master/SIOP/ parent folder for SIOP docs on OpenID.net]
Line 424: Line 381:
 
[[Category:Standard]]
 
[[Category:Standard]]
 
[[Category:Identity]]
 
[[Category:Identity]]
 +
[[Category:User Experience]]
 
[[Category:Authentication]]
 
[[Category:Authentication]]
 
[[Category:Security]]
 
[[Category:Security]]
 +
[[Category:Best Practice]]

Latest revision as of 09:11, 22 October 2021

Full Title

Self-issued Identifiers in an OpenID Connect Context where there is a large choice among OpenID providers..

Also known as chooser or selector spec or as the Joint Authentication Management (JAM) specification or as a Vendor Relationship Manager.

Goals

  1. Allow users the choice of which identifier to use with a Relying Party in a world where thee number of options makes it hard for the Relying Party to list them all.
  2. Allow users to easily navigate back to a Relying Party without having to remember their choice when they registered, which could easily be over a year in the past.

Justification

There has never been much interest in User Experience among identifier standards developers. This wiki page attempts to address that. Some Commentary follows:

  • David Cahdwick
    I think the whole direction of this Picker is misguided because it assumes that users will be knowledgeable about their numerous identifiers and will want to manage them. I don't believe that users will want to choose identifiers or know anything about them. I believe that users are interested in their electronic credentials (the equivalent of today’s plastic cards) and the identities that go with these. Users typically don't care a jot about what identifier is being used to cryptographically link their identity attributes to an identifier: transient identifiers are the best at protecting the user’s privacy and the user won't have any idea what the identifier is in any particular transaction. So the user will not be choosing identifiers as this draft assumes.
  • Tom Jones
    I believe that there is a great deal of truth in David’s assertions about human’s desire for multiple identifier. The sad fact is i have ~100 of them today in spite of my desires to have none (they are typically called user names and each has their own lexical requirements). Without the help of a p/w manager i would not even be on atlassian at all. There are now ~100 DID methods. RPs will never to interested in supporting so many. How then to manage a world with ~100 digital identifiers per person? Doc Searls proposed a Vendor Relationship Manager (VRM) app, perhaps that would be a better word for what we are about?

Context

  1. Report of a method to improve a sign in User Experience from an RP site for first time signin with a self-issued ID than they can get with, say, Google or FB.
  2. Report of a method to improve a sign in when the user returns to the same site.

In both cases the user is given a choice on a "Selection" menu where options are related to something the user knows, which should be the identifiers that the user has enabled.

Terms and Abbreviations

Term Description
User An organic human being operating a computing device, typically a smartphone or laptop.
DID Decentralized Identifier as per DID.Core[1]
DID Document DID Document as per [DID.Core]
SIOP DID Self-Issued OpenID Connect Provider DID profile. Refers to a specific flavor(s) of Verification Method used in the OIDC SIOP flow.
JWT JSON Web Token as per [RFC7797]
JWE JSON Web Encryption as per [RFC7516]
JWS JSON Web Signature as per [RFC7515]
JWK JSON Web Key as per [RFC7517]
JWKS JWK Set as per [RFC7517]
OIDC OpenID Connect as per [OIDC.Core]
OAuth client Used synonymously with Relying Party (see RP)
OP OpenID Provider as per [OIDC.Core]
SIOP Self-Issued OpenID Provider as per [OIDC.Core] section 7.
RP Relying Party, as used in [OIDC.Core] for any website the relies on claims produced by a CP for example an OP.
CP Claims provider, Certificate Provider, Credential Provider, Credential Service Provider (CSP), etc.
Identity Wallet An application that is under the control and acts on behalf of the key credential holder. aka identity agent. can be a mobile app, browser extension/ plugin etc.
DID AuthN Refers to a method of proofing control over a DID for the purpose of authentication.
Verification Method a more recent name for one instance of a DID AuthN
Trust Authority A URL endpoint that contains the references that define, inter alia, the operation of the picker and of the wallets
Trusted Wallet code trusted by one or more Trust Authorities to protect user secrets and perhaps to validate user presence.
Identity Wallet An application that is under the control and acts on behalf of the key credential holder. aka identity agent. can be a mobile app, browser extension/ plugin etc.
JAM session The period of time from when the user clicks on a link in the RP until the UI for the wallet is accepted by the user.

More items, especially those related to the meaning of origin or site are on the wiki page PWA initiators.

Scope of Picker

There really is not any one location or scope of control that needs to be determined. A picker can be at one one of these levels of control.

  1. Family
  2. Individual
  3. Platform (Android, Apple, etc.)
  4. Device
  5. Wallet
  6. Identifier Friendly Name.

Also sync can be performed at the high levels so that an individual can sync all devices and wallets, or a platform can sync all devices (and keystores) that share that platform.

Problems

  1. As originally specified in section 7 of the OpenID Connect specification, there was a single end-point specified for the user. The implicit assumption here is that a user would only have a single wallet. That is not the way the world evolved.
  2. The Relying Party. RP cannot know all of the identifier providers at the user's disposal when the user first goes to the site. (Or returns anonymously.)
  3. The user may not remember if they have already registered at the RP or which identifier they used when they last went to the RP. (The assumption is that there is on RP cookie on the users device.
  4. The user may have a wide range of devices that they want to use as and where convenient to them.
  5. The current [Did.core] model does not address the user experience of having a number of identifiers that are completely unhelpful for user choice without some selection method they can understand.

User Experience

This section addresses an optimal user experience with no consideration of where the picker resides or how is is implemented. The following are the expected steps to use the picker, or chooser as it is now known.

  1. User determines that they want to have one or more self-issued identifiers.
  2. User will have already selected at least a few credentials that they wish to store. We will assume these two as a base use case:
    1. Driver's license
    2. Health card in SHC format
  3. User will chose a smart phone and a wallet or user agent app to begin the process. This choice may be dictated by their required credentials.
  4. The wallet will give the user the option to enable one (or more) federated choices, perhaps based on the federation logo on their favorite web sites. The user will be given an option to list one or more of their personal self-issued identifiers. NOTE - all of the federation data can (optionally) be stored on the user's device and not on the the chooser site. (At a future time we might be able to include the sharing of that data on multiple devices owned by the user.)
  5. The next time the user goes to a web site where they have no active cookie, that site should list the particular federation logos that they have joined.
  6. The user clicks on the logo and one of several actions will occur:
    1. The user as a single wallet with a single ID that is selected and the user is given the consent menu.
    2. The user may have more than one ID on more than one wallet that are known to be part of that federation and so the user is give a choice as to which ID to use with this web site.
  7. The user consent dialog will be presented by the wallet with a list of the data types that were requested by the web site. (It's possible in the future that some of the data elements that are not required can be de-selected by the user as is required by, at least, the California privacy legislation).
  8. The user clicks "OK" and the user is connected to the web site as a fully registered user.


FrameworkChooser.png

Solutions

  • This document describes a picker which can intercept a AuthZ request flowing from an RP and help the user select the appropriate wallet and perhaps even the appropriate identifier.
  • In all cases the user on a user agent (assumed here, without prejudice, to be a brewer) navigates to the Relying Party which displays one or more buttons that take the user to a picker which can be of any type located on any accessible site, include the device hosting the browser.

Device Based

  • The ideal place for the picker is the Password Manager in the browser, which can be loaded by the user, but that is painful at the start of 2021, so other solutions are needed in the short term.
  • The picker can be in a native app that assumes ownership of openid:// and sorts out the user choice on their own device. Unless a sharing solution were created, this would only work if the user had the app on every devices and initialized every device with their preferences.

Cloud Based

a cloud based solution is proposed for the sort term. The following discussion is based on a full could implementation but a web app solution would be a natural extension.

An everyday use case that the Decentralized Identity community identified is the sign-up or login with web applications. Nowadays, this is often achieved through social login schemes such as Google Sign-In. While the Decentralized Identity community has serious concerns about social login, the underlying protocol, OIDC, does not have these flaws by design. SIOP DID provides great potential by leveraging an Identity Wallet, e.g., as a smartphone app, on the web. This will increase and preserve the user’s privacy by preventing third-parties from having the ability to track which web applications a user is interacting with. SIOP focuses on the integration of Identity Wallets in the form of browser extensions/ plugins, or smartphone apps, it does not prevent implementers using the proposed flow in different scenarios as well, e.g., between two web services.

The main use case is to sign up with/ login (aka register) to an RP, i.e., website. It assumes the user operates a mobile or desktop browser or a browser-based app that can respond to SIOP requests.

The SIOP picker will eithe generate or pass trough the <SIOP Response> based on the specific DID method that the user choses. If required it can reconstitute or amend the request for transmission to the SIOP (wallet).The primary use case will install one or more identity wallets on the user smartphone.

This specification does not explicitly support any particular location for the picker. It is expected that both cloud-based and device based pickers will be enabled.

User Creates Choices

This is a series of actions that can involve:

  1. More that one device that protect user secrets in what is called here a Wallet.
  2. User may create any number of Identifiers on each wallet.
  3. User may wish to migrate or back-up the wallet on a number or devices.
  4. User may choose to include or exclude each Wallet' on any one of the user-controlled Wallets;
  5. No assumptions is made here about whether the devices are (1) smartphone (2) laptops, (3) user controlled servers, or (4) Wallet as a service. (Also called Mobile as a Service in the EU.
  6. Each Wallet is trusted on one ore more Trust Authorities.
  7. The RP gets to select the Trust Authorities that have the characteristics that will allow the RP to make a trust decsiion about users that seek to register with the RP.

Generate SIOP Request at the RP

The Redirect 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 following are taken directly from the OIDC. It is not clear that the RP will know or even care whether the request is to be filled by a SIOP when a picker is used. It may not even be necessary for the picker to be limited to SIOP requests.

The following is a non-normative example HTTP 302 redirect response from the Client, which flows through the picker to the User Agent to make an Authentication Request to the Authorization Endpoint.

 HTTP/1.1 302 Found
 Location: https://server.example.com/authorize?
   response_type=code
   &scope=openid%20profile%20email
   &client_id=s6BhdRkqt3
   &state=af0ifjsldkj
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

The following is the non-normative example request that would be redirected through the User Agent to the Authorization Server in response to the HTTP 302 redirect response by the Client above:

 GET /authorize?
   response_type=code
   &scope=openid%20profile%20email
   &client_id=s6BhdRkqt3
   &state=af0ifjsldkj
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
 Host: server.example.com


RP Meta-data In contrast to other OIDC flows, e.g., Authorization Code Flow, RPs can provide client meta-data in the registration request parameter.

Request_object_signing_alg can be omitted. RPs implementing the DID AuthN profile MUST not use none for request_object_signing_alg.

There is no limitation placed on the ULR used by the client for identification. The JWKS MUST be provided in the jwks_uri or jwks entry of the registration parameter. Alternatively this can be handled by a DID doc.

RPs can decide to receive the SIOP Response encrypted. To enable encryption, the registration parameter MUST use id_token_encrypted_response_alg and id_token_encrypted_response_enc according to OIDC Client Metadata [OIDC.Registration].

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

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

Regular flow using a smartphone.

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 MAY 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.
OPTIONAL. response_context specifies whether the response should be returned to the callback URL in the context of an existing system browser session, or whether the response can be returned in a new/empty context (requested with a response_context of wallet). The default response_context is rp, indicating that the response should be submitted in the conext of the RP's existing system browser session.

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

EXAMPLE 3

{
  "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:

EXAMPLE 4

{
   "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"
   }
}

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):

EXAMPLE 5

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):

EXAMPLE 6

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

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:

EXAMPLE 7

{
  "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 Response> encryption:

EXAMPLE 8

{
   "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" ]
   }
}

Encryption JWE encryption MUST use Diffie-Hellman key agreement, i.e., algorithm ECDH-ES using the X25519 curve which uses direct key agreement with an ephemeral key. This means that a symmetric key is derived using Diffie-Hellman from the RP's public key and a randomly generated ephemeral private key. The corresponding ephemeral public key is included in the header of the JWE in the epk and the derived symmetric key is used to directly encrypt the JWT content. For symmetrically encrypting the content XChaCha20Poly1305 is used which has algorithm code XC20P.

The following is an example of the protected header of the resulting JWE:

EXAMPLE 9

{
  "alg": "ECDH-ES",
  "epk":
  {
    "kty": "OKP",
    "crv":"X25519",
    "x":"hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"
  }
  "enc": "XC20P",
  "kid": "did:example:0xab#key-1"
}

Note that the kid above denotes the DID and key of the RP, i.e., this public key is the key used by the sender together with the ephemeral private key in order to derive the shared secret. For the encryption the 24 bytes nonce field in the XChaCha20 algorithm is used as the initialization vector. The authentication tag is the MAC computed by the Poly1305 function. It is 16 bytes long.

The message to be encrypted is the JWT of the id_token, including header and signature. The JWT is encoded via base64url before encryption.

For the final encoding of the JWE the JWE Compact Serialization outlined in [RFC7516] is used. The structure of the message is as follows:

EXAMPLE 10
BASE64URL(JWE Protected Header) || '.' || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)
Note the two '.' characters above which indicates that the encrypted key is empty since we are using direct key agreement.

Processing the SIOP Request at the Picker

The Picker MUST validate the <SIOP Request> by following the Self-Issued ID Token Validation rules as per [OIDC.Core]. NOTE 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 Picker or SIOP MUST further validate the SIOP 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 Request. Verify the SIOP 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 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.

API for syncing picker data from the wallet to the picker

The need for a spec at this level seems helpful. No effort has been started by 2021-04-01

UX Considerations

The Picker will provide a UX with the user choices. This requires that a user (or user wallet) register their options the the picker. It is expected that such a registration API can be defined in some spec at a later time..

SIOP defines a custom URL scheme openid://. Mobile browsers would open the app that registered that scheme. Desktop browser extensions/ plugins have support for similar functionality. It is out of the scope of the spec under which circumstances a QR code will be rendered. One option will be to provide the QR code if the user is using the desktop browser, and no browser extension/ plugin is available.

On Android, the user can choose which app should open if multiple apps registered the same custom URL scheme. On iOS, the behavior is undefined. One approach would be to check if the user is on an iOS device and then, won't render the button if this is a concern. A fallback on iOS could be the use of custom mime types, but unusual UX has to be considered. Note, this issue is not specific to SIOP only but affects all apps using custom URL schemes. In case a QR Code is used where the user has to open the app first and has to scan the QR Code, this issue is mitigated.

Security Considerations

Threat: Interception of the Redirect URI If an attacker can cause the <SIOP Response> to be sent a URI under his control, he will directly get access to the fragment carrying the id_token.

This attack can be mitigated by hardening the RP, e.g., no support for the open redirector pattern.

Threat: Identity Token Leak in Browser History An attacker could obtain the <SIOP Response> from the browser's history.

This attack cannot be fully mitigated. It is RECOMMENDED to use short expiration times for id_token, and indicating that browsers should not cache the response.

Threat: Identity Token Leak to Third Party Scripts It is relatively common to use third-party scripts on RP pages, such as analytics tools, crash reporting. The author of the application may not be able to be fully aware of the entirety of the code running in the application. When a <SIOP Response> is returned in the fragment, it is visible to any third-party scripts on the page.

This attack could be mitigated by using trusted/ audited third party scripts on the RP's page, or browser-based app.

Countermeasures Use response_mode=form_post whenever possible to mitigate the risks described above. Under some circumstances, e.g., this will not be possible as such in the case of purely decentralized apps (dApp).

Threat: Session Fixation in Cross-Device Flow When the protocol begins on one device and ends on another, there is a risk that the cross-device transfer can be hijacked. For example, consider a flow that begins with the display of a QR code by the RP transfers to a mobile wallet when the user scans the QR code. In this scenario, an attacker can trick the user into scanning a QR code associated with a legitimate RP's sign-in request, thereby causing the user to authenticate within the context of the attacker's session.

Countermeasures Validate that the browser session in which the DID SIOP Response is submitted belongs to the same user as the browser session in which the DID SIOP Request was displayed. Even if these sessions are on different devices, the RP can take steps to ensure these belong to the same user (e.g., by checking whether an existing session exists or by asking the user to sign in through a non-SIOP means).

Additional Security Considerations

  • Putting user information in a central location creates a rich source of data that attackers can target. Metamask performed similar function crytocurrency that created a paradigm that attackers could follow to acquire user trust maleciously.[2]
  • The OWASP Foundation maintains a set of security recommendations and best practices for web applications, and it is RECOMMENDED to follow these best practices when creating an SIOP or RP based on this specification.

UX Considerations

  • It is expected that each trust federation will create their own picker, although a federation of federations is a distinct possibility.
  • The RP will need little change as the picker will appear to be a normal OIDC URL. It is expected that there will be additional text provided by the RP to inform the user as the the expectation on clicking a picker (federation) button.
  • For Native apps the URL Schema redirect can be overridden the the last app to request access.
  • For PWA (web apps) the URL is bound to the web site that installed the PWA, leading to exacerbations of the NASCAR logo problem.
  • For Web App installations, TBD - complex

OIDC Considerations

This work aims to be backward compatible with existing OIDC clients and OPs that implement the SIOP specification. Although the SIOP specification is part of the OIDC core specification, it is not widely adopted yet. One of the reasons was that not many apps existed that provided functionality we can find in Identity Wallets. Nevertheless, SIOP uses the same or similar request and response messages and should be easy to allow OIDC vendors to upgrade existing OIDC clients to support SIOP.

References

  1. W3C, Decentralized Identifiers (DIDs) v1.0. https://www.w3.org/TR/did-core
  2. Datid Canellis, PSA: MetaMask reveals your Ethereum address to sites you visit, here’s how to hide it Hard Fork | The Next Web (2019-03-22) https://thenextweb.com/hardfork/2019/03/22/metamask-ethereum-privacy-address/

Normative references

Informative references

Other Material