v0.15.0

Getting started

This page shows how to get started with verifying or issuing IRMA attributes, using the following components:

  • irma server, a server that verifies or issues IRMA attributes to Yivi apps,
  • yivi-frontend, a JavaScript library for drawing the Yivi QR in your website, and handling IRMA session with the irma server.

You should have the Yivi app installed (Android, iOS). If you want to compile from source instead of using prebuilt binaries, you should additionally have Git, Go, and npm installed.

Installing and running irma server

You can install the irma command line tool in the following two ways.

  • Download prebuilt binary: From GitHub. Choose the binary for your OS and architecture (most likely amd64). Rename the file to /usr/local/bin/irma to have it available in your PATH.
  • Compile and install from source as follows: 
    go install github.com/privacybydesign/irmago/irma@latest
  • Using Docker: 
    docker pull ghcr.io/privacybydesign/irma:latest

After installing the irma binary, start the server (with increased verbosity but otherwise default configuration):

  • Using a prebuilt binary or compiled from source: 
    irma server -v
  • Using Docker: 
    IP=192.168.1.2 # Replace with your local IP address.
docker run -p 8088:8088 ghcr.io/privacybydesign/irma:latest server -v --url "http://$IP:port"

Run irma server -h to see configuration options. In order to verify your configuration, run irma server check -v. General documentation can be found on the irma server page, API documentation of HTTP endpoints can be found on the api irma server page.

Perform a command line IRMA session

Given a running IRMA server (see above), you can perform a first IRMA session using your server on the command line as follows:

  • Using a prebuilt binary or compiled from source: 
    irma session --server http://localhost:8088 --disclose pbdf.pbdf.irmatube.type
  • Using Docker 
    IP=192.168.1.2 # Replace with your local IP address.
docker run ghcr.io/privacybydesign/irma:latest session --server "http://$IP:8088" --disclose pbdf.pbdf.irmatube.type

IRMATube attributes are available on the IRMATube demo page. This will print a QR that you can scan with your Yivi app, and the attribute contents after they have been received and verified by the server. irma session can also perform issuance sessions and attribute-based signature sessions. If you pass -v it logs the session request JSON that it sends to your irma server.

Installing an example webpage for yivi-frontend

Download the yivi-frontend-packages source code, as zip from GitHub, or using git:

git clone https://github.com/privacybydesign/yivi-frontend-packages && cd yivi-frontend-packages

Examples for the browser and for nodejs are included in the examples folder. In this guide we will use the yivi-frontend example for browsers to realize the example webpage. This example has to be installed first.

cd examples/browser/yivi-frontend/
npm install
npm run build

Perform browser IRMA session

(Re)start your irma server, configuring it such that it statically hosts the yivi-frontend example webpage we just built:

  • Using a prebuilt binary or compiled from source: 
    irma server -v --static-path ~/yivi-frontend-packages/examples/browser/yivi-frontend
  • Using Docker: 
    IP=192.168.1.2 # Replace with your local IP address.
docker run -v ~/yivi-frontend-packages:/yivi-frontend-packages -p 8088:8088 ghcr.io/privacybydesign/irma:latest server -v --url "http://$IP:port" --static-path /yivi-frontend-packages/examples/browser/yivi-frontend

A webpage demoing IRMA attribute issuance verification should now be available at http://localhost:8088.

Open the browser console and the console running irma server to see various log messages and possibly error messages as the IRMA session proceeds.

Example configuration and IRMA session

Generally, your IRMA server runs in your backend alongside a server application serving your frontend (website), with which the Yivi app user is interacting. Your server application starts and manages sessions at your IRMA server to verify or issue attributes (for example, when the user wants to log in). This can be setup as follows.

Configure irma server

In production it is generally best to authenticate incoming session requests from your application. The following is an example production configuration file (in YAML) for the irma server (start with irma server -c /path/to/config.yml) that will accept session requests if they include a Authorization: mysecrettoken HTTP header.

production: true
email: "example@example.com"  # see https://irma.app/docs/email

port: 443
url: "https://example.com/irma/"
tls_cert: "/etc/letsencrypt/live/example.com/fullchain.pem"
tls_privkey: "/etc/letsencrypt/live/example.com/privkey.pem"

no_auth: false
requestors:
  myapp:
    auth_method: "token"
    key: "mysecrettoken"
  • You may want to restrict permissions to verify or issue specific attributes, globally or per requestor.
  • The server can be made into a daemon on most Linux systems using a systemd unit file.
  • Another common setup is to have a reverse proxy between the IRMA server and the internet, which handles TLS instead and forwards traffic on https://example.com/irma/ to the IRMA server.

Perform a session

Assuming your application runs on the same server as the IRMA server, your application can now start a session at your IRMA server as follows (using curl as example):

curl https://example.com/session \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: mysecrettoken" \
  -d '{
        "@context": "https://irma.app/ld/request/disclosure/v2",
        "disclose": [[["irma-demo.MijnOverheid.ageLower.over18"]]]
      }'

This will output something like the following:

{
  "token": "X7LU5Q8Jhig0330gjYUO",
  "sessionPtr": {"u": "https://example.com/irma/t1nXs4ZduyhvAeAAlB77","irmaqr": "disclosing"},
  "frontendRequest":{"authorization":"X9XeI0gJG2HZv4hZ1WkP","minProtocolVersion":"1.0","maxProtocolVersion":"1.1"}
}

Instead of managing sessions with HTTP requests as shown here, for certain languages (currently Go and JavaScript) it is also possible to include an IRMA library and manage sessions using function invocations.

Issuing IRMA attributes

This page mostly focuses on verifying, i.e. receiving IRMA attributes from Yivi apps and establishing their authenticity. Issuing attributes to Yivi apps can be done with the same software and with largely similar flows, but is more involved, because the identity of prospective issuers need to be verified and the contents and structure of the credentials to be issued needs to be established. This process is documented (among other things) in the issuer guide.

For experimenting and demoing, however, it is possible to issue any of the existing credentials within the irma-demo scheme. For example, if the requestors block in the YAML example configuration of the IRMA server above would include permission to issue irma-demo attrbutes, as follows:

requestors:
  myapp:
    auth_method: "token"
    key: "mysecrettoken"
    issue_perms:
      - "irma-demo.*"

Then an issuance session for the credential used in the example disclosure session above can be started at the IRMA server as follows:

curl https://example.com/session \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: mysecrettoken" \
  -d '{
        "@context": "https://irma.app/ld/request/issuance/v2",
        "credentials": [
          {
            "credential": "irma-demo.MijnOverheid.ageLower",
            "attributes": {
              "over12": "yes",
              "over16": "yes",
              "over18": "yes",
              "over21": "no"
            }
          }
        ]
      }'

To issue a demo credential of your own not already present in the irma-demo scheme, see the issuer guide.

← What is IRMA?Stateless IRMA server →