# Decision making factors and guidelines for integrating an SSI agent / ID Gateway
###### tags: `documentation` `ssi` `eID`

## 1. Brief introduction of the technologies

This section will briefly introduce the compared technologies, as well as describe the main components, roles, and supported features. It will also touch on the associated integration efforts at a high level.

The goal is to provide a better understanding, and some guidance, on which solution should be used at this stage, depending on the requested use cases.

### 1.1. SSI (Self Sovereign Identity)

Existing SSI framework implementations aim to enable the secure and private (i.e. encrypted, signed, no correlation,, minimal data collection) exchange of Verifiable Data (i.e. signed [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#introduction)) between participants without the inclusion of a third/central party.

The following three roles are prevalent in most real world SSI deployments:
- Issuer - These are services / agents which create and transmit [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#introduction) (signed statemenets about other participants) to holders (e.g. a library issuing library cards to it's visitors). Issuers primarely interact with holders (described later).
- Verifier - These are services which consme Verifiable Credentials created by (potentially multiple) issuers, usually in exchange for a specific service (e.g. a cinema requesting and verifying a visitor's tickets on entrance, a car rental service requesting and verifying a customer's driver's license, etc.). Verifiers also primarely interact with Holders.
- Holder - These participants possess one or more verifiable credentials (collected during interactions with issuers) and generate presentations from them (when interacting with verifiers). A holder is usually, but not always, the subject of the verifiable credentials they are holding. One very common example of a holder is a regular everyday person using a mobile SSI Wallet to interact with various SSI enabled services.

The figure below shows the aformentioned roles and associated information flows:

It is worth mentioning that [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#what-is-a-verifiable-credential) can include / represent any type of information (e.g. a phone number, email address, university transcript, photo, driver's license etc.). Furthermore, it is important to note that any participant in an SSI ecosystem is able to issue credentials about any other participant (including themselves). Verifiers are expected to express which issuers they trust for particular credentials when requesting data from holders.

It is also important to note that in order to securely interact and exchange authentic information, every participant in an SSI ecosystem must have one (or more) associated [Decentralized Identifier(s)](https://www.w3.org/TR/did-core/#introduction). DIDs are designed to enable individuals and organizations to generate their own identifiers using systems they trust. These new identifiers enable entities to prove control over them by authenticating using cryptographic proofs such as digital signatures.

<small> More information on DIDs, as well as many other useful SSI concepts are also outlined [in this useful FAQ document](https://identity.foundation/faq/#identifiers-and-namespaces-layer-1). </small>

#### Integration Efforts

The integration / on-boarding effort depends on the selected / required role, as well as some use-case specific details.

- **Holders** can join an SSI ecosystem by making use of a SSI Wallet (often in the form of an application on a phone) to create a digital identity ([Decentralized Identifier](https://www.w3.org/TR/did-core/#introduction) / DID), and start interacting with various SSI enabled services to receive / present Verifiable Credentials. An example SSI Wallet is the Jolocom ONCE compliant wallet (available for [Android](https://play.google.com/store/apps/details?id=com.jolocomwallet&hl=en&gl=US) and [iOS](https://apps.apple.com/us/app/jolocom-smartwallet/id1223869062)).
- The easiest way for a service provider to start **issuing** verifiable credentials to its users is by integrating a SSI agent implementation (e.g. the [Jolocom SDK](https://github.com/jolocom/jolocom-sdk/blob/main/docs/index.md), [ACA-Py](https://github.com/hyperledger/aries-cloudagent-python), others). The exact integration effort / available functionality and API will depend to some extent on the selected agent implementation.
- Simillar integration efforts apply if a service provider would like to act as a **verifier** (i.e. request Verifiable Credentials from holders). It would be required to integrate a SSI agent implementation (e.g. [the Jolocom SDK](https://github.com/jolocom/jolocom-sdk/blob/main/docs/index.md), [ACA-Py](https://github.com/hyperledger/aries-cloudagent-python), others) with / alongside the existing service backend.

It is worth pointing out that interoperability within the SSI space is still developing, and various existing SSI platforms / deployments might not be compatible. In practice this means that one must make sure that the mobile Wallet (holder role) selected for a specific use case supports the same Verifiable Credential formats and protocols as the selected issuer / verifier agent implementation.

For example, as of now the Jolocom SmartWallet (enables holder role, available on [Android](https://play.google.com/store/apps/details?id=com.jolocomwallet&hl=en&gl=US) / [iOS](https://apps.apple.com/us/app/jolocom-smartwallet/id1223869062)) needs to be used in combination with a [Jolocom SDK](https://github.com/jolocom/jolocom-sdk/blob/main/docs/index.md) (enables issuer / verifier roles). Alternatively, using a different SSI wallet application (e.g. the [Lissi wallet](https://lissi.id/), [esatus wallet](https://esatus.com/solutions/self-sovereign-identity/?lang=en)) would similarly require a compatible SSI agent implementation (e.g. [ACA-Py](https://github.com/hyperledger/aries-cloudagent-python)) to be integrated by the issuer / verifier components.

A later section of this document will describe the supported features, as well as the associated integration efforts for the Jolocom solution. Contrasting the different existing SSI approaches in detail is outside of the scope of this document. It is worth pointing out that converging on an interoperable SSI stack (allowing most wallets to be freely used with most agent implementations) is being actively worked on in the context of the SDI projects.

### 1.2. OpenID Connect / ID Gateway
#### OpenID Connect
First of all, OpenID Connect ("OIC")is an open standard for interoperable authentication and identification. The first OIC standards were released at the beginning of 2014 while the underlying OAuth 2.0 standards were released in 2012.
> OpenID Connect is an interoperable authentication protocol based on the OAuth 2.0 family of specifications. It uses straightforward REST/JSON message flows with a design goal of “making simple things simple and complicated things possible”. It’s uniquely easy for developers to integrate, compared to any preceding Identity protocol.

<small> [See their FAQ for further details.](https://openid.net/connect/faq/)</small>

The OIC specification is mature and a vivid community cares for further development and maintenance. At the time of writing there are [13 certified libraries](https://openid.net/developers/certified/) for OpenID Connect relaying parties for almost all programming languages found in modern internet applications.

#### ID Gateway
The ID Gateway utilizes OIC and helps Service Providers with connecting multiple eID-Infrastuctures with only one technical integration.
See the following picture for an overview over the involved systems.

---

@startuml
!define osaPuml https://raw.githubusercontent.com/Crashedmind/PlantUML-opensecurityarchitecture2-icons/master
!include osaPuml/Common.puml
!include osaPuml/User/all.puml
!include osaPuml/Hardware/all.puml
!include osaPuml/Misc/all.puml
!include osaPuml/Server/all.puml
!include osaPuml/Site/all.puml

osa_user_blue(User1,"User","Service Consumer", "User")
osa_server_web(SP1,"Service Provider","Need Authentication", "system")
osa_server_identity(IDG,"ID Gateway","router to Auth-Systems", "system")
osa_server_identity(ID1,"any Auth System","Auth System", "system")
User1->SP1: Access Service
SP1->IDG: Please have an identification for me
IDG->ID1: redirect user

---

The protocol between the service provider an the ID Gateway is [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) . The protocol between ID Gateway and the connected Auth-System is Auth-System specific. Accordingly, the connection between the user and the Auth-system depends on the specified protocol there. The user could use a wallet or an ID Card or Username and Password or a totally different ID System.
The following image illustrates the different roles in an ID Gateway scenario.

#### Systems involved in ID Gateway scenarios
<small>See also [online](https://excalidraw.com/#json=4677558926835712,f_WfVnw00igR-t-uM8PTcA)</small>

From the service providers point of view the ID Gateway is the single point of contact. This connection is established at configuration time via exchanging cryptographic material (keys and certificates) so mutual recognition can happen. Any messages between these two systems are signed and on demand also encrypted. Authentication and identification messages have a short validity time for risk minimization.

The ID Gateway fullfills the authentication or identification request on behalf of the service provider ("commissioned data processing"). Legal obligations apply from the [GDPR](https://ec.europa.eu/info/law/law-topic/data-protection_de)

##### Integration Protocol

A Service Provider integrates with the ID Gateway via OpenID Connect.

In the first step the Service Provider redirects the User to the ID Gateway for authentication. The ID Gateway validates the request and, if successful, authenticates the user. Afterwards the ID Gateway redirectes a `code` to a previously configured redirect_url at the Service Provider.

Then the Service Provider sends the `code` to the ID Gateway and authenticates against it. The authentication of the Service Provider is only via backchannel. In the response the Service Provider receives a signed and possibly encrypted `id_token` containing authentication information. The `id_token` is only issued for this Service Provider. The response also contains an `access_token`. With this `access_token` the Service Provider can fetch additional user information (Step 8). This is also done via backchannel. The `userinfo` is only issued for this Service Provider and also signed and possibly encrypted.

!$C_REDIR = "#118888"
'Macro for colored Redir-block

!function redir($p)
!return "<i><color " + $C_REDIR + "> [redirect to:"+ $p + "</color>]</i>"
!endfunction

actor "User / Browser" as USER
participant "Service Provider" as RP
participant "ID Gateway" as OP

autonumber

RP->USER: redir("ID Gateway") send Authentication Request
USER->OP
OP<->USER: authenticate user with other authentication medium
OP->USER: send Authentication Response
USER->RP
RP->OP: Token Request (send Authorization Code, authorize ServiceProvider)
OP-->RP: Response contains access_token and signed id_token
RP->OP: Userinfo Request (send access_token)
OP-->RP: Response contains signed and possibly encrypted userinfo

#### Integration effort
The integration can be broken down into the following steps
- find a provider for the ID Gateway. You can also host the ID Gateway yourself, but that isn't in the scope of this document
- you will receive an Well-Known address from your operator. [See Servicekonto.nrw as an example](https://servicekonto.nrw/AutentIDConnect/sk/.well-known/openid-configuration). There you'll find all the information you need to configure your client
- The operator has to configure your client into the ID Gateway. This includes a password and redirect urls.
- and there you go :bicyclist:

#### Userinfo Token
After a successful authentication/identification you will receive an UserInfo Token. [See Spec here](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse).
The UserInfo token is a signed and optionally encrypted json structure. Any userinformation can be transmitted that way. Some attributes are defined in the [OpenID Connect Core Specification](https://openid.net/specs/openid-connect-core-1_0.html), some depend on the capabilities of the authorization server.
The following example illustrates an UserInfotoken.

{
  "sub": "e09045a2-b87c-4690-8e79-c531c373a497",
  "aud": "lzghdUKLP01X0GcRgq4C6Wj0qQ8M72vE",
  "birthdate": "1940-01-01",
  "iss": "https://head.governikus-eid.de:7000/AutentIDConnect/npa",
  "http://www.governikus.de/npa/restricted_id": "41542F44452F774A734A71686934446A48587661743742502F4E555659566574453D",
  "given_name": "Max",
  "iat": 1637160640,
  "family_name": "Mustermann",
  "jti": "9825d6e8-acea-44f8-83bb-0597a8486fa4"
}

## 2. Common / overlapping functionality, i.e. why are we comparing the approaches here?

The ONCE Wallet aggregates different sources / types of Verifiable Data which users can use in their interactions with various service providers. At this stage, the two main data types that the ONCE wallet can share are:

- [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#what-is-a-verifiable-credential)
- Data sourced from the user's electronic ID card.

with support for additional document types (e.g. Mobile Driver License) on the roadmap.

Currently the approaches to requesting these different data types are not unified. Different tooling / specifications need to be employed depending on the type of data required by the service provider. As the ONCE project develops further, we intend to enable service providers to query the ONCE Wallet for data combined from different sources / technologies (e.g. requesting eID Data alongside the Mobile Drivers License data and a [W3C Verifiable Credential](https://www.w3.org/TR/vc-data-model/#what-is-a-verifiable-credential)), but as of now this is not supported.

The currently envisioned way of realising this integration is by integrating an SSI enabled agent as one of the (potentially many) Auth-Systems used by the ID Gateway, and leveraging the already utilized OpenID Connect protocol to request / present Verifiable Credentials as well.

In practice, at the current stage, the deciding factor for a service provider choosing an approach for requesting data from the ONCE Wallet (i.e. running / integrating an SSI agent or integrating the ID Gateway) is the type of required data (i.e. Verifiable Credentials or eID data).

The next section of this document is intended to help developers select the most suitable integration, depending on their use case / required features, as well as further factors.

## 3. Distinct functionality, i.e. features supported by one solution but not the other

Besides the overlapping functionality of enabling users to share (and enabling services to request) certain types of signed / authentic information, the outlined technologies have further, solution specific features which might be relevant.

### SSI:
- Allows for issuance of authentic information (in the form of W3C Verifiable Credentials containing any use case specific data), not only for requesting / consumption.
- "Anyone" can issue and request Verifiable Credentials, no entry barrier for issuers.
- The data which can be issued / requested is not limited to eID data. Verifiable Credentials are quite flexible, and can be used to model almost any use case (e.g. doctor prescriptions, official documents, event tickets, cntracts and receipts, etc.).

### OpenID Connect / ID Gateway

- Service Provider can stay agnostic to connected eID-Systems
- Server-2-Server Federation support (eIDAS, Servicekonten, Elster, ...)
- ID Gateway can leverage the usage of SSI as a proxy to SSI Infrastructures and integration of wallets
- only known systems can interact - so the system is auditable

Another factor to take into consideration is that the SSI space is still actively maturing and evolving, while the eID infrastructure is more stable and established. It is more likely you will encounter breaking changes / more frequent updates when using the approach based on SSI / the Jolocom Agent. We foresee major (interoperability driven) modifications / updates during 2022 (with first releases of an updated SSI implementation planned for end of Q1 2022).

## 4. What are the supported features (comparison table)
There are a number of differences depending on the chosen approach:
In order to make editting this section easier, we can use this spreadsheet:

https://docs.google.com/spreadsheets/d/1i8hIoTbZVNMe9amWFQDkq5zVNDxhwIoqBom01lbDJUI/edit?usp=sharing

The matrix compares both technologies across a set of criteria (privacy, operating costs, legal considerations). It is worth re-iterating that will be updated as both technologies evolve further.

## 5. Integration guide

In this section we will provide more detailed integration documentation (in addition to high level descriptions in sections 1.1. and 1.2. of this document).

It is worth pointing out that regardless of the selected technology / solution, the same user facing client application can be used, namely the ONCE compliant Jolocom SmartWallet. A service provider will be able to request both W3C Verifiable Credentials (as described below), as well as eID data ([as documented here](https://hackmd.io/@once-sdi/rkCQpqZSK)) from the ONCE compliant Wallet.

### 5.1. The Jolocom SSI Stack

As mentioned in section [1.1. SSI introduction](https://hackmd.io/EzBvbwMyTyWu-LsHFlspbw?both#Integration-Efforts) -- the on-boarding / integration efforts will depend on the selected role, SSI technology stack, and use case complexity.

Luckily, for end users (natural persons, credential holders), the entry barrier is quite low. They need to download and install a mobile SSI wallet of their choice, e.g. the Jolocom SmartWallet(available on [Android](https://play.google.com/store/apps/details?id=com.jolocomwallet&hl=en&gl=US) / [iOS](https://apps.apple.com/us/app/jolocom-smartwallet/id1223869062)).

In this section we will focus on the Jolocom technology stack (which is being actively improved), but alternative solutions also exist, and might be more suitable for particular use cases / deployments.

In order to be able to issue Verifiable Credentials, a service provider needs to manage / run an instance of an SSI agent alongside their service backend. This can be achieved by directly integrating the [Jolocom SDK](https://github.com/jolocom/jolocom-sdk/blob/main/docs/index.md) (available as a JavaScript module) with their service backend. The agent instance abstracts away some of the complexity related to:
- Creating and managing DIDs, as well as the associated cryptographic keys ([documentation](https://github.com/jolocom/jolocom-sdk/blob/main/docs/guides/identity.md)).
- Creating / signing [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#introduction) ([documentation](https://github.com/jolocom/jolocom-sdk/blob/main/docs/guides/credentials.md)).
- Exchanging (i.e. issuing, and requesting) Verifiable Credentials with other parties ([documentation](https://github.com/jolocom/jolocom-sdk/blob/main/docs/guides/interaction_flows.md#verifiable-credential-issuance)).

**In case you decide to integrate the Jolocom SDK directly**, the [following example repository](https://github.com/jolocom/jolocom-example-service) (containing a simple service backend integrated with the SDK) can be a useful starting point / reference. The [included API documentation](https://github.com/jolocom/jolocom-example-service/blob/master/src/api/openapi.yaml) and [architecture diagram](https://github.com/jolocom/jolocom-example-service#structure) provide further context related to supported features.

Integrating the Jolocom SDK directly might be undesirable in some cases (e.g. for very simple use cases which would rather skip the overhead associated with managing an agent and the associated DIDs), or impossible in others (e.g. the service backend is written in a language other than JavaScript).

**An alternative, much simpler, integration path is also available**, which relies on using a containerized version of the Jolocom SDK, and interacting with it via a local RPC interface. The RPC server / client implementations can be [found in this repository](https://github.com/jolocom/sdk-rpc-interface). The two packages included in the repository are:
- [Server component](https://github.com/jolocom/sdk-rpc-interface/tree/master/packages/server) -- a simple WebSocket server, which exposes a set of methods supported by the Jolocom-SDK via a [JSON-RPC](https://www.jsonrpc.org/specification) based interface.
- [Client component](https://github.com/jolocom/sdk-rpc-interface/tree/master/packages/client) -- a instance of the RPC client can be used to interact with a locally running instance of the SDK RPC server and initiate / undergo Verifiable Credential issuance and request flows. The client is rather thin, and is mostly responsible for assembling correct [JSON-RPC](https://www.jsonrpc.org/specification) requests, and handling responses received from the server.

The included README documents, alongside this [additional documentation](https://jolocom.notion.site/Jolocom-SDK-RPC-description-8b3c925c6f88438c9f1797897616f158) describe the supported features / interaction flows in more detail, and provide instructions for how to configure and run the components.

All of the supported flows can be tested out (with the Jolocom SmartWallet) using one of the following demo resources:
- [Interactions demo service](https://interxns.jolocom.io/) ([source code](https://github.com/jolocom/interactions-demo)) - Developer oriented demo service, can be used to issue / request various credentials from the SmartWallet, as well as undergo other interactions.
- [The Avalon](https://avalon.jolocom.com/) / [Aelondo](https://aelondo.jolocom.com/) - Simple (issuer, verifier) demo services showcasing inter-connected verifiable credential exchange flows.