We apologize that our current implementation does not yet support the Stardust Upgrade from IOTA. As such, you cannot issue or verify credentials associated via a did:iota. Please refer to our roadmap for more information on when our products will be updated to include this latest changes.
Authors: Severin Stampler (walt.id) December 2022
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.
The [OIDC4VP] specification is based on top of OAuth 2.0 [RFC6749], which enables implementers to also build on top of OpenID Connect [OIDC] and the Self-issued OpenId Provider specification [SIOPv2].
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_definition parameter to the authorization request. The presentation is returned in the vp_token response parameter.
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_definition JSON 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 or a presentation_definition_uri. Those two ways to request credential presentations are mutually exclusive. The wallet MUST refuse any request violating this requirement.
The presentation_definition parameter 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_uri parameter, containing a URL to a presentation definition object.
The following example shows a presentation definition object, requesting the presentation of a VerifiableId credential:
This is an example authorization request:
The response parameters depend on the response_type defined in the authorization request. Possible response parameters include:
id_token: The ID token as defined by section 2 of the [OIDC] core specification.
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 vp_token response.
state: Optional state parameter passed through from the authorization request.
Depending of the response_type given in the authorization request, the response should contain the following parameters, like described in section 6.1 of [OIDC4VP]:
If only vp_token is used as the response_type, the VP Token is provided in the authorization response.
If id_token is used as the response_type alongside vp_token, the VP Token is provided in the OpenID Connect authentication response along with the ID Token.
In all other cases, if vp_token is not used, but presentation_definition parameter is present, the VP Token is provided in the Token Response.
Any combination of vp_token with a response_type other than id_token is undefined.
The vp_token response parameter contains the verifiable presentation or array of verifiable presentations, matching the input descriptors of the presentation definition, specified in the authorization request.
The only supported format of the verifiable presentation in this specification is the [ldp_vp] / [JSON-LD] format. The JSON data can be either a single presentation object or an array of JSON objects and must be URL encoded.
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_token request parameter, with the presentation_submission and vp_token response parameters:
An example vp_token, containing a presentation with a VerifiableId credential:
An example presentation_submission object:
For creating compliant error responses, please refer to section 6.3 of [OIDC4VP].
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.
The response_mode should 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_uri specified 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.
The response_mode should 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_uri specified 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/
IOTA Foundation, "IOTA Identity Framework Guide", https://wiki.iota.org/identity.rs/introduction/
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/.