Quick Start

This guide will help you quickly get started with UniCore. You will:

Deploy a UniCore instance locally using Docker Compose.
Issue a Credential to a user.
Verify that Credential.

Prerequisites

Docker
UniMe app or any other Identity Wallet that supports the following standards:
- OpenID for Verifiable Credential Issuance Working Group Draft 13
- OpenID for Verifiable Presentations Working Group Draft 20
- Self-Issued OpenID Provider v2 Working Group Draft 13

Download UniMe

Download the UniMe app on your mobile device:

Configuration

1. Create a Docker Compose file

Create a new compose.yaml file with the following content:

name: ssi-agent

services:
  mongodb:
    image: mongo:8
    restart: always
    ports:
      - 27017:27017
    command: "mongod --replSet rs0"
    healthcheck:
      test: |
        mongosh --quiet --eval "try { rs.status().ok } catch (e) { rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: 'localhost:27017' }] }).ok }"
      interval: 5s
      timeout: 5s
      retries: 5

  ssi-agent:
    image: impiercetechnologies/ssi-agent:1.0.0-beta.13
    depends_on:
      - mongodb
    ports:
      - 3033:3033
      - 9091:9091
    environment:
      UNICORE__PROFILE: development
      UNICORE__APPLICATION_URL: ${UNICORE__APPLICATION_URL}
      UNICORE__EVENT_STORE__TYPE: mongodb
      UNICORE__EVENT_STORE__CONNECTION_STRING: mongodb://mongodb:27017/ssi-agent?directConnection=true&retryWrites=false&replicaSet=rs0
      UNICORE__SECRET_MANAGER__STRONGHOLD_PASSWORD: "secure_password"
      UNICORE__METRICS__ENABLED: true
      UNICORE__METRICS__PORT: 9091

info

UNICORE__PROFILE: development enables UniCore's development mode, which requires less initial configuration and enables a more verbose API and debugging information.

2. Create an `.env` file

Create a new .env file in the same directory as the compose.yaml file with the following content:

UNICORE__APPLICATION_URL=${UNICORE__APPLICATION_URL}

3. Set the `UNICORE__APPLICATION_URL` environment variable

Set the UNICORE__APPLICATION_URL environment variable in your shell that contains your local IP address:

export UNICORE__APPLICATION_URL=http://<your-local-ip-address>:3033

note

The UNICORE__APPLICATION_URL variable can also be set in the .env directly. However, for the purpose of this quick start, it is more practical to set the variable in the shell session as shown above, allowing it to be reused in the curl commands throughout this guide.

Replace <your-local-ip-address> with your machine's local IP address. This might help you find your local IP address:

# macOS
ipconfig getifaddr en0

# Linux
hostname -I

# Windows (PowerShell)
Get-NetIPAddress

warning

Using localhost or 127.0.0.1 will not work when trying to access UniCore from another device on the network. Your local IP address is most likely in the range 192.168.x.x or 10.x.x.x (or similar).

note

Make sure to set export UNICORE__APPLICATION_URL in the same terminal session where you will also run docker compose up, or ensure that the variable is available in your environment.

Deployment

Run the following command:

docker compose up

This will start UniCore, together with a local Postgres database and a database admin tool (pg-admin) to inspect the data.

Issuing a Credential

To issue a Credential, follow these steps:

1. Post the Credential data to UniCore's HTTP API

Open a new terminal window and ensure the UNICORE__APPLICATION_URL is set as described in this section:

Then run:

curl --location "$UNICORE__APPLICATION_URL/v0/credentials" \
--header 'Content-Type: application/json' \
--data '{
    "offerId":"001",
    "credentialConfigurationId": "001",
    "credential": {
        "credentialSubject": {
            "first_name": "John",
            "last_name": "Doe"
        }
    },
    "expiresAt": "never"
}'

This command sends a POST request to create a new Credential Offer with the specified data.

2. Retrieve the URL-Encoded Credential Offer

Run:

curl --location "$UNICORE__APPLICATION_URL/v0/offers" \
--header 'Content-Type: application/json' \
--data '{
    "offerId": "001"
}'

This returns the URL-encoded Credential Offer.

3. Render the Credential Offer as a QR Code

To proceed, you need to render the URL-encoded Credential Offer as a QR code. You can use any method or tool you prefer to generate the QR code. Here are some options:

Option 1: Using Command Line with qrencode

Install qrencode via your preferred package manager, then generate the QR code:

qrencode -o credential-offer.png -s 10 '<URL-ENCODED-CREDENTIAL-OFFER>'

Replace <URL-ENCODED-CREDENTIAL-OFFER> with the actual value returned from the previous step.
note
The URL-encoded Credential Offer to be encoded must be enclosed within single quotes ' '.

Open the QR code image:

open credential-offer.png

Option 2: Using Online QR Code Generators

Go to an online QR code generator such as https://www.the-qrcode-generator.com/.
Paste the URL-encoded Credential Offer into the text field (as Plain Text).
Generate the QR code image.

note

The key requirement is to generate a QR code from the URL-encoded Credential Offer so that it can be scanned by the UniMe app.

4. Scan the QR Code with UniMe

Open the UniMe app on your mobile device.
Scan the QR code to accept the Credential Offer.

Credential Offer

After accepting, the Credential will appear in the UniMe app.

Verifying a Credential

Now, request the user to present their Credential:

1. Create a URL-Encoded Authorization Request

Ensure the UNICORE__APPLICATION_URL environment variable is set (if not, set it again):

export UNICORE__APPLICATION_URL=http://<your-local-ip-address>:3033

Then run:

curl --location "$UNICORE__APPLICATION_URL/v0/authorization_requests" \
--header 'Content-Type: application/json' \
--data '{
    "nonce": "this is a nonce",
    "state": "state_id",
    "dcql_query": {
        "credentials": [
            {
                "id": "CredentialQuery",
                "format": "jwt_vc_json",
                "meta": {
                    "type_values": [
                        ["VerifiableCredential"]
                    ]
                }
            }
        ]
    }
}'

This creates an Authorization Request specifying the type of Credential that is being requested.

2. Render the Authorization Request as a QR Code

Similar to how you generated the QR code for the Credential Offer, you now need to render the URL-encoded Authorization Request as a QR code. You can use the same method you used earlier:

If using qrencode, run:

qrencode -o authorization-request.png -s 10 '<URL-ENCODED-AUTHORIZATION-REQUEST>'

Replace <URL-ENCODED-AUTHORIZATION-REQUEST> with the actual value returned from the previous step.
note
The URL-encoded Authorization Request to be encoded must be enclosed within single quotes ' '.
Open the QR code image:

  open authorization-request.png

If using an online tool or app, input the URL-encoded Authorization Request to generate the QR code.

info

The process of generating the QR Code is exactly the same; you're just using the new URL-encoded Authorization Request instead of the Credential Offer.

3. Scan the QR Code with UniMe

Now scan the QR code using the UniMe app.
The app will prompt to share the Credential.

Authorization Request

Upon acceptance, UniCore will verify the validity of the Credential.

In order to check whether the Credential was successfully verified by UniCore, you can run the following command:

curl --location 'http://localhost:3033/v0/authorization_requests/state_id'

This will return an object containing a "vp_token" field. If the value of this field is not null, the Credential was successfully verified.

Troubleshooting

Problem: QR code not scanning.

Solution: Ensure the QR code contains the correct URL-encoded data and that it's clear enough for the camera to read.
Problem: Cannot connect to UniCore from mobile device.

Solution: Check that both devices are on the same network and that firewall settings allow incoming connections on port 3033.

Additional Notes

Firewall Settings: Ensure your machine allows incoming connections on the required ports.
Access from Mobile Device: Your mobile device must be on the same network as your UniCore instance.
Environment Variables: Remember that environment variables set in your shell are not persisted across terminal sessions. You may need to set UNICORE__APPLICATION_URL in each new terminal or include it in your shell's startup script.

By following this guide, you've:

Deployed UniCore locally.
Issued a Credential to a user.
Verified the Credential using the UniMe app.

Prerequisites​

Download UniMe​

Configuration​

1. Create a Docker Compose file​

2. Create an .env file​

3. Set the UNICORE__APPLICATION_URL environment variable​

Deployment​

Issuing a Credential​

1. Post the Credential data to UniCore's HTTP API​

2. Retrieve the URL-Encoded Credential Offer​

3. Render the Credential Offer as a QR Code​

4. Scan the QR Code with UniMe​

Verifying a Credential​

1. Create a URL-Encoded Authorization Request​

2. Render the Authorization Request as a QR Code​

3. Scan the QR Code with UniMe​

Troubleshooting​

Additional Notes​

Prerequisites

Download UniMe

Configuration

1. Create a Docker Compose file

2. Create an `.env` file

3. Set the `UNICORE__APPLICATION_URL` environment variable

Deployment

Issuing a Credential

1. Post the Credential data to UniCore's HTTP API

2. Retrieve the URL-Encoded Credential Offer

3. Render the Credential Offer as a QR Code

4. Scan the QR Code with UniMe

Verifying a Credential

1. Create a URL-Encoded Authorization Request

2. Render the Authorization Request as a QR Code

3. Scan the QR Code with UniMe

Troubleshooting

Additional Notes