Skip to main content

Run OpenDID Service


Running the OpenDID service requires some configuration and a KILT DID. The DID establishes a secure session with an identity wallet using a key agreement key of type X25519KeyAgreementKey2019 included in the DID Document generated by the setup container.

OpenDID serves a well-known DID configuration, which the identity wallet uses to ensure that the domain is linked to the specified DID.

Run setup container

Before running the opendid-setup container, set two environment variables:

  1. SEED to provide an account with funds (minimum of 3 KILT) for the DID generation.

    export SEED="dont try this seed its completely made up for this nice example"

    Set to "spiritnet" if the account is on the spiritnet production network.

    export ENDPOINT="spiritnet"

    Set to "peregrine" if the account is on the peregrine test network.

    export ENDPOINT="peregrine"

    Then run the setup with the following command:

    docker run --rm -it -e "ENDPOINT=${ENDPOINT}" -v $(pwd):/data "${SEED}"

The command generates a set of new mnemonics and then derives a DID from them and generates multiple files into the current directory:

  1. config.yaml The configuration file used by the OpenDID service.


    You only need the config.yaml to run the OpenDID service. This file includes the generated mnemonic and secret keys and you should protect it from unauthorized access.

  2. did-secrets.json This file contains the public and secret keys in the DID Document.


    Keep a secure backup of this file as it contains all the secret keys.

  3. did-document.json contains the DID Document generated by this setup.

The container generates sensible defaults in the config.yaml file, but here are some values you might want to change:

  • Set production to true, this only allows secure connections.

  • Set the WellKnownDid > origin, which should match the host running the OpenDID service.

  • Set the keys used for JWT issuance in the jwt section.

  • The client section, including:

    • The client ID as a key (The default is: example-client).

    • The requirements section, including:

      • What CTypes are required for authentication.

      • The trusted attesters as an address (The default is for the SocialKYC attester).


        The generated default config.yaml requires an email credential issued by an attester.

      • What redirect_urls the service accepts (The default is http://localhost:1606/callback.html for the demo project).

      • The clientSecret is optional but recommended. If you use the authorization code flow, the token endpoint requires it.

Run the service

When you've made changes to the config.yaml file, you can run the OpenDID service.

  1. Specify the runtime through the RUNTIME environment variable:

    Set to "spiritnet" for production KILT

    export RUNTIME="spiritnet"

    Set to "peregrine" for the KILT test net.

    export RUNTIME="peregrine"
  2. Run the docker image.

    docker run -d --rm \
    -v $(pwd)/config.yaml:/app/config.yaml \
    -v $(pwd)/checks:/app/checks \
    -e "RUNTIME=${RUNTIME}" \
    -p 3001:3001 \
  3. Open the login page at http://localhost:3001.

Next steps

With configuration in place and a service running, next you need to integrate OpenDID into an application so that a user can use the login page.