docs/index.html

<!DOCTYPE html>
<html>
<head>
    <meta charset='utf-8'>
    <title>Self-Issued OpenID Connect Provider DID Profile v0.1 (DEPRECATED)</title>
    <link rel="icon" type="image/png" sizes="16x16" href="images/favicon-16x16.png">
    <style>
      #subtitle ~ h2,
      .copyright,
      #sotd p:first-of-type {
        display: none;
      }
    </style>

    <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>

    <script class='remove' src="./common.js"></script>

    <script class='remove'>
      var respecConfig = {
        subtitle: "DIF Working Group Draft",
        wg: "Authentication Working Group",
        logos: [{
          src: 'https://raw.githubusercontent.com/decentralized-identity/decentralized-identity.github.io/master/images/logo-large.png',
          href: "https://identity.foundation/",
          alt: "Decentralized Identity Foundation",
          width: 200,
          id: 'dif-logo',
        }],
        editors: [{
          name: "Oliver Terbu",
          url: "https://www.linkedin.com/in/oliver-terbu/",
          company: "uPort | ConsenSys",
          companyURL: "https://uport.me/"
        }
        ],
        authors: [{
          name: "Oliver Terbu",
          url: "https://www.linkedin.com/in/oliver-terbu/",
          company: "uPort | ConsenSys",
          companyURL: "https://uport.me/"
        },
        {
          name: "Ivan Basart",
          url: "https://www.linkedin.com/in/ivanbasart/",
          company: "Validated ID",
          companyURL: "https://www.validatedid.com/"
        },
        {
          name: "Kyle Den Hartog",
          url: "https://www.linkedin.com/in/kyledenhartog/",
          company: "Mattr",
          companyURL: "https://mattr.global/"
        },
        {
          name: "Christian Lundkvist",
          url: "https://www.linkedin.com/in/chrislun/",
          company: "ConsenSys",
          companyURL: "https://consensys.net/"
        },
        {
          name: "David Stark",
          url: "https://www.linkedin.com/in/david-stark-a3bb40/",
          company: "SecureKey",
          companyURL: "https://securekey.com/"
        },
        {
          name: "Dmitri Zagidulin",
          url: "https://www.linkedin.com/in/dzagidulin/",
          company: "Digital Bazaar",
          companyURL: "https://digitalbazaar.com/"
        },
        {
          name: "Danny Strockis",
          url: "https://www.linkedin.com/in/dannystrockis/",
          company: "Microsoft",
          companyURL: "https://www.microsoft.com/en-us/security/technology/own-your-identity"
        },
        {
          name: "Orie Steele",
          url: "https://www.linkedin.com/in/or13b/",
          company: "Transmute",
          companyURL: "https://www.transmute.industries/"
        }],
        github: "https://github.com/decentralized-identity/did-siop",
        edDraftURI: "https://identity.foundation/did-siop/",
        shortName: "did-siop",
        localBiblio: siop.localBiblio
      };
    </script>
</head>

<body>

<section id="abstract">
    <h2>Abstract</h2>
    <p>
        This specification defines the "SIOP DID Profile" (<a href="did-siop">SIOP DID</a>) that is a
        <a href="#did-authn">DID AuthN</a> flavor to use
        OpenID Connect (<a href="#oidc">OIDC</a>) together with the strong decentralization, privacy and security
        guarantees of Decentralized Identifiers (<a href="#did">DID</a>) for everyone who wants to have a generic
        way to integrate <a href="#identity-wallet">Identity Wallets</a> into their web applications.
    </p>
</section>

<section id='sotd'>
    <p>
        <a href="did-siop">SIOP DID</a> is an unapproved DIF working group draft specification and now being DEPRECATED within the
        <a href="https://identity.foundation"> Decentralized Identity Foundation</a> (DIF).
    </p>

    <div class="issue">
        The work on DIF SIOP DID Profile specification has moved to OIDF AB WG to work on a number of new specifications in the course of the DIF/OIDF liaison:
        <ul>
            <li><a href="https://openid.net/specs/openid-connect-4-verifiable-presentations-1_0.html">OpenID Connect for Verifiable Presentations</a></li>
            <li><a href="https://openid.net/specs/openid-connect-self-issued-v2-1_0.html">SIOP V2</a></li>
        </ul>
    </div>

</section>

<section class="informative">
    <h1>Terminology</h1>
    <table class="simple">
        <thead>
        <tr>
            <th style="min-width: 8em;">Term</th>
            <th>Description</th>
        </tr>
        </thead>
        <tbody>
        <tr>
            <td id="did">DID</td>
            <td>Decentralized Identifier as per [[DID]]</td>
        </tr>
        <tr>
            <td id="did-document">DID Document</td>
            <td>DID Document as per [[DID]]</td>
        </tr>
        <tr>
            <td id="did-siop">SIOP DID</td>
            <td>Self-Issued OpenID Connect Provider DID profile. Refers to a specific flavor of DID AuthN used in the
                OIDC SIOP flow.</td>
        </tr>
        <tr>
            <td id="jwt">JWT</td>
            <td>JSON Web Token as per [[RFC7797]]</td>
        </tr>
        <tr>
            <td id="jwe">JWE</td>
            <td>JSON Web Encryption as per [[RFC7516]]</td>
        </tr>
        <tr>
            <td id="jws">JWS</td>
            <td>JSON Web Signature as per [[RFC7515]]</a></td>
        </tr>
        <tr>
            <td id="jwk">JWK</td>
            <td>JSON Web Key as per [[RFC7517]]</a></td>
        </tr>
        <tr>
            <td id="jwks">JWKS</td>
            <td>JWK Set as per [[RFC7517]]</td>
        </tr>

        <tr>
            <td id="oidc">OIDC</td>
            <td>OpenID Connect as per [[?OIDC.Core]]</td>
        </tr>
        <tr>
            <td id="oidc-client">OIDC client</td>
            <td>Used synonymously with Relying Party (see <a href="#rp">RP</a>)</td>
        </tr>

        <tr>
            <td id="op">OP</td>
            <td>OpenID Provider as per [[?OIDC.Core]]</td>
        </tr>
        <tr>
            <td id="siop">SIOP</td>
            <td>Self-Issued OpenID Provider as per [[?OIDC.Core]]</td>
        </tr>
        <tr>
            <td id="rp">RP</td>
            <td>Relying Party, as used in [[?OIDC.Core]]</td>
        </tr>
        <tr>
            <td id="identity-wallet">Identity Wallet</td>
            <td>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.</td>
        </tr>
        <tr>
            <td id="did-authn">DID AuthN</td>
            <td>Refers to a method of proofing control over a DID for the purpose of authentication.</td>
        </tr>

        </tbody>
    </table>
</section>

<section class="informative">
    <h1>
        Introduction
    </h1>

    <p>
        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,
        <a href="#oidc">OIDC</a>, does not have these flaws by design. <a href="#did-siop">SIOP DID</a> provides
        great potential by leveraging an <a href="#identity-wallet">Identity Wallet</a>,
        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.
    </p>
    <p class="note">
        While this specification focuses on the integration of <a href="#identity-wallet">Identity Wallets</a>
        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
        <a href="#did">DIDs</a>.
    </p>

    <section class="informative">
        <h2>
            Purpose
        </h2>

        <p>
            The main purpose is to sign up with/ login to an <a href="#rp">RP</a>, i.e., web application. It assumes
            the user operates a mobile or desktop browser or a browser-based app that can respond to
            <a href="#siop">SIOP</a> requests according to this specification.
        </p>

        <p class="note">
            The <a href="#siop">SIOP</a> flow is conducted peer-to-peer between the <a href="#rp">RP</a> and the
            <a href="#siop">SIOP</a>. This could be used to authenticate holders based on their <a href="#did">DID</a>,
            to setup/ bootstrap a DID Comm connection with any <a href="#did">DID</a> routing that you may need, or to
            provide the <code>login_hint</code> to an OpenID Connect service in the <a href="#did-document">DID Document</a>
            supporting the Client-Initiated Backend Channel (CIBA) as per [[?OIDC.CIBA]].
        </p>

    </section>

    <section class="informative">
        <h2>
            Goals
        </h2>

        <p>
            The main goals of this specification are:
        </p>
        <ul>
            <li>
                Staying backward compatible with existing <a href="#oidc-client">OIDC clients</a> and
                <a href="#op">OPs</a> that implement the <a href="#siop">SIOP</a> specification which is part of the
                <a href="oidc">OIDC</a> core specification as per [[?OIDC.Core]] to reach a broader community.
            </li>
            <li>
                Adding validation rules for <a href="#oidc-client">OIDC clients</a> that have
                <a href="#did-authn">DID AuthN</a> support to make full use of <a href="#did">DIDs</a>.
            </li>
            <li>
                Not relying on any intermediary such as a traditional centralized public or private
                <a href="#op">OP</a> while still being <a href="#oidc">OIDC</a>-compliant.
            </li>
        </ul>
    </section>
</section>

<section class="normative">
    <h1>Protocol Flow</h1>
    <p>
        This specification assumes, the user is operating a mobile or desktop browser to visit a web application or uses
        a browser-based app.
    </p>
    <p>
        First, the user clicks on the sign up or login UX element. The <a href="#rp">RP</a> will then generate the
        redirect to <code>openid://&lt;SIOP Request&gt;</code> which will be handled by the <a href="#siop">SIOP</a>.
    </p>

    <p class="note">
        On the mobile device, this would open the <a href="#identity-wallet">Identity Wallet</a> app, e.g., uport,
        connect.me. On the desktop browser, this would either show a QR code which can be scanned by the
        <a href="#identity-wallet">Identity Wallet</a> app or a redirect to <code>openid://&lt;SIOP Request&gt;</code>
        that for instance could be handled by a browser extension/ plugin implementing the <a href="#siop">SIOP</a>.
    </p>

    <p>
        The <a href="#siop">SIOP</a> will generate the <code>&lt;SIOP Response&gt;</code> based on the specific
        <a href="#did">DID</a> method that is supported. The <code>&lt;SIOP Response&gt;</code> will be signed and
        optionally encrypted and will be provided according to the requested response mode.
    </p>

    <p>
        This specification does not explicitly support any intermediate hubs or cloud agents. It is meant to be a
        protocol to exchange the <a href="#did">DID</a>. You could then interact with a hub/ cloud agent using the
        service endpoint in the <a href="#did-document">DID Document</a>.
    </p>

    <p>
        Unlike the <a href="#oidc">OIDC</a> Authorization Code Flow as per [[!OIDC.Core]], the <a href="#siop">SIOP</a>
        will not return an access token to the <a href="#rp">RP</a>. If this is desired, this could be achieved by
        following the aforementioned CIBA flow as per [[?OIDC.CIBA]] in addition. <a href="#siop">SIOP</a> also
        differs from Authorization Code Flow by not relying on a centralized and known
        <a href="#op">OP</a>. The <a href="#siop">SIOP</a> can be unknown to the <a href="#rp">RP</a> until the
        user starts to interact with the <a href="#rp">RP</a> using its <a href="#identity-wallet">Identity Wallet</a>.
        <a href="#oidc">OIDC</a> Authorization Code Flow is still a useful approach and should be used whenever the
        <a href="op">OP</a> is known, and <a href="#op">OP</a> discovery is possible, e.g., exchanged or pre-populated
        <a href="#did-document">DID Document</a> containing an openid element in the service section.
        The <a href="#siop">SIOP</a> flow allows to integrate <a href="#identity-wallet">Identity Wallets</a> with
        plain <a href="oidc-client">OIDC clients</a> if they implemented the <a href="#siop">SIOP</a> specification.
        In contrast, using <a href="#did-authn">DID AuthN</a> as the authentication means in the <a href="oidc">OIDC</a>
        Authorization Code Flow would require integration with the <a href="op">OP</a> vendor itself.
    </p>

    <figure id="protocol-flow">
        <img style="margin: auto; display: block; width: 100%;"
             src="assets/did_authn_siop_profile_flow.png" alt="Example SIOP flow with a mobile browser as the User-Agent
              and an Identity Wallet app as the SIOP.">
        <figcaption style="text-align: center;">
            Example <a href="#siop">SIOP</a> flow with a mobile browser as the User-Agent and an
            <a href="#identity-wallet">Identity Wallet</a> app as the <a href="#siop">SIOP</a>.
        </figcaption>
    </figure>

    <section>
        <h2>Generate SIOP Request</h2>
        <h3>Redirect Request</h3>
        <p>
            The request contains <code>scope</code>, <code>response_type</code> and <code>client_id</code> as query
            string parameters for backward compatibility with the OAuth2 specification [[!RFC6749]].
            <code>response_type</code> MUST be <code>id_token</code> and <code>client_id</code> MUST specify the
            redirect URI of the <a href="#rp">RP</a> (as per [[!OIDC.Core]]). All other <a href="#oidc">OIDC</a>
            request parameters MUST be provided in an Request Object as per [[!OIDC.Core]] which is encoded as a JWT.
            This enables the <a href="#rp">RP</a> to authenticate against the <a href="#siop">SIOP</a> using the
            <a href="#rp">RP's</a> <a href="#did">DID</a>. The Request Object can be passed by value in the
            <code>request</code> request parameter, or by reference using the <code>request_uri</code> parameter.
        </p>

        <pre class="example nohighlight">
            openid://?response_type=id_token
                &client_id=https%3A%2F%2Frp.example.com%2Fcb
                &scope=openid%20did_authn
                &request=&lt;JWT&gt;
        </pre>

        <p>
            In the example above the <a href="#did-authn">DID AuthN</a> <code>&lt;SIOP Request&gt;</code> is initiated
            by the <a href="#rp">RP</a> using Request Object by value.
        </p>

        <pre class="example nohighlight">
            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
        </pre>

        <p>
            In the example above the <a href="#did-authn">DID AuthN</a> <code>&lt;SIOP Request&gt;</code> is initiated
            by the <a href="#rp">RP</a> using Request Object by reference.
        </p>

        <h3>RP Metadata</h3>
        <p>
            In contrast to other <a href="#oidc">OIDC</a> flows, e.g., Authorization Code Flow, <a href="#rp">RPs</a>
            can provide client metadata in the <code>registration</code> request parameter. Clients MAY include
            any registration metadata parameters defined in <a href="https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata"
            >OpenID Connect Registration 1.0</a>, and servers MAY use these parameters as they see fit.
        </p>

        <p>
            In addition to <code>RS256</code>, an <a href="#siop">SIOP</a> according to this specification MUST support
            <code>EdDSA</code> and <code>ES256K</code> [[!draft-ietf-cose-webauthn-algorithms-03]] for
            <code>request_object_signing_alg</code> and <code>request_object_signing_alg</code> can be omitted.
            <a href="#rp">RPs</a> implementing the <a href="#did-authn">DID AuthN</a> profile MUST not use
            <code>none</code> for <code>request_object_signing_alg</code>.
        </p>

        <p>
            The Request Object MUST be directly or indirectly verifiable by a verification method in the
            <a href="#rp">RP's</a> <a href="#did-document">DID Document</a> and directly by the <a href="#rp">RP's</a>
            JWKS. The JWKS MUST be provided in the <code>jwks_uri</code> or <code>jwks</code> entry of the
            <code>registration</code> parameter. The JWKS MUST contain an entry with a <code>kid</code> that matches
            the <code>kid</code> in the Request Object. <code>jwks_uri</code> MUST use the HTTP(S) DID Resolution
            Binding as per [[DID.Resolution]] for backward compatibility reasons with plain <a href="#siop">SIOP</a>
            <a href="#op">OPs</a>. The <code>jwks</code> request parameter SHOULD be used only if the public key cannot
            be directly obtained from the <a href="#did-document">DID Document</a>.
        </p>

        <p>
            <a href="#rp">RPs</a> can decide to receive the <code>SIOP Response</code> encrypted. To enable encryption,
            the registration parameter MUST use <code>id_token_encrypted_response_alg</code> and
            <code>id_token_encrypted_response_enc</code> according to <a href="oidc">OIDC</a> Client Metadata
            [[!OIDC.Registration]]. This specification RECOMMENDS the use of `ECDH-ES` with the `X25519` curve for JWE
            as explained in section <a href="#encryption">Encryption</a> and described in
            [[!draft-amringer-jose-chacha-00]].
        </p>

        <h3>Request Object</h3>
        <p>
            The Request Object follows the <a href="#oidc">OIDC</a> specification, e.g., adding <code>nonce</code>,
            <code>state</code>, <code>response_type</code>, and <code>client_id</code> parameters.
        </p>

        <p>
            The request contains <code>scope</code>, <code>response_type</code> and <code>client_id</code> as query
            string parameters for backward compatibility with the OAuth2 specification [[!RFC6749]].
            <code>response_type</code> MUST be <code>id_token</code> and <code>client_id</code> MUST specify the
            redirect URI of the <a href="#rp">RP</a> (as per [[!OIDC.Core]]). All other <a href="#oidc">OIDC</a>
            request parameters MUST be provided in an Request Object as per [[!OIDC.Core]] which is encoded as a JWT.
            This enables the <a href="#rp">RP</a> to authenticate against the <a href="#siop">SIOP</a> using the
            <a href="#rp">RP's</a> <a href="#did">DID</a>. The Request Object can be passed by value in the
            <code>request</code> request parameter, or by reference using the <code>request_uri</code> parameter.
        </p>

        <p>
            The Request Object follows the <a href="#oidc">OIDC</a> specification, e.g., adding <code>nonce</code>,
            <code>state</code>, <code>response_type</code>, and <code>client_id</code> parameters.
        </p>

        <p>
            This specification introduces additional rules for request parameters and claims in the Request Object:
        </p>

        <ul>
            <li>
                REQUIRED. <code>iss</code> MUST contain the <a href="#did">DID</a> of the <a href="#rp">RP</a> that can
                be resolved to a <a href="#did-document">DID Document</a>. The <a href="#did-document">DID Document</a>
                MUST contain a verification method in the authentication section, e.g., public key, that allows the
                <a href="#siop">SIOP</a> to verify the Request Object.
            </li>
            <p class="note">
                By default, the <code>iss</code> claim refers to the <code>client_id</code> but <a href="#siop">SIOP</a>
                assumes that <code>client_id</code> is the redirect URI of the <a href="#rp">RP</a>. That is the reason
                why the <a href="#did">DID</a> is not encoded in the <code>client_id</code>. It is compliant with the
                <a href="#oidc">OIDC</a> specification to use different values for <code>iss</code> and
                <code>client_id</code>.
            </p>

            <li>
                REQUIRED. <code>kid</code> MUST be a DID URL referring to a verification method in the authentication
                section in the <a href="#rp">RP's</a> <a href="#did-document">DID Document</a>, e.g.,
                <code>did:example:0xab#key1</code>. The <a href="#siop">SIOP</a> MUST be able to use that verification
                method to verify the Request Object directly or indirectly. Additionally, the referred JWKS in the
                <code>registration</code> parameter MUST contain an entry with the same <code>kid</code>.
            </li>
            <li>
                REQUIRED. <code>scope</code> MUST include <code>did_authn</code> to indicate the <a href="#did-siop">
                SIOP DID </a> profile is used.
            </li>
            <li>
                REQUIRED. <code>registration</code> MUST be included in the Request Object
            </li>
            <li>
                REQUIRED. <code>client_id</code> MUST be repeated in the Request Object
            </li>
            <li>
                OPTIONAL. <code>response_mode</code> specifies how the response is returned to the redirect URI by the
                <a href="#siop">SIOP</a>. <a href="#siop">SIOP</a> implementing this specification MAY set the
                <code>response_mode</code> to <code>form_post</code>. <code>fragment</code> is the default
                Response Mode. <a href="#rp">RPs</a> MUST take into consideration the platform of the
                User-Agent when specifying this request parameter.
            </li>
            <p class="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 <code>response_mode</code>.
            </p>
            <li>
                OPTIONAL. <code>response_context</code> specifies whether the response should be returned to the
                redirect URI in the context of an existing system browser session, or whether the response can be
                returned in a new/empty context (requested with a <code>response_context</code> of <code>wallet</code>).
                The default <code>response_context</code> is <code>rp</code>, indicating that the response should be submitted
                in the conext of the RP's existing system browser session.
            </li>
            <p class="note">
                A <code>response_context</code> of <code>wallet</code> 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.
            </p>
            <li>
                OPTIONAL. <code>claims</code> follows the
                <a href="https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter">OIDC Core schema</a>,
                adding a top-level <code>vc</code> property as a sibling to (and following the schema of) <code>id_token</code>
                and <code>userinfo</code>. Requesting claims within the <code>vc</code> set indicates that the requesting party
                would like to receive (if <code>essential</code> is <code>false</code>), or requires (if <code>true</code>)
                a specific set of verifiable credential types within the <code>.vp.verifiableCredential</code> array of the
                SIOP Response. Specific [VC types](https://www.w3.org/TR/vc-data-model/#types) are identified using the VC type's full URI. 
            </li>
            <p class="note">
                When providing claims in this manner, the SIOP Response acts as a W3C Verifiable Presentation; requested claims
                are provided in the Response by populating the array of Verifiable Credentials within the Presentation.
            </p>
        </ul>

        <p>
            The following is a non-normative example of the JWT header of a Request Object:
        </p>
        <pre class="example nohighlight">
            {
                "alg": "ES256K",
                "typ": "JWT",
                "kid": "did:example:0xab#veri-key1"
            }
        </pre>

        <p>
            The following is a non-normative example of the JWT payload of a Request Object without requesting
            <code>&lt;SIOP DID Response&gt;</code> encryption:
        </p>
        <pre class="example nohighlight">
            {
                "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"
                }
            }
        </pre>

        <p>
            The following is a non-normative example HTTP 302 redirect response by the <a href="#rp">RP</a>, which
            triggers the User-Agent to make an <a href="siop-did">SIOP DID</a> Authentication Request using Request
            Object by value to the <a href="#siop">SIOP</a> (with line wraps within values for display purposes
            only):
        </p>
        <pre class="example nohighlight">
            HTTP/1.1 302 Found
            Location: openid://?
                &client_id=https%3A%2F%2Frp.example.com%2Fcb
                &scope=openid%20did_authn
                &request=&lt;JWT&gt;
        </pre>

        <p>
            The following is a non-normative example HTTP 302 redirect response by the <a href="#rp">RP</a>, which
            triggers the User-Agent to make an <a href="siop-did">SIOP DID</a> Authentication Request using Request
            Object by reference to the <a href="#siop">SIOP</a> (with line wraps within values for display purposes
            only):
        </p>
        <pre class="example nohighlight">
            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
        </pre>

        <h3 id="encryption">Encryption</h3>
        <p>
            JWE encryption SHOULD 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 <a href="#rp">RP's</a> 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`.
        </p>

        <p>
            The following is an example of the protected header of the resulting JWE:
        </p>

        <pre class="example nohighlight">
            {
                "alg": "ECDH-ES",
                "epk":
                {
                    "kty": "OKP",
                    "crv":"X25519",
                    "x":"hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"
                }
                "enc": "XC20P",
                "kid": "did:example:0xab#key-1"
            }
        </pre>

        <p>
            Note that the `kid` above denotes the DID and key of the <a href="#rp">RP</a>, 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.
        </p>

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

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

        <pre class="example nohighlight">
            BASE64URL(JWE Protected Header) || '.' || '.' ||
            BASE64URL(JWE Initialization Vector) || '.' ||
            BASE64URL(JWE Ciphertext) || '.' ||
            BASE64URL(JWE Authentication Tag)
        </pre>

        <p>
            Note the two '.' characters above which indicates that the encrypted key is empty since we are
            using direct key agreement.
        </p>
    </section>    

    <section>
        <h2>SIOP Request Validation</h2>
        <p>
            The <a href="#siop">SIOP</a> MUST validate the <code>&lt;SIOP Request&gt;</code> by following the
            Self-Issued ID Token Validation rules as per [[!OIDC.Core]].
        </p>
        <p class="note">
            The step described above ensures that the Request Object is verified according to the
            <a href="#oidc">OIDC</a> specification. This includes basic JWS verification.
        </p>

        <p>
            If scope contains the <code>did_authn</code> scope, the receiving <a href="#siop">SIOP</a>
            MUST further validate the <code>&lt;SIOP Request&gt;</code> as follows in no particular order:
        </p>

        <ul>
            <li>
                Resolve the <a href="#did-document">DID Document</a> from the
                <a href="#rp">RP's</a> <a href="#did">DID</a> specified in the <code>iss</code> request parameter.
            </li>
            <li>
                If <code>jwks_uri</code> is present, ensure that the <a href="#did">DID</a> in the
                <code>jwks_uri</code> matches the <a href="#did">DID</a> in the <code>iss</code> claim.
            </li>
            <li>
                Determine the verification method from the <a href="#rp">RP's</a>
                <a href="#did-document">DID Document</a> that matches the <code>kid</code> of the
                <code>SIOP Request</code>.
            </li>
            <li>
                Verify the <code>SIOP Request</code> according to the verification method above. This step depends on
                the verification method in the authentication section in the <a href="#did-document">DID Document</a>
                and is out-of-scope of this specification.
            </li>
        </ul>

        <p class="note">
            If the key pair that signed the <code>SIOP Request</code> refers to the same key as indicated by the
            verification method, then no additional verification has to be done as the <a href="#siop">SIOP</a>
            validation will verify the signature of the JWS.
        </p>
    </section>

    <section>
        <h2>Generate SIOP Response</h2>
        <p>
            The <a href="#siop">SIOP</a> MUST generate and send the <code>&lt;SIOP Response&gt;</code> to the
            <a href="#rp">RP</a> as described in the Self-Issued OpenID Provider Response section in [[!OIDC.Core]].
            The <code>id_token</code> represents the &lt;SIOP Response&gt; encoded as a JWS, or nested JWS/JWE.
        </p>

        <p>
            This specification introduces additional rules for claims in the <code>id_token</code>:
        </p>

        <ul>
            <li>
                REQUIRED. <code>sub_jwk</code> MUST contain a <code>kid</code> that is a DID URL referring to the
                verification method in the <a href="#siop">SIOP's</a> <a href="#did-document">DID Document</a> that can
                be used to verify the JWS of the <code>id_token</code> directly or indirectly.
            </li>
            <li>
                REQUIRED. <code>did</code> MUST be the <a href="#siop">SIOP's</a> <a href="#did">DID</a>.
            </li>
        </ul>

        <p class="note">
            The <code>sub_jwk</code> claim has to be provided for backward compatibility reasons. The verification
            method in the <a href="#did-document">DID Document</a> can be different from a public key and can use a
            <code>publicKey</code> property value other than <code>publicKeyJwk</code>.
        </p>

        <p>
            The following is a non-normative example of the JWT header of an <code>id_token</code> using no encryption:
        </p>

        <pre class="example nohighlight">
            {
                "alg": "ES256K",
                "typ": "JWT",
                "kid": "did:example:0xab#key-1"
            }
        </pre>

        The following is a non-normative example of the unencrypted JWT payload of an <code>id_token</code>:
        <pre class="example nohighlight">
            {
                "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"
            }
        </pre>
    </section>

    <section>
        <h2>SIOP Response Validation</h2>
        <p>
            The <a href="#rp">RP</a> MUST validate the <code>&lt;SIOP Response&gt;</code> as described in the
            Self-Issued ID Token Validation section in [[!OIDC.Core]]. This includes:
        </p>

        <ul>
            <li>
                Optionally decrypting the JWE to obtain the JWS which contains the <code>id_token</code>.
            </li>
            <li>
                Verifying that the <code>id_token</code> was signed by the key specified in the <code>sub_jwk</code>
                claim.
            </li>
        </ul>

        <p>
            Additionally, the <a href="#rp">RP</a> MUST validate the <code>id_token</code> against the
            <a href="#siop">SIOP's</a> <a href="#did-document">DID Document</a> as follows:
        </p>

        <ul>
            <li>
                Resolve the <a href="#did-document">DID Document</a> from the
                <a href="#siop">SIOP's</a> <a href="#did">DID</a> specified in the <code>did</code> claim.
            </li>
            <li>
                Determine the verification method from the <a href="#siop">SIOP's</a> <a href="#did-document">DID
                Document</a> that matches the <code>kid</code> of the <code>sub_jwk</code> claim in the
                <code>id_token</code>.
            </li>
            <li>
                Verify the <code>id_token</code> according to the verification method above. This step depends on the
                verification method in the authentication section in the <a href="#did-document">DID Document</a> and
                is out-of-scope of this specification.
            </li>
        </ul>

        <p class="note">
            If the key pair that signed the <code>id_token</code> refers to the same key as indicated by the
            verification method, then no additional verification has to be done as the <a href="#siop">SIOP</a>
            validation will verify the signature of the JWS.
        </p>
    </section>
    
    <section>
        <h2>SIOP Discovery</h2>
        <p>
            The <a href="#siop">SIOP</a> specification assumes the following OP discovery metadata:
        </p>
        <pre class="nohighlight">
            "id_token_signing_alg_values_supported": ["RS256"],
            "request_object_signing_alg_values_supported": ["none", "RS256"]
        </pre>

        <p>
            The <a href="#did-authn">DID AuthN</a> profile assumes the following OP discovery metadata:
        </p>
        <pre class="nohighlight">
            "id_token_signing_alg_values_supported": ["RS256", "ES256K", "EdDSA"],
            "request_object_signing_alg_values_supported":
                ["none", "RS256", "ES256K", "EdDSA"]
        </pre>

        <p>
            This change will allow <a href="#did-authn">DID AuthN</a> enabled <a href="#rp">RPs</a> to use additional
            signature algorithms commonly used amongst members of the SSI community.
        </p>
    
        <p class="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 <code>RS256</code> shouldn't break the
            <a href="#siop">SIOP</a> specification. A <a href="#did-authn">DID AuthN</a> enabled <a href="#rp">RP</a>
            would provide <code>id_token_signed_response_alg</code> to indicate its preferred signature algorithm
            among the three <code>id_token_signing_alg_values_supported</code> options listed above.
        </p>
        
    </section>
</section>

<section class="informative">
    <h1>UX Considerations</h1>

    <p>
        <a href="#siop">SIOP</a> uses the custom URL scheme <code>openid://</code>. 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.
    </p>

    <p>
        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 <a href="#siop">SIOP</a> 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.
    </p>
</section>

<section class="informative">
    <h1>Security Considerations</h1>
    <h2>Threat: Interception of the Redirect URI</h2>
    <p>
        If an attacker can cause the <code>&lt;SIOP Response&gt;</code> to be sent a URI under his control, he will
        directly get access to the fragment carrying the <code>id_token</code>.
    </p>
    <p>
        This attack can be mitigated by hardening the <a href="#rp">RP</a>, e.g., no support for the open redirector
        pattern.
    </p>

    <h2>Threat: Identity Token Leak in Browser History</h2>
    <p>
        An attacker could obtain the <code>&lt;SIOP Response&gt;</code> from the browser's history.
    </p>
    <p>
        This attack cannot be fully mitigated. It is RECOMMENDED to use short expiration times for
        <code>id_token</code>, and indicating that browsers should not cache the response.
    </p>

    <h2>Threat: Identity Token Leak to Third Party Scripts</h2>
    <p>
        It is relatively common to use third-party scripts on <a href="#rp">RP</a> 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 <code>&lt;SIOP Response&gt;</code> is returned in the fragment, it is visible to any
        third-party scripts on the page.
    </p>
    <p>
        This attack could be mitigated by using trusted/ audited third party scripts on the <a href="#rp">RP's</a> page,
        or browser-based app.
    </p>

    <h2>Countermeasures</h2>
    <p>
        Use <code>response_mode=form_post</code> 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).
    </p>

    <h2>Threat: Session Fixation in Cross-Device Flow</h2>
    <p>

        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 <a href="#rp">RP</a>
        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.

    <h2>Countermeasures</h2>
    <p>
        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).
    </p>

    <h2>Additional Security Considerations</h2>
    <p>
        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 <a href="#siop">SIOP</a> or <a href="#rp">RP</a>
        based on this specification.
    </p>
</section>

<section class="informative">
    <h1>IANA Considerations</h1>
    <p>
        This specification registers the <code>did</code> claim in the IANA JSON Web Token
        Claims registry defined in JWT.
    </p>
</section>

<section class="informative">
    <h1>OIDC Considerations</h1>
    <p>
        This specification aims to be backward compatible with existing <a href="#oidc-client">OIDC clients</a> and
        <a href="#op">OPs</a> that implement the <a href="#siop">SIOP</a> specification. Although the
        <a href="#siop">SIOP</a> 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
        <a href="#identity-wallet">Identity Wallets</a>. Nevertheless, <a href="#siop">SIOP</a> uses the same or similar
        request and response messages and should be easy to allow <a href="#oidc">OIDC</a> vendors to upgrade existing
        <a href="#oidc-client">OIDC</a> clients to support <a href="#siop">SIOP</a>.
    </p>
</section>

</body>

</html>