Skip to main content

APP to APP Authentication Flow

Introduction

The authentication process using Dizme involves a verification of credentials that is initiated by a verify request from the Customer Backend (BE) to the Dizme Stack "Credx". Typically, this verification request requires the verification of a member credential.

Process Overview

  1. Verify Request Initiation: The Customer Backend initiates a verify request to the Dizme Stack "Credx". This request can be for single use or multiple uses and generally requires the verification of a member credential.
  2. Embedding the URI: The Customer app embeds the URI obtained from the verify request.
  3. User Authentication Request: When the user requests to authenticate on the Customer app, it triggers an intent to the Dizme app using the embedded URI obtained from the verify request. This URI is encoded in base64 and included in the intent URI. Based on the OS, the URI should have this format:
    • Android URI: dizme://open?params=b3BlbmlkNHZwOi8vYXV0aG9yaXplP3Jlc3BvbnNlX3R5cGU9dnBfdG9rZW4mY2xpZW50X2lkPWRpZDp3ZWI6Y3JlZHgtZGl6bWUtY2wuZGl6bWUuaW86ZGl6bWUmcmVzcG9uc2VfbW9kZT1kaXJlY3RfcG9zdCZzdGF0ZT1paEwxVDF4blc0OWEmcHJlc2VudGF0aW9uX2RlZmluaXRpb25fdXJpPWh0dHBzJTNBJTJGJTJGY3JlZHgtZGl6bWUtY2wuZGl6bWUuaW8lMkZkaXptZSUyRnBkJTJGaWhMMVQxeG5XNDlhJmNsaWVudF9pZF9zY2hlbWU9cmVkaXJlY3RfdXJpJnJlc3BvbnNlX3VyaT1odHRwcyUzQSUyRiUyRmNyZWR4LWRpem1lLWNsLmRpem1lLmlvJTJGZGl6bWUlMkZ2ZXJpZnklMkZpaEwxVDF4blc0OWE=
    • iOS URI: dizme://open?params=ZGl6bWU6Ly9pbmZvY2VydC1hZ2VudC5kaXptZS5pby9hcGkvdjEvaW52aXRhdGlvbi9lYjBmYjQxNy1lOTFiLTRhMjItODc4Ny02NWYyYjlhNDUxMTE=
    • params is the verify request URI encoded in base64.
  4. Verification by Dizme: The Dizme app receives the verify request and displays the credential verification request to the user. Once the user approves, Dizme sends the proof of credentials to the Dizme Stack "Credx".
  5. Callback to Customer Backend: Dizme Stack "Credx" sends a callback to the Customer Backend with the verified credential data. The Customer Backend processes the data and, if valid, generates an authentication token (authtoken).
  6. Complete Verify Invocation: The Customer Backend invokes the complete verify with the following payload:
{
  "status": "BL_SUCCESS",
  "reason": "Credentials verification has been successfully completed",
  "messages": [
    {
      "lang": "it",
      "body": "Le tue credenziali sono state verificate con successo con successo. A breve potrai accedere al servizio richiesto",
      "title": "Dizme Authenticator"
    }
  ],
  "availableActions": [
    {
      "action": "INTENT",
      "data": {
        "intent_android": "scheme://authtoken",
        "intent_ios": "scheme://authtoken",
        "success_messages": [
          {
            "lang": "it",
            "body": "Le tue credenziali sono state verificate con successo con successo. A breve potrai accedere al servizio richiesto",
            "title": "Dizme Authenticator"
          }
        ],
        "failure_messages": [
          {
            "lang": "it",
            "body": "Errore durante il tentativo di completamento l’autenticazione",
            "title": "Dizme Authenticator"
          }
        ]
      }
    }
  ]
}

Action Handling by Dizme Wallet

The Dizme Wallet, upon receiving the action, triggers the specific intent URI, awakening the Customer app, which then receives the authtoken and completes the authentication process.

Note: The use of separate fields for Android and iOS intents is to simplify the Customer Backend's work and provide flexibility for different URI schemes on both operating systems. It is suggested to keep the URI simple and below 2k in size, for instance, using a base64 encoded authtoken.

Sequence

generic_app_to_app_autentication.png

Dizme Interaction API Definition

verify/request

The /verify/request endpoint provides the capability to request verifiable credentials from a user. To initiate such a request, an organization must first establish a proof template (or request) tailored to its specific requirements. This foundational step involves configuring the proof request, which can be accomplished using Dizme Studio, an integral tool within the Dizme ecosystem designed for this purpose (refer to the Dizme Studio documentation for further guidance).

verify/request/multiple-use

The /verify/request/multiple-use service extends the functionality of requesting verifiable credentials from users, with an emphasis on multi-use scenarios. This service necessitates the prior creation of a proof template or request by the organization, akin to the single-use request process. The configuration of this proof request is facilitated through Dizme Studio, offering organizations the flexibility to tailor requests to their operational needs (detailed documentation available in Dizme Studio).

verify/complete

The /verify/complete service enables organizations to finalize the verification process, providing an option to incorporate the result of the verification check on the data received. Typically, following a successful verification confirmation, an organization might conduct additional business logic checks or operations. Depending on these subsequent evaluations, the organization can affirm the verification's success or note any discrepancies. Additionally, there's the option to include an informational message for the user or a link for a subsequent credential offer, enhancing communication and next steps.

verify/status

With the /verify/status service, organizations can inquire about the current status of a verification process. This function is essential for tracking the progress of verification requests and ensuring timely updates are available.

verify/report

The /verify/report service offers access to comprehensive verification reports, including the presentation definition and the verifiable presentation detailing the data transmitted from the wallet. This service is crucial for organizations seeking to analyze and verify the credentials presented by users.

Organizations API Callback

verify/event

Upon invoking the /verify/event service, organizations receive all attributes requested in the verification process. This immediate feedback mechanism is vital for organizations to promptly process and act upon the received information.

Possible values:

  • CREATED: New verify transaction created
  • READ: Verify transaction details retrieved (verify request read from wallet)
  • SUCCESS: Credential verified with success
  • FAILED: Credential verification failed
Back to top