Skip to main content

VIDconnect

VIDconnect implements the OpenID connect identity protocol, in particular the OpenID connect Self-Issued OpenID Provder standard.

Register your Entity​

In order to interact with VIDconnect you need to register your entity. An entity represents a party that will be registered at VIDconnect. This entity will hold the OpenID client information.

important

VIDconnect is an independent service and requires the registration of its own entity, independently from VIDcredentials.

If you are interested in using VIDconnect, please contact the VIDchain Support Team for your entity creation in VIDconnect.

To register an entity, the following information have to be provided:

  • redirect_uri: This URL defines the location where the OIDC Provider should redirect the user after the authentication flow is finished. More than one URL can be provided for testing purposes.
  • (optional) logo : This optional attribute defines the image that will appear when user is logging in (QR website).
  • (optional) scope: Specify which kind of credentials you want to allow presenting: email, phone, verifiableId. By default, any generic Verifiable Credential is valid if you do not specify otherwise.

With this information, Validated ID is ready to create your entity and provide you back the access details:

  • client_id : The client id is a string to uniquely identify your client when making calls to the OIDC provider.
  • client_secret: The client secret is used to authenticate the client to OIDC provider.

Integrate your site to VIDconnect​

Once you are provided with your client_id and client_secret you are ready to start the integration.

The flow basically consists on:

  1. Redirecting the user from your website to VIDconnect. The user will interact with VIDconnect either through scanning a QR code or, if the user is navigating in a mobile browser, it will be automatically be redirected to folllow the process with VIDwallet app.
  2. The user will select with which DID wants to be authenticated and present any credential requested.
  3. VIDconnect will validate the presentation of the ownership of the DID and the verifiable presentation validity. If success, VIDconnect will provide a code to your redirect_uri.
  4. With this code received via callback, you are ready to request the JWT that contains the information presented by the user, either the did or a verifiable presentation.
  5. Use the information within the JWT to validate your business logic rules.

Step by step​

Redirect to OIDP​

First, the client redirects the requester to VIDconnect OIDC provider with an URL in the following format:

https://api.vidchain.net/oauth2/auth?
  response_type=code
  &state=08bd09b6-8544-4f8b-9aef-bdd6f17db6f7
  &redirect_uri=<Your callback URL>
  &client_id=<Your Client ID>
  &scope=openid VerifiableIdCredential
  &nonce=a8d84bc5-1c09-484b-9638-81baf028dfb2

As integrator you now own an openID client for VIDconnect. With this client you need to perform a request to the following URL https://staging.vidchain.net/oauth2/auth. This endpoint will redirect your client to https://staging.vidchain.net/oauth2/login where VIDconnect login QR code will be shown. See more details about this endpoint at Redirect User to VIDconnect OpenAPI Specification.

Processing callback​

Once the user is authenticated, the OID provider redirects the user session to the callback URL providing the code:

http(s)://<callback URL>
  ?code=pRt3Lk5I7A....IhUNaPsWPQ
  &scope=openid%20VerifiableIdCredential
  &state=08bd09b6-8544-4f8b-9aef-bdd6f17db6f7

Token endpoint​

With this code, the client_id and the client_secret, your OIDC client needs to call the /token endpoint:

POST to https://api.vidchain.net/oauth2/token

With the following body:

"Content-Type": 'application/x-www-form-urlencoded'
code: code,
redirect_uri: REDIRECT_CALLBACK,
grant_type: "authorization_code",
client_id: CLIENT_ID,
client_secret

An example response is shown below:

{
    "access_token": "7UZT2tlb...UJkdovjfM",
    "expires_in": 3599,
    "id_token": "eyJhbGciOiJSUzI1NiIsImt...qvcFmb8vxqwXjHn9kERSRA",
    "scope": "openid VerifiableIdCredential",
    "token_type": "bearer"
}

You can retrieve the information through https://staging.vidchain.net/oauth2/token which will provide you an id_token. This token is a JWT which contains user's information (did, verifiable presentation...). You have to retrieve the information provided from vp field found in JWT payload. This is a dummy example of the payload of a decoded id_token:

{
  ...
  "did": "did:ethr:0x733D178303Efdf2155336728f7d3CA1e7009a4BB",
  "vp": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "proof": {
      "created": "2022-09-26T11:49:57.000Z",
      "jws": "eyJhbGciOiJFUzI1NkstUiIsInR5cCI6IkpXVCJ9.eyJpYXQi...X19.8wYnV6c8DRcXhArxFnwZOoNTMIsNMU_GW52puWfNkXXNRwu5ckoO7TufZYEDaVhesHqkFF8bYJcoNf7cbHA0GQE",
      "proofPurpose": "assertionMethod",
      "type": "EcdsaSecp256k1Signature2019",
      "verificationMethod": "did:ethr:0x733D178303Efdf2155336728f7d3CA1e7009a4BB#key-1"
    },
    "type": "VerifiablePresentation",
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://api.vidchain.net/credentials/vid-google/v1"
        ],
        "credentialStatus": {
          "id": "https://dev.vidchain.net/api/v1/revocation/credential-status/status-list/100/credential/724",
          "statusListCredential": "https://dev.vidchain.net/api/v1/revocation/status-list/100",
          "statusListIndex": "724",
          "type": "RevocationList2021"
        },
        "credentialSubject": {
          "email": "example@gmail.com",
          "id": "did:ethr:0x733D178303Efdf2155336728f7d3CA1e7009a4BB",
          "image": "https://lh3.googleusercontent.com/a-/ACNPEu8x95NzH16EsC18_cHvc2z4A=s40-b",
          "lastName": "Smith",
          "name": "Bob"
        },
        "id": "https://api.vidchain.net/api/v1/schemas/2393",
        "issuanceDate": "2022-09-20T07:48:10.000Z",
        "issuer": "did:ethr:0x078D7c2922E3f95A35A22C54696D8870b857C3f9",
        "proof": {
          "created": "2022-09-20T07:48:10.000Z",
          "jws": "eyJhbGciOiJFUzI1NksiLCJraWQiOiJkaWQ6ZXRocjoweDA3OEQ3YzI5MjJFM2Y5NUEzNUEyMkM1NDY5NkQ4ODcwYjg1N0MzZjkja2V5cy0xIiwidHlwIjoiSldUIn0.eyJpYXQ...bCJdfX0.heEE7Vcx2cCMl2zYdhxSzKEr7ZbvEUCHrDzKE-TL1WGISaO0mzyxwZOJdlbqKDVv2FqPsDnkHCSDuvXd3wJR3g",
          "proofPurpose": "assertionMethod",
          "type": "EcdsaSecp256k1Signature2019",
          "verificationMethod": "did:ethr:0x078D7c2922E3f95A35A22C54696D8870b857C3f9#keys-1"
        },
        "type": [
          "VerifiableCredential",
          "VerifiableIdCredential",
          "EmailCredential",
          "VidGoogleCredential"
        ]
      }
    ]
  }
}

See more details about this request under Retrieve OIDC ID Token VIDconnect OpenAPI specification.

Example setup of an OpenID Connect Client​

This section details the example configuration of an OpenID client using Typescript and the JSO client:

import { JSO, Popup } from "jso";

const nonce = utils.randomString(24);
const state = utils.randomString(24);

let configFile = {
  client_id: config.CLIENT_ID,
  client_secret: config.CLIENT_SECRET,
  token: config.IDENTITY_PROVIDER + "/oauth2/token",
  authorization: config.IDENTITY_PROVIDER + "/oauth2/auth",
  redirect_uri: config.REDIRECT_CALLBACK,
  scopes: {
    request: ["openid", "offline"],
    require: ["openid", "offline"],
  },
  response_type: "code",
  debug: true,
};

this.client = new JSO(configFile);

VIDchain Integration Examples​

More integration examples can be found on the public GitHub repository demonstrating for example the interaction with VIDconnect or VIDcredentials.