3. Register DID Document

Role: New Entity

This step is performed by the New Entity using the onboarding credential received from a Trusted Issuer or Support Office in Step 2.

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.

Prerequisites

Before starting this step, ensure you have:

Completed Step 1: Your wallet is set up with ES256K and ES256 key pairs
Received onboarding credential: From a Trusted Issuer or Support Office (Step 2)
Valid VC to onboard: The verifiable credential should contain your DID in the credentialSubject field

Load your existing wallet

Your wallet should already be configured from Step 1. Load your existing wallet with the private keys you saved:

Command
==> using user ES256K did1 <YOUR_ES256K_PRIVATE_KEY> <YOUR_DID>
==> using user ES256 did1 <YOUR_ES256_PRIVATE_KEY> <YOUR_DID>

Replace the placeholders with:

<YOUR_ES256K_PRIVATE_KEY>: The ES256K private key you saved in Step 1
<YOUR_ES256_PRIVATE_KEY>: The ES256 private key you saved in Step 1
<YOUR_DID>: Your DID from Step 1

info

If you don't have your private keys saved, you'll need to go back to Step 1 and regenerate your wallet. Make sure to save your private keys securely this time.

Now connect the wallet with the pilot environment:

Command
==> env pilot

Verify your onboarding credential

You should have already received a "Verifiable Authorisation To Onboard" credential from a Trusted Issuer or Support Office in Step 2. This verifiable credential should contain your DID in the credentialSubject field. To see your DID run:

Command
==> view user.did
did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw

info

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 didr_invite. For this you have to present the authorisation to onboard obtained in the previous step:

Command
==> resAuthDIDRInvite: authorisation auth didr_invite_presentation ES256 <VC_TO_ONBOARD>

Output - value saved in 'resAuthDIDRInvite'
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Inh6bzBsZmQ2TXpJbWRTNGVHbWtDY2hCUVBGbDh5emU1ZjREZFNGWTlxSFEiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjYyNTcsImV4cCI6MTcwMDIzMzQ1Nywic3ViIjoiZGlkOmVic2k6enpjSkp1TTRaNEFVS2RMOGtkTUVLTnciLCJhdWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjMiLCJzY3AiOiJvcGVuaWQgZGlkcl9pbnZpdGUiLCJqdGkiOiI3NDUzNTNkYS00ODZkLTQyNjYtODQ5MS03ZTI4MjgyZmUwODkiLCJpc3MiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjMifQ.U9wctwpyQFMD4L2B2fRuhhyJoQzcSlok1dDQCgNlNnCaIXMBqymPmQVWvRMAFr7RAbMWj9AeXJec0QIr12XyNA",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid didr_invite",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Inh6bzBsZmQ2TXpJbWRTNGVHbWtDY2hCUVBGbDh5emU1ZjREZFNGWTlxSFEiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjYyNTcsImV4cCI6MTcwMDIzMzQ1Nywic3ViIjoiZGlkOmVic2k6enpjSkp1TTRaNEFVS2RMOGtkTUVLTnciLCJhdWQiOiJkaWQ6ZWJzaTp6emNKSnVNNFo0QVVLZEw4a2RNRUtOdyIsImp0aSI6IjE1N2NiYzJjLTg1ZTItNDI2Zi1iYWRjLTI3NTUyMjk2ZjljMiIsIm5vbmNlIjoiM2JiZTQxOTktN2ZkZS00MzcyLTk1YzMtMGFiMDkzN2JkMWE3IiwiaXNzIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS9hdXRob3Jpc2F0aW9uL3YzIn0._-4F6nAA65PTzwJLRbsd6SyoHD6KrlsDOzoj0Qxyz4iWLUi9pIIPyJ83Tm-8o8UnH9lQKEde2gCq956p3JxpaA"
}

Now load the access token:

Command
==> using token resAuthDIDRInvite.access_token

Register first part of the DID Document

To register the first part of the DID Document run:

Command
==> did 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:

Command
==> did get /identifiers/ user.did

Output
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw",
  "controller": ["did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw"],
  "verificationMethod": [
    {
      "id": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#DcKbRyDwj-vgt4smUt5dlgwoN1tTvH1x98dc2ydTQ3A",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "4ZaWhy-1tbVSoEr-AMvPPnurkH2_wQrEr2O823fTETU",
        "y": "O0mebx46dePZr_jrIeORSCAqKLhj5GpY8PU6npBstCQ"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#DcKbRyDwj-vgt4smUt5dlgwoN1tTvH1x98dc2ydTQ3A"
  ],
  "capabilityInvocation": [
    "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#DcKbRyDwj-vgt4smUt5dlgwoN1tTvH1x98dc2ydTQ3A"
  ]
}

Request a "write" access token

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

Command
==> resAuthDIDRWrite: authorisation auth didr_write_presentation ES256K

Output - value saved in 'resAuthDIDRWrite'
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Inh6bzBsZmQ2TXpJbWRTNGVHbWtDY2hCUVBGbDh5emU1ZjREZFNGWTlxSFEiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjYyNjcsImV4cCI6MTcwMDIzMzQ2Nywic3ViIjoiZGlkOmVic2k6enpjSkp1TTRaNEFVS2RMOGtkTUVLTnciLCJhdWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjMiLCJzY3AiOiJvcGVuaWQgZGlkcl93cml0ZSIsImp0aSI6ImIyOGY2MGFjLTJlMGYtNGFiMi04OTg5LTFiN2VlYmY5MjVlYSIsImlzcyI6Imh0dHBzOi8vYXBpLXBpbG90LmVic2kuZXUvYXV0aG9yaXNhdGlvbi92MyJ9.OikkjrWO4kI3O_PkqsNGcVZ0inZa9Vx9cwqHQ2G6B_p9WhlskNS62xsPHOzjn37bbAYfG8skxEX5MUni2SVpKQ",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid didr_write",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Inh6bzBsZmQ2TXpJbWRTNGVHbWtDY2hCUVBGbDh5emU1ZjREZFNGWTlxSFEiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjYyNjcsImV4cCI6MTcwMDIzMzQ2Nywic3ViIjoiZGlkOmVic2k6enpjSkp1TTRaNEFVS2RMOGtkTUVLTnciLCJhdWQiOiJkaWQ6ZWJzaTp6emNKSnVNNFo0QVVLZEw4a2RNRUtOdyIsImp0aSI6ImI2MmFiMDE5LWNhNTYtNGE2Yi1iODcwLTQxNzdhMzQ2M2ZiOCIsIm5vbmNlIjoiYjVmN2Y5NjQtODcyMC00ZDU2LWFmYzMtYzg0ZTRkMTE1NjI2IiwiaXNzIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS9hdXRob3Jpc2F0aW9uL3YzIn0.vY1-ENX-KIm6UfW-JTTv2IxHfdPjg6149KwXkbJUZtw9ygluLjHLPuWuvMUlhDkkHGF_Nmh14Q59uQw8MnvmUg"
}

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:

Command
==> did addVerificationMethod user.did ES256

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

Command
==> did addVerificationRelationship user.did authentication ES256

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

Command
==> did addVerificationRelationship user.did assertionMethod ES256

At this point your DID document should be like this:

Command
==> did get /identifiers/ user.did

Output
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw",
  "controller": ["did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw"],
  "verificationMethod": [
    {
      "id": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#DcKbRyDwj-vgt4smUt5dlgwoN1tTvH1x98dc2ydTQ3A",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "4ZaWhy-1tbVSoEr-AMvPPnurkH2_wQrEr2O823fTETU",
        "y": "O0mebx46dePZr_jrIeORSCAqKLhj5GpY8PU6npBstCQ"
      }
    },
    {
      "id": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#TI3gGIhSOygydZ8gJnseuFZ2G237LYDE6tVaOtb-6Is",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "iBv6wrPNeSitje8yfFK4rsoc8fbE8Rngp85KFDMLjgw",
        "y": "Dv8BryEQCUqQe9bRawFdKlhfGDN9o1r2OyIeFLlsqH4"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#DcKbRyDwj-vgt4smUt5dlgwoN1tTvH1x98dc2ydTQ3A",
    "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#TI3gGIhSOygydZ8gJnseuFZ2G237LYDE6tVaOtb-6Is"
  ],
  "assertionMethod": [
    "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#TI3gGIhSOygydZ8gJnseuFZ2G237LYDE6tVaOtb-6Is"
  ],
  "capabilityInvocation": [
    "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#DcKbRyDwj-vgt4smUt5dlgwoN1tTvH1x98dc2ydTQ3A"
  ]
}

Congratulations!

You have registered a new Legal Entity in the DID Registry. You can now proceed to Step 4 to request trusted issuer credentials from a Trusted Issuer or Support Office.

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:

Command
==> run registerDidDocument_ES256K_ES256 <VC_TO_ONBOARD>

Prerequisites​

Load your existing wallet​

Verify your onboarding credential​

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​