OIDC4VP profile for Login-with-IOTA
Login-with-IOTA is defined as a profile of the OpenID Connect for Verifiable Presentations specification [OIDC4VP], which defines the protocol for authorization using SSI, based on top of OAuth 2.0 [RFC6749] and introduces protocol extensions for the presentation of claims via Verifiable Credentials [VC_DATA_MODEL]. In this document we will describe the specifics of using the OIDC4VP protocol in the scope of Login-with-IOTA to ensure compatibility with the IOTA identity framework [IOTA_IDENTITY].
The IOTA identity framework [IOTA_IDENTITY] defines a custom DID method [IOTA_DID], based on the public key of the user account. The key material used is an EdDSA/Ed25519 [RFC8032] key pair.
To ensure compatibility with the IOTA identity framework [IOTA_IDENTITY], the issuers and holders of verifiable credentials should use a did:iota for issuance and as credential subject.
The credentials used by the IOTA identity framework [IOTA_IDENTITY] are in line with the W3C specification for Verifiable Credentials [VC_DATA_MODEL]. Every type of credential, that is compatible with the W3C specification, should in theory be supported.
Proofs for the credentials are created in the linked data format, ldp_vc or ldp_vp, as described by the W3C data integrity specification [VC_DATA_INTEGRITY], using [JSON-LD] as the credential format and the JCS Ed25519 Signature 2020 [JcsEd25519Signature2020] signature type.
This Login-with-IOTA profile of the [OIDC4VP] specification supports only W3C Verifiable Credentials [VC_DATA_MODEL].
Like described by [OIDC4VP], verifiable presentations can be requested by adding the
presentation_definitionparameter to the authorization request. The presentation is returned in the
Both, same-device and cross-device flows are supported by this profile. For cross-device scenarios [OIDC4VP] introduces a new response mode
post, to support verifier initiated verification.
The parameters for a Login-with-IOTA authorization request, are a subset of the parameters defined by the [OIDC4VP] specification:
response_type: REQUIRED. this parameter is defined in [RFC6749]. The possible values are determined by the response type registry established by [RFC6749]. This specification introduces the response type
vp_token. This response type asks the Authorization Server (AS) to return only a VP Token in the Authorization Response.
presentation_definition: CONDITIONAL. A string containing a presentation_definition JSON object as defined in Section 4 of [DIF.PresentationExchange].
presentation_definition_uri: CONDITIONAL. A string containing a URL pointing to a resource where a
presentation_definitionJSON object as defined in Section 4 of [DIF.PresentationExchange] can be retrieved .
nonce: REQUIRED. This parameter follows the definition given in [OIDC]. It is used to securely bind the verifiable presentation(s) provided by the AS to the particular transaction.
state: OPTIONAL. State provided by the authorization client, that is passed through to the response.
A request MUST contain either a
presentation_definition_uri. Those two ways to request credential presentations are mutually exclusive. The wallet MUST refuse any request violating this requirement.
presentation_definitionparameter must contain a JSON representation of a Presentation Definition object, according to the DIF Presentation Exchange specification [DIF.PresentationExchange].
Alternatively the request could contain the
presentation_definition_uriparameter, containing a URL to a presentation definition object.
The following example shows a presentation definition object, requesting the presentation of a
"id": "vp token example",
"id": "verifiable id credential",
This is an example authorization request:
The response parameters depend on the
response_typedefined in the authorization request. Possible response parameters include:
presentation_submission: The presentation submission object, as defined in [DIF.PresentationExchange], which links the input descriptors of the presentation definition in the request to the corresponding presentation(s) in the
state: Optional state parameter passed through from the authorization request.
Depending of the
response_typegiven in the authorization request, the response should contain the following parameters, like described in section 6.1 of [OIDC4VP]:
- If only
vp_tokenis used as the
response_type, the VP Token is provided in the authorization response.
id_tokenis used as the
vp_token, the VP Token is provided in the OpenID Connect authentication response along with the ID Token.
- In all other cases, if
vp_tokenis not used, but
presentation_definitionparameter is present, the VP Token is provided in the Token Response.
Any combination of
vp_tokenresponse parameter contains the verifiable presentation or array of verifiable presentations, matching the input descriptors of the presentation definition, specified in the authorization request.
The presentation submission object contains the correlations of the input descriptors, specified in the presentation definition of the authorization request, with the verifiable presentations in the VP token of the response. The format of the presentation submission objects is defined in section 6 of [DIF.PresentationExchange].
This is an example response for the
respones_type=vp_tokenrequest parameter, with the
HTTP/1.1 302 Found
vp_token, containing a presentation with a VerifiableId credential:
For the same device flow, the verifier or relying party, links directly to the authorization endpoint of the wallet, passing the request parameters, as specified in the Authorization request section.
response_modeshould be set to
form_post. After getting the user consent, the wallet will generate the response parameters, as specified in the Authorization response section, and performs a HTTP FORM POST action to the
redirect_urispecified in the authorization request. The relying party can now verify the authorization response and redirect the user to the protected web page.
For the cross-device flow, the verifier or relying party initiates an internally cached authorization session and displays a QR code containing the authorization request URI with the request parameters, as specified in the Authorization request section.
response_modeshould be set to
post. The wallet scans the QR code and parses the authorization request. After getting the user consent, the wallet will generate the response parameters, as specified in the Authorization response section, and posts the response to the
redirect_urispecified in the authorization request, via the HTTP POST method. The relying party can now verify the authorization response and update the state of the internally cached authorization session. Depending on the concrete implementation (for example by polling for the session state), the relying party UI can now be refreshed and redirected to the protected page.
Terbu, O., Lodderstedt, T., Yasuda, K., Lemmon, A., Looker, T., "OpenID for Verifiable Presentations", September 2022, https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, https://www.rfc-editor.org/info/rfc6749
Sporny, M., Longley, D., Chadwick, D., "Verifiable Credentials Data Model v1.1", March 2022, https://www.w3.org/TR/vc-data-model/
Millenaar, J., IOTA Foundation, "IOTA DID Method Specification", https://wiki.iota.org/identity.rs/specs/did/iota_did_method_spec/
Josefsson, S.; Liusvaara, I. (January 2017). Edwards-Curve Digital Signature Algorithm (EdDSA). IRTF. doi:10.17487/RFC8032. ISSN 2070-1721. RFC 8032. https://datatracker.ietf.org/doc/html/rfc8032
Longley, D., Sporny, M., "Verifiable Credential Data Integrity 1.0", https://w3c.github.io/vc-data-integrity/
Sporny, M., Longley, D., Kellog, G., Lanthaler, M., Champin, P., Lindström, N., "JSON-LD 1.1", https://www.w3.org/TR/json-ld11/
Cohen, G., Steele, O, Decentralized Identity Foundation, "JCS Ed25519 Signature 2020", https://identity.foundation/JcsEd25519Signature2020/
N. Sakimura, J. Bradley, M. Jones, B. de Medeiros, C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", November 8, 2014, https://openid.net/specs/openid-connect-core-1_0.html
K. Yasuda, M. Jones, T. Lodderstedt, "Self-Issued OpenID Provider v2", September 2022, https://openid.bitbucket.io/connect/openid-connect-self-issued-v2-1_0.html
Buchner, D., Zundel, B., Riedel, M., and K. H. Duffy, "Presentation Exchange 2.0.0", , https://identity.foundation/presentation-exchange/spec/v2.0.0/.