DID Registration

Updated: June 2, 2020

Registering a Decentralized Identifier (DID) is the process of creating a unique identifier on a distributed ledger and associating it with one or more public keys. You can prove you are the owner/controller of a DID to anyone you choose, as long as you possess the corresponding private key(s). DIDs form the foundation of decentralized identity. The W3C Credentials Community Group's DID spec explains the DID technical standard in more detail.

The way you claim a DID and publish your public keys depends on which distributed ledger you use to register your DID. Each ledger has its own rules, formats, and quirks. Thankfully, the developing DID standard defines common ways to deal with DIDs, and our services expose the standard to you in a simple web API. Currently, we're developing support for the following ledgers:

Bitcoin
Ethereum, via uPort
Sovrin

Our intention is to be chain agnostic, enabling users to choose a DID variant that runs on their preferred ledger. We plan to add support for other DID variants/ledgers that are compliant with DID standards and security requirements.

While we continue to work on DID registration for the ledgers above, we've created a service for generating test DIDs. We call this our test DID method. It is not connected to any blockchain or ledger. To try out DID registration with our test method, you can use our example user agent chrome extension, or query our APIs directly.

Registration via our chrome extension

We've built a test user agent that implements our registration APIs; it is appropriate if you want to try out registration without writing any code. Over time we plan to provide production-ready user agent applications across platforms including mobile and desktop. To register a DID via our user agent:

Install the chrome extension by following this guide.
Once installed, open the extension by clicking on the icon in Google Chrome.
Type in a friendly name for your DID and click create.

Congratulations, you have created your first DID! You can now move on to using this DID to perform authentication.

Registration via our APIs

If you're a developer who wants to allow users to register DIDs from your app or service, you can implement DID registration by following the steps below.

Prerequisites

In order to complete this registration tutorial, you'll need:

NPM and NodeJS 8 or later installed on your machine.
OpenSSL installed on your machine, or an equivalent RSA key generator.

Choose a target ledger

First, you need to decide on which ledger, or DID method, you'll register your DID. Each ledger offers different characteristics and qualities that you might want depending on how you plan to use your new DID.

For now, you only have one option: to register on our test method. As we bring support for other ledgers online, we plan to publish guidance choosing the appropriate ledger for your use case.

Generate a key pair

Next, you need to generate an asymmetric key pair using the key types supported by your target ledger. For testing things out you'll use an RSA key, but the test method also supports Secp256k1 and Ed25519 keys. You can generate your keys however you like, but here's an example using OpenSSL.

Generate the private key in PEM format:

openssl genrsa -out private.pem 2048

Extract the public key in PEM format:

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Generate a JWS

To register a DID using these keys, you must sign a DID registration request with your private key. A DID registration request must be formatted as a compact JSON Web Signature (JWS) with the following body:

}

{
  "@context": "https://w3id.org/did/v1",
  "publicKey": [
    {
      "id": "#key-1",
      "type": "Secp256k1VerificationKey2018",
      "publicKeyJwk": {
        "kty": "EC",
        "kid": "#key-1",
        "crv": "P-256K",
        "x": "p7Mt2Z6hXu8g_I62owqmNcrj3t1nRoWslB8eQ7JP0yY",

property	value	description
`didMethod`	`test`	The DID method used to register the DID. Currently only `test` is supported.
`publicKey`	`[]`	An array of public keys in the JSON Web Key (JWK) format.
`hubUri`	`foo.com`	Any string value, reserved for future use.

You can generate and sign a JWS using any tool you like. JWT.io maintains a nice list of JWT libraries to use. You can also use DIF's experimental did-auth-jose package to generate and sign a JWT. First install the necessary packages:

npm install @decentralized-identity/did-auth-jose
npm install pem-jwk

Then copy and paste the following code into a new javascript file called make-jws.js:

var fs = require('fs');
var path = require('path');
var didAuth = require('@decentralized-identity/did-auth-jose');

// load JWKs from files
const jwkPriv = JSON.parse(fs.readFileSync(path.resolve(__dirname, './private.jwk'), 'ascii'));
const jwkPub = JSON.parse(fs.readFileSync(path.resolve(__dirname, './public.jwk'), 'ascii'));

// load JWK into an EcPrivateKey object
const privateKey = didAuth.EcPrivateKey.wrapJwk(jwkPriv.kid, jwkPriv);

async function makeJws() {

    // construct the JWS payload
    const body = {
        "@context": "https://w3id.org/did/v1",
        publicKey: [
            {
                id: jwkPub.kid,
                type: "Secp256k1VerificationKey2018",
                publicKeyJwk: jwkPub
            }
        ],
        service: [
            {
                id: "IdentityHub",
                type: "IdentityHub",
                serviceEndpoint: {
                    "@context": "schema.identity.foundation/hub",
                    "@type": "UserServiceEndpoint",
                    instance: [
                        "did:test:hub.id",
                    ]
                }
            }
        ],
    };

    // Construct the JWS header
    const header = {
        alg: jwkPub.defaultSignAlgorithm,
        kid: jwkPub.kid,
        operation:'create',
        proofOfWork:'{}'
    };

    // Sign the JWS
    const cryptoFactory = new didAuth.CryptoFactory([new didAuth.Secp256k1CryptoSuite()]);
    const jwsToken = new didAuth.JwsToken(body, cryptoFactory);
    const signedBody = await jwsToken.signAsFlattenedJson(privateKey, {header});

    // Print out the resulting JWS to the console in JSON format
    console.log(JSON.stringify(signedBody));

}

makeJws();

Finally, run the above script, which will output a signed registration request as a JWS:

> node make-jws.js

eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3RLZXkifQ.eyJkaWRNZXRob2QiOiJ0ZXN0IiwiaHViVX....

Call the registration API

Now that you've generated your new key pair securely on your own machine, you can publish your public key onto the distributed ledger with the following API call to https://beta.register.did.microsoft.com/api/v1.1:

POST /api/1.0/register HTTP/1.1
Host: beta.ion.microsoft.com
Content-Type: application/json
Content-Length: 1061

{
  "header": {
    "alg": "ES256K",
    "kid": "#key-1",
    "operation": "create",
    "proofOfWork": "{}"
  },

The following curl command will produce this request for you:

curl -v -H "Content-Type: application/jwt" --data "eyJhbGciOi..." -X POST https://beta.register.did.microsoft.com/api/v1.1

If your request succeeded, you should receive back the following response:

      "use": "verify",
      "defaultEncryptionAlgorithm": "none",
      "defaultSignAlgorithm": "ES256K"
    }
  }
],
"service": [
  {

property	value	description
`did`	`did:test:79cc8f04-0588-4513-b1c6-ae987610c082`	Your new DID. The format of this value will vary for each DID method, so it should generally be treated as an opaque string.
`status`	`registered`	The `status` property indicates the status of the creation of your DID. Possible values include `in-progress`, `failed`, and `not-registered`.

On our test method DID creation occurs instantaneously. Other ledgers, however, may require significant queueing and processing time for each new DID. Your next step should be to poll for completion of your DID creation before you proceed to use it. You can poll for a DID's registration status with the following request (substituting did:test:79cc8f04-0588-4513-b1c6-ae987610c082 for your DID):

"type": "IdentityHub",
"serviceEndpoint": {
  "@context": "schema.identity.foundation/hub",

The following curl command will produce this request for you:

curl https://beta.register.did.microsoft.com/api/v1.0/did:test:79cc8f04-0588-4513-b1c6-ae987610c082/status

And the response will be the same format as above:

        "instance": [
          "did:test:hub.id"
        ]
      }
    }
  ]
}

Once you've received a registered status from the Registration API, your DID has been successfully created on the distributed ledger used by the DID method you chose.

Note

Any DIDs you create on our test ledger will be deleted periodically.

Call the discovery API

Congratulations, you've successfully created a DID! The next step is to use the discovery API to double check that your DID can be resolved correctly.

See something missing? We'd love your feedback and input on the Verifiable Credentials preview. Please contact us. When you use Microsoft DID Services, you agree to the DID Preview Agreement and the Microsoft Privacy Statement.