walt.id Identity on AWS User Guide

Overview

This image runs walt.id Identity, an open source platform for decentralized identity and verifiable credentials. It gives you the building blocks to issue, hold and verify W3C Verifiable Credentials using open standards including OpenID for Verifiable Credential Issuance (OID4VCI), OpenID for Verifiable Presentations (OID4VP) and Decentralized Identifiers (DIDs).

walt.id Identity 0.22.0 is deployed from the pinned upstream container images, each managed by a systemd service that starts it on boot and restarts it on failure:

• The Issuer API on port 7002 issues Verifiable Credentials to wallets over OID4VCI
• The Verifier API on port 7003 requests and verifies Verifiable Presentations over OID4VP, running configurable credential and presentation policies
• The Wallet API on port 7001 (bound to loopback) is a server side holder wallet that can receive, store and present credentials, backed by a local SQLite database
• The web wallet is a browser user interface, served on port 80 through an nginx reverse proxy, for registering, holding and presenting credentials

The Wallet API state - the holder accounts, keys and stored credentials - lives on a dedicated, independently resizable EBS data volume mounted at /var/lib/waltid, so your data survives instance replacement. On the first boot of every deployed instance a one shot service generates unique wallet signing and encryption keys and a unique wallet administrator account, written to /root/waltid-credentials.txt with mode 0600 so only the root user can read it. No administrator, no shared secret and no default credential ship in the image.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, port 80 for the web wallet, and ports 7002 and 7003 if you will call the Issuer and Verifier APIs from your own applications
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for walt.id Identity. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger; walt.id Identity runs three JVM API services plus the web wallet, so it needs the memory. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network, port 80 for the web wallet, and ports 7002 and 7003 for the Issuer and Verifier APIs. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation generates the per instance wallet keys and administrator account; on a fresh instance this takes a minute or two after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg walt.id Identity Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, 7002 and 7003 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=waltid-identity}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Retrieve the Wallet Administrator Credentials

On the first boot of your instance, a unique wallet administrator account and unique wallet signing keys are generated. Retrieve them with:

sudo cat /root/waltid-credentials.txt

The file lists the wallet administrator email (waltid-admin@localhost) and password, and the Issuer, Verifier and Wallet API URLs. Store the password somewhere safe; it is unique to this instance.

Step 5: Open the Web Wallet

Browse to http://<public-ip>/ to open the web wallet, served on port 80 through nginx. Sign in with the wallet administrator email and password from the credentials file, or choose Sign up here to register a new holder account.

After signing in you land on the credentials view, which lists the Verifiable Credentials held by the wallet. Use Receive to claim a credential from an issuer and Present to share one with a verifier.

Select a credential to see its detail: the issuer Decentralized Identifier, the validity period and the raw credential JSON.

Step 6: Verify the Services Are Running

Confirm the platform services are active and answering on the instance:

systemctl is-active docker waltid-issuer waltid-verifier waltid-wallet waltid-demo-wallet nginx
echo "web wallet:  $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/)"
echo "issuer api:  $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:7002/swagger/index.html)"
echo "verifier api:$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:7003/swagger/index.html)"

Each service should report active and each endpoint should return 200.

Step 7: Issue, Hold and Verify a Credential (Built In Self Test)

The image ships an end to end self test that proves the whole flow using only the on box APIs: it mints an issuer key, issues an OpenBadge Verifiable Credential, has the wallet claim it, has the verifier request a presentation, has the wallet present it, and asserts the verifier reports the presentation as verified.

sudo /usr/local/sbin/waltid-selftest.sh

A successful run prints SELFTEST_OK issue->hold->verify verified=true.

Step 8: Using the Issuer and Verifier APIs

The Issuer API (port 7002) and Verifier API (port 7003) expose interactive OpenAPI documentation at the /swagger path. Open http://<public-ip>:7002/swagger and http://<public-ip>:7003/swagger in a browser to explore the endpoints, or integrate them into your own applications to issue and verify W3C Verifiable Credentials over OID4VC.

The Issuer and Verifier learn the instance public address on every boot and embed it into the credential offers and presentation requests they produce, so offers and requests point at the right host with no hand editing. The Wallet API is bound to loopback and reached through the web wallet on port 80, or from the instance itself, or over an SSH tunnel:

ssh -i /path/to/your-key.pem -L 7001:127.0.0.1:7001 ubuntu@<public-ip>

With the tunnel open, browse to http://127.0.0.1:7001/swagger on your workstation.

Step 9: The Dedicated Data Volume

The Wallet API state - the holder accounts, keys and stored credentials - lives on a dedicated EBS data volume mounted at /var/lib/waltid, separate from the operating system disk, so it survives instance replacement and can be resized independently.

df -h /var/lib/waltid

To grow the wallet data tier, expand the EBS volume in the AWS console, then extend the filesystem on the instance with sudo resize2fs on the mounted device.

Step 10: Production Hardening with Your Own DNS and TLS

For production, front the services with your own domain name and TLS. Point a DNS record at the instance, terminate HTTPS at nginx (or an AWS load balancer) with a certificate for your domain, and restrict the Issuer and Verifier security group rules to the networks that need them. Because the Issuer and Verifier derive their public base URL from the instance address on each boot, set the base URLs explicitly to your domain in /etc/waltid/issuer/config/issuer-service.conf and /etc/waltid/verifier/config/verifier-service.conf once you place them behind a stable hostname, and restart the two services.

Support

This image is maintained by cloudimg with 24/7 technical support by email and chat. We can help with deployment, the Issuer, Verifier and Wallet APIs, OID4VC and DID configuration, credential and presentation policies, the web wallet, TLS and runtime tuning. walt.id Identity is licensed under the Apache License 2.0; the cloudimg charge covers packaging, security patching, image maintenance and support.