Skip to main content

Get an X509Credential from a UZI certificate

Many use cases, like 360-graden-clientbeeld, identify care organizations by their URA number. The CIBG doesn't issue Verifiable Credentials with the URA yet, so you create one yourself from the care organization's UZI server certificate: an X509Credential.

The node uses the X509Credential to:

  • register the care organization on the Discovery Service, so other parties can find it;
  • prove the care organization's identity when it requests an access token from another party.

The X509Credential is:

  • issued by the UZI certificate: the issuer is a did:x509 DID derived from the certificate, and the credential is signed with the certificate's private key;
  • issued to the care organization's did:web DID, which belongs to its subject on your Nuts node. That subject holds the credential in its wallet.

It contains the UZI certificate, and the URA, name and city taken from it. It does not contain the private key.

Do this once per care organization, per environment.

Before you start

  • The care organization has a subject, and you have its did:web DID (see "Create a subject").
  • The care organization's UZI server certificate from the CIBG:
    • the full certificate chain (root CA up to the certificate itself) as a PEM file;
    • the unencrypted private key of the certificate as a PEM file.
  • A tool to create the credential. Choose one:
    • The nutsfoundation/go-didx509-toolkit Docker image (source), to create the credential by hand. The steps below use this tool.
    • The Java library uzi-did-x509-issuer-java, to create the credential from your EHR or another Java application, without Docker. See its README for usage.

Create the credential

Put the certificate chain (certificate.pem) and private key (privatekey.pem) in a directory called certs. From the directory that contains certs, run (replace <did> with the care organization's did:web DID, from "Create a subject"):

docker run --rm -v "$(pwd)/certs:/certs" \
  nutsfoundation/go-didx509-toolkit:1.2.0 \
  vc /certs/certificate.pem /certs/privatekey.pem \
  "CN=UZI-register Private Server CA G1,O=CIBG,C=NL,2.5.4.97=#130e4e54524e4c2d3530303030353335" \
  <did>

Check https://hub.docker.com/r/nutsfoundation/go-didx509-toolkit/tags for the latest version.

The output is the X509Credential as a JWT (a long string starting with eyJ). Load it into the care organization's wallet in the next step, "Load the credential into the wallet".

Non-production environments

For non-production environments, the CIBG issues test certificates whose name, URA and city don't match the real care organization. Where the use case allows it, you can instead create a fake UZI server certificate with a test CA:

  1. Check out https://github.com/nuts-foundation/go-didx509-toolkit. You need Bash and openssl.

  2. In the test_ca directory, run:

    ./issue-cert.sh <domain (CN)> <name (O)> <city (L)> <uzi> <ura> <agb>

    The domain, UZI and AGB values can be anything; use cases don't use them.

  3. The certificate chain and private key are written to the out directory. Copy them to your certs directory.

  4. Create the credential as above, but with "CN=Fake UZI Root CA" as the CA:

    docker run --rm -v "$(pwd)/certs:/certs" \
  nutsfoundation/go-didx509-toolkit:1.2.0 \
  vc /certs/somedomain-chain.pem /certs/somedomain.key \
  "CN=Fake UZI Root CA" \
  <did>

Which CAs an environment accepts is set in the use case's Discovery Service definition. For 360-graden-clientbeeld:

Environment Accepted certificates
Development, test Fake UZI certificates and CIBG test certificates
Acceptance CIBG-issued certificates (test and real), not fake ones
Production Real CIBG-issued certificates only

Lifecycle

The X509Credential is only valid as long as the UZI certificate it was created from. Create and load a new X509Credential:

  • before the UZI certificate expires, with the renewed certificate;
  • when the UZI certificate is replaced or revoked;
  • when the care organization's details in the certificate change (name, city).

Load the new credential as described in "Load the credential into the wallet".