Onboard | EBSI hub

This guide presents the steps to onboard a new legal entity in EBSI, which consists in the registration of the DID Document in the DID Registry.

Setup your wallet

Create a new DID with 2 key pairs:

The first key pair with the ES256K algorithm. It will be used to write data in the blockchain.
The second key pair with the ES256 algorithm. It will be used to sign verifiable credentials and verifiable presentations.

==> using user ES256K
==> using user ES256

...

{
  "keys": {
    "ES256K": {
      "id": "k0G8kZ0UxsxGLYiiAhRUgtLtFzu-ZpbvzFtpJIH63ZI",
      "kid": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#k0G8kZ0UxsxGLYiiAhRUgtLtFzu-ZpbvzFtpJIH63ZI",
      "privateKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo",
        "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
      },
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo"
      },
      "privateKeyEncryptionJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo",
        "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
      },
      "publicKeyEncryptionJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo"
      }
    },
    "ES256": {
      "id": "eJYROV5PYyRZxjF7QABzsd7ooTw5bFNm2Ytt6bAxySQ",
      "kid": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#eJYROV5PYyRZxjF7QABzsd7ooTw5bFNm2Ytt6bAxySQ",
      "privateKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "Vm7_Vhz07e9UoblDw1rmd29bV6ykcut4npLnqhhQlVk",
        "y": "uISs1AK-TVo0duSg3AvFuBNgBPp7ex4dWmYvkFN8uRk",
        "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
      },
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "Vm7_Vhz07e9UoblDw1rmd29bV6ykcut4npLnqhhQlVk",
        "y": "uISs1AK-TVo0duSg3AvFuBNgBPp7ex4dWmYvkFN8uRk"
      },
      "privateKeyEncryptionJwk": {
        "kty": "EC",
        "x": "ORK0V91Xg9IAFAMMcl73AxXv6n2ptYKEn5nBfiKCIm4",
        "y": "yRMSUPrqVtF2-Q_HkCDYjhNcrvkJeaf9PZdY1BLs8Jc",
        "crv": "P-256",
        "d": "p4B-UL0hzwNTJFA4taL3N0a1jCmIjUMPgKiwSjO1ZjM"
      },
      "publicKeyEncryptionJwk": {
        "kty": "EC",
        "x": "ORK0V91Xg9IAFAMMcl73AxXv6n2ptYKEn5nBfiKCIm4",
        "y": "yRMSUPrqVtF2-Q_HkCDYjhNcrvkJeaf9PZdY1BLs8Jc",
        "crv": "P-256"
      }
    }
  },
  "privateKeyHex": "0x3b6e9be143d5c7f30caf3b3c89bab43c220722711c1dda2e632f660dc61c0a4f",
  "publicKeyHex": "0x048264fcc4ba4019a197d899dfc539e53ace49532ed25d241b204af03cd05bbbafafd2556dc90adb8b1b230e0dcb3d7aaa81da019761366a2cb31c8ee9afcd6b1a",
  "address": "0x8390f8b75Dfb727dD53C25a048DC4887CF482330",
  "did": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
  "didVersion": 1
}

note

Save the generated private keys in a safe place

Now connect the wallet with the pilot environment:

==> env pilot

Request a credential to onboard

For this step contact with the Trusted Issuer related to your use case and request a "Verifiable Authorisation To Onboard". This veriable credential should contain your DID in the credentialSubject field. To see your DID run:

==> view user.did
did:ebsi:zy8Psj9ez9wrsSZ7vrHE221

note

If there is no Trusted Issuer to contact and you are at the top level of the use case then contact with Support Office in order to get the "Verifiable Authorisation To Onboard".

Request an "invite" access token

In this step you will request an access token to the authorisation API with the scope did_invite. For this you have to present the authorisation to onboard obtained in the previous step:

==> resAuthDIDRInvite: authorisation-new auth didr_invite_presentation ES256 vcToOnboard

...

Value saved in 'resAuthDIDRInvite':
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjk5MzUsImV4cCI6MTcwMDIzNzEzNSwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjQiLCJzY3AiOiJvcGVuaWQgZGlkcl9pbnZpdGUiLCJqdGkiOiI1MGE5NzAzNi03N2Y5LTQ4ZWYtYjFmMi01ZTRiN2RkOTQ1YmQiLCJpc3MiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjQifQ.uFtHY11ugcBSBVvYz3BmSPcJeoR7xNR56wuQwx6Rh_WlzUKmNepZMAsDo0bG_b8lmsmYm29gGXZiJxI5foPsEQ",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid didr_invite",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjk5MzUsImV4cCI6MTcwMDIzNzEzNSwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJkaWQ6ZWJzaTp6eThQc2o5ZXo5d3JzU1o3dnJIRTIyMSIsImp0aSI6Ijg4NGI1NDg2LThiNmUtNDNmNi1hMjc4LTQwNmVjYjhlNDJlZSIsIm5vbmNlIjoiZDQ2MjEwODgtMzdlYS00MzU0LTk0NDUtOGQxMDlmODI4NzhlIiwiaXNzIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS9hdXRob3Jpc2F0aW9uL3Y0In0.kbm2b6Ex_OXqh7LqLY14UqQtvz8_9tX0gxVRJkLkL0S_Zv3xgyXbKxisK4hpdeWNZARbdtbY8xlWB6GoBF74bw"
}

Now load the access token:

using token resAuthDIDRInvite.access_token

Register first part of the DID Document

To register the first part of the DID Document run:

==> did-new insertDidDocument

This command will interact with the DID Registry and insert the ES256K key with the relationships "authentication" and "capabilityInvocation". At this point your DID document should be like this:

==> did-new get /identifiers/ user.did

...

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
  "controller": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221"
  ],
  "verificationMethod": [
    {
      "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "QjnMrtzeAwvgVWjEZd6lYGgMe5yvQjKvb8teLxFHf18",
        "y": "fT_D3W75TeZcJjt4eXBZtG3cfeqsVl8F6et5ClT525I"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64"
  ],
  "capabilityInvocation": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64"
  ]
}

Request a "write" access token

Now request an access token to the authorisation API with the scope did_write. In this case there is no need to present the veriable authorisation to onboard because the DID is already in the registry:

==> resAuthDIDRWrite: authorisation-new auth didr_write_presentation ES256K

...

Value saved in 'resAuthDIDRWrite':
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMzE3MDgsImV4cCI6MTcwMDIzODkwOCwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjQiLCJzY3AiOiJvcGVuaWQgZGlkcl93cml0ZSIsImp0aSI6IjkwMjJkZWFlLWU0ODEtNDk5NC04ZTM0LTc1MzNjMjNiNmQ4NyIsImlzcyI6Imh0dHBzOi8vYXBpLXBpbG90LmVic2kuZXUvYXV0aG9yaXNhdGlvbi92NCJ9.40dn2_k1Q_YQZXYLITFTwalaaQoJs987t_GjAE_irqPlE4GjhqmqhN4RPl69xaFm9IBB9eolLKSWB2dH5HuqBA",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid didr_write",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMzE3MDgsImV4cCI6MTcwMDIzODkwOCwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJkaWQ6ZWJzaTp6eThQc2o5ZXo5d3JzU1o3dnJIRTIyMSIsImp0aSI6ImRiODIzNmQzLWI3M2MtNGQ5Ni1iNGJiLWJkZWNkZmU5MzQyMiIsIm5vbmNlIjoiMGViYjJmNjgtNGZkZi00Y2QwLWIxNmQtZjBmMDM1YzExNzUxIiwiaXNzIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS9hdXRob3Jpc2F0aW9uL3Y0In0.nB0t5K0eoRqEPT1s-B6jHPMOvSb8soN3SN_Brded2O_zicjkX6uyqOlA9hNqcCZSpNQAi2rdGRdk-IwZCxxUUw"
}

Please note that the command is using the ES256K key for the authentication because this the key registered in the DID registry.

Now load the access token:

==> using token resAuthDIDRWrite.access_token

Register the second part of the DID Document

The following steps will complete the registration of the DID Document. First register the ES256 key as verification method:

==> did-new addVerificationMethod user.did ES256

Now create the relationship "authentication" with this verification method:

==> did-new addVerificationRelationship user.did authentication ES256

Finally, do the same for the relationship "assertionMethod":

==> did-new addVerificationRelationship user.did assertionMethod ES256

At this point your DID document should be like this:

==> did-new get /identifiers/ user.did

...

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
  "controller": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221"
  ],
  "verificationMethod": [
    {
      "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "QjnMrtzeAwvgVWjEZd6lYGgMe5yvQjKvb8teLxFHf18",
        "y": "fT_D3W75TeZcJjt4eXBZtG3cfeqsVl8F6et5ClT525I"
      }
    },
    {
      "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#-gIhC6LBcLhgP2mUhLc7uJoG-6Fd7WxRTxanIYBk12o",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "Cbe06PxqDBf6t1t4Eyk4va7TjPPq7TqmtJdT53L3Amw",
        "y": "A6ChunbYIgvAZVKuN15slVtFq1jfReRqDDbwBW9uViI"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64",
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#-gIhC6LBcLhgP2mUhLc7uJoG-6Fd7WxRTxanIYBk12o"
  ],
  "assertionMethod": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#-gIhC6LBcLhgP2mUhLc7uJoG-6Fd7WxRTxanIYBk12o"
  ],
  "capabilityInvocation": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64"
  ]
}

Congratulations!

You have registered a new Legal Entity in the DID Registry

Script to register a Legal Entity

The CLI tool is equipped with a script to simplify the process of registering a new Legal Entity. First, setup your wallet and request a verifiable authorisation to onboard. Then run:

==> run new/registerDidDocument_ES256K_ES256 vcToOnboard

Setup your wallet​

Request a credential to onboard​

Request an "invite" access token​

Register first part of the DID Document​

Request a "write" access token​

Register the second part of the DID Document​

Script to register a Legal Entity​