Skip to content

Install the Issuance Service

This article sets up an instance of the credential issuance service. If you have not run either service before, work through the quickstart first — it brings up the issuer, the verifier and their database together and covers the prerequisites once.

Requirements

  • Docker with the Compose plugin.
  • OpenSSL, to generate the signing certificate.
  • Access to Partisia's container registry: docker login registry.gitlab.com. Please book a call with us to arrange it.
  • A PostgreSQL database the service can reach, with a database created for it. See Database.

Configure the service

The service reads a single JSON configuration file, conventionally server.json. This example is a complete working configuration:

server.json
{
  "port": 8079, // (1)!
  "baseUrl": "http://localhost:8079", // (2)!
  "database": { // (3)!
    "persistenceUnitName": "model",
    "driver": "org.postgresql.Driver",
    "url": "jdbc:postgresql://postgres:5432/issuer",
    "user": "postgres",
    "password": "postgres"
  },
  "issuer": { // (4)!
    "id": "localhost",
    "display": {
      "name": "Credential Issuer",
      "logoFile": "conf/static/partisia-logo.png"
    }
  },
  "signing": { // (5)!
    "keyFile": "conf/signing-key/issuer-localhost.key",
    "certificateFiles": [
      "conf/signing-key/issuer-localhost.pem"
    ]
  },
  "integrations": { // (6)!
    "authentication": {
      "api-key": "Local development"
    }
  }
}
  1. REST endpoint port. Required.
  2. The address this service advertises to wallets. Required — a wallet uses it to fetch the credential offer, metadata and the credential itself, so it must be an address the wallet can reach.
  3. PostgreSQL connection. Required.
    • For a full explanation of this field see Database.
  4. Information about the issuer.
    • id becomes the iss claim of every credential this service issues. It is a plain identifier string, not a key or an address.
    • display is issuer-level metadata a wallet may show alongside the credential: a name, and optionally a logoFile pointing at an image inside the container.
  5. The signing key and certificate chain. Required — the service will not start without them.
  6. API keys accepted on the administrative endpoints. The JSON key is the token; the value is a label.
    • For a full explanation of this field see API keys.

Every other setting is optional. For the complete list, including the external authorization server and the status list, see the configuration reference.

Paths are relative to the container

keyFile, certificateFiles and logoFile are resolved against the container's working directory, /app. Mount your configuration directory there — ./issuer/conf:/app/conf:ro — and a path of conf/signing-key/x.key then refers to issuer/conf/signing-key/x.key on the host.

Generate the signing certificate

mkdir -p issuer/conf/signing-key
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -keyout issuer/conf/signing-key/issuer-localhost.key \
  -out    issuer/conf/signing-key/issuer-localhost.pem \
  -days 365 -subj "/CN=localhost" -sha256

This is a self-signed pair, which is right for local work. Facing verifiers you do not operate, you need a certificate chaining to a root they trust — see Signing certificates.

The optional authorization server

The issuance protocol requires an OAuth 2.0 authorization server, so that credentials are only issued to authorized holders. That server must support the pre-authorized code flow.

If you do not want to run your own, leave authorizationServer out of server.json. When the field is absent the issuance service acts as the authorization server itself, which is what the example above does. To point it at your own server instead:

"authorizationServer": {
  "baseUrl": "https://auth.example.org"
}

Setting this changes how issuances start: you obtain a pre-authorized code from your own server and pass it in. See OAuth 2.0 integration.

Run it

Run the image with your configuration directory mounted:

docker run -d \
  -p 8079:8079 \
  -w /app \
  -v "$(pwd)/issuer/conf:/app/conf:ro" \
  registry.gitlab.com/secata/platform/did/release/issuer-backend:latest

The issuer and verifier are released independently but tested as pairs, so pull both at the same time. See Going to production for recording which version you run.

In practice you will run this alongside the database with Compose; the quickstart has a complete docker-compose.yml.

The log prints Starting server when the service is ready. Navigate to http://localhost:8079/openapi for the API specification, where you can try the endpoints directly. Remember to supply your API key — the administrative endpoints return 401 without it.

What's next?

The issuance service is now able to talk to wallets and issue credentials.

  1. Create a credential configuration. The service cannot issue anything until you declare what it is allowed to issue.
  2. Start an issuance. What your own application calls, and when.
  3. Receive the issued credential. Configure a callback so your application is told when a credential has been delivered, instead of polling.

Troubleshooting

Startup, connection and request failures are collected in Troubleshooting.