@cef-ebsi/ebsi-siop-auth v0.2.0

EBSI SIOP Auth Library

EBSI Auth library for natural persons and legal entities.

Table of Contents

1. Installation
2. Authentication Flow
3. Usage
4. Library Test
5. Licensing

Installation

npm install @cef-ebsi/siop-auth

or if you use yarn

yarn add @cef-ebsi/siop-auth

Authentication Flow

The current EBSI SIOP Auth implementation follows RFC - DID-OIDC for NP/LE Authentication to EBSI & Relying Party in EBSI V2, which uses two JSON Web Tokens (JWT) signed by both two parties DID keys in a double challenge-response authentication.

Current version supports only ES256K algorithm (the EC secp256k1) and did:ebsi DID method.

Note: This version implemented does have support for custom claims. (i.e. using VerifiableID).

The DID Auth flow has the following steps involving a natural person or legal entity (NP/LE) and a relying party (RP):

1. createAuthenticationRequest (RP)

• A NP, i.e. user, with a valid ebsi:did already generated, accesses on an Institution web site, i.e. the RP, and clicks to a Login button
• RP creates an EbsiDidAuth URI Request calling EbsiDidAuth.createAuthenticationRequest with this payload:

const didAuthRequestCall: DidAuthRequestCall = {
  redirectUri: "https://app.ebsi.xyz/demo/spanish-university", // Redirect URI after successful authentication
  hexPrivateKey: , "0x33fbb77871a3...3b44a67" // RP private key used to sign the token
  issuer: "did:ebsi:BdFneNpniW3DE639yY6sEga9GhwdZ3jSdfJ1EyURMPx5" // RP did
  kid: "https://api.test.intebsi.xyz/did-registry/v2/identifiers/did:ebsi:BdFneNpniW3DE639yY6sEga9GhwdZ3jSdfJ1EyURMPx5#keys-1" // kid that resolve public keys for the signer (RP)
};

// Creates a URI using the wallet backend that manages entity DID keys
const { uri } = await EbsiDidAuth.createAuthenticationRequest(didAuthRequestCall);

• RP receives an Open ID URI and nonce as a result:

openid://?response_type=id_token&client_id=http%3A%2F%2Fapp.ebsi.xyz%2Fdemo%2Fspanish-university&scope=openid%20did_authn&state=7b24331f73fd65a37a0ea915&nonce=_fRDy4lli3gTctXx9evaLJowCZkb2xQcrqnlcNrruKk&request=eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QiLCJraWQiOiJodHRwczovL2FwaS50ZXN0LmludGVic2kueHl6L2RpZC1yZWdpc3RyeS92Mi9pZGVudGlmaWVycy9kaWQ6ZWJzaTpCZEZuZU5wbmlXM0RFNjM5eVk2c0VnYTlHaHdkWjNqU2RmSjFFeVVSTVB4NSNrZXlzLTEifQ.eyJpYXQiOjE2MTg5MDQ0MDEsImV4cCI6MTYxODkwNDcwMSwiaXNzIjoiZGlkOmVic2k6QmRGbmVOcG5pVzNERTYzOXlZNnNFZ2E5R2h3ZFozalNkZkoxRXlVUk1QeDUiLCJzY29wZSI6Im9wZW5pZCBkaWRfYXV0aG4iLCJyZXNwb25zZV90eXBlIjoiaWRfdG9rZW4iLCJjbGllbnRfaWQiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvZGVtby9zcGFuaXNoLXVuaXZlcnNpdHkiLCJzdGF0ZSI6IjdiMjQzMzFmNzNmZDY1YTM3YTBlYTkxNSIsIm5vbmNlIjoiX2ZSRHk0bGxpM2dUY3RYeDlldmFMSm93Q1prYjJ4UWNycW5sY05ycnVLayJ9.h2nlz3AeflzTkh_E2oIvjR_h_0OdB1DDW1maB9Zt3bcfzjYe0Yynl8BJbMB206GySJeZ4d53TuBm8kwSJ2HurA

Note: RP needs to store nonce, found inside the Request token to be used on the response validation process.

• RP redirects to the front-end passing DID-Auth URI.

2. verifyAuthenticationRequest (NP/LE)

• User parses the received EBSI DID Auth Request URI to obtain request URL parameter to be used to verify the token and create the Response token:

const params = new URLSearchParams(didAuthUri);
const didAuthRequestJwt = params.get("request");
const didResolver = "https://api.intebsi.xyz/did/v1/identifiers";

// VERIFY DID-AUTH REQUEST
const requestPayload: DidAuthRequestPayload = await EbsiDidAuth.verifyAuthenticationRequest(
      didAuthRequestJwt as string,
      didResolver as string
    );
console.log(requestPayload); // verified didAuthRequestJwt payload
/*
{
      iat: 1618912769,
      exp: 1618913069,
      iss: 'did:ebsi:BdFneNpniW3DE639yY6sEga9GhwdZ3jSdfJ1EyURMPx5',
      scope: 'openid did_authn',
      response_type: 'id_token',
      client_id: 'http://localhost:8080/demo/spanish-university',
      state: '191340de0f14683a2282375a',
      nonce: 'sSvVr4kc-Bh76Z4kA5hJ7M9FnoIjxHoZ6GMiQklykGA'
    }
*/

3. createAuthenticationResponse (NP/LE)

• After a successful validation, user creates an EBSI SIOP Auth Response JWT token calling EbsiDidAuth.createAuthenticationResponse, reusing the Request nonce and state.

// CREATE A DID-AUTH RESPONSE
const didAuthResponseCall: DidAuthResponseCall = {
  hexPrivatekey: userPrivateKey, // private key managed by the user. Should be passed in hexadecimal format
  did: "did:ebsi:0x226e2e2223333c2e4c65652e452d412d50611111", // User DID
  state: requestPayload.state, // same state received as a Request Payload after verifying it
  nonce: requestPayload.nonce, // same nonce received as a Request Payload after verifying it
  redirectUri, // parsed URI from the DID Auth Request payload
};
const didAuthResponseJwt = await EbsiDidAuth.createAuthenticationResponse(
  didAuthResponseCall
);

• User redirects to the RP redirectUri URI passing the Response token as a parameter:

https://app.ebsi.xyz/demo/spanish-university?response=<Signed JWT Response Object>

4. verifyAuthenticationResponse (RP)

• RP verifies the DID Auth Response token calling EbsiDidAuth.verifyAuthenticationResponse passing the stored nonce:

const response = await EbsiDidAuth.verifyAuthenticationResponse(
  idToken, // DID Auth Response token to be validate
  didResolver, // DID resolver to be used to obtain public key that validates the token
  audience, // audience specified should match audience within idToken
  requestPayload.nonce // RP stored token
);
console.log(response); // signatureValidation result and verified payload
/*
{
  signatureValidation: true,
  signer: {
    id: 'did:ebsi:AaEkn73secFMUTSg4vTLkhX79kJE8oaAK748ToS8Ys9e#keys-1',
    type: 'Secp256k1VerificationKey2018',
    controller: 'did:ebsi:AaEkn73secFMUTSg4vTLkhX79kJE8oaAK748ToS8Ys9e',
    publicKeyHex: '044490262f40c4f6e9dd16f4d365a44320b48f7c6f55ee87b4a3484b2231df381ed8deb985954e323fd02165e5c2be2e159b2b968d053406eeba2cd4dacbf54c5a'
  },
  payload: {
    did: 'did:ebsi:AaEkn73secFMUTSg4vTLkhX79kJE8oaAK748ToS8Ys9e',
    iat: 1618928334,
    exp: 1618928634,
    iss: 'https://self-issued.me',
    sub: 'og9XbdC0JgtydhaR_SHMKMSvOAV5lRMfo2N8fnKVZRk',
    aud: 'http://localhost:8080/demo/spanish-university',
    nonce: 'BDuATmO9cHP-GcerBzR7kULmgaGaZYXAuKIK8CKCr7o',
    sub_jwk: {
      kid: 'did:ebsi:AaEkn73secFMUTSg4vTLkhX79kJE8oaAK748ToS8Ys9e#key-1',
      kty: 'EC',
      crv: 'secp256k1',
      x: 'c6f81999b3e89f6b6e58e7637ab7c17594bf06e371e20083ee513113f74ca8bb',
      y: 'cbc7af2b19c67cf64725fe4d054820d995a27cd6a23aaebdb120aefbb5957e92'
    }
  }
}
*/

• Response object contains a JSON struct with signatureValidation set to true and the verified payload:

{
  "signatureValidation": true,
  "payload": {
    "iss": "https://self-issued.me",
    "sub": "QS+5mH5GqVxuah94+D9wV97mMKZ6iMzW1op4B4s02Jk=", // Thumbprint of the sub_jwk
    "aud": "redirect-uri", // MUST be client_id from the Request Object
    "exp": 1569937756, // Unix Timestamp; Date and time when the ID Token expires.
    "iat": 1569934156, // Unix Timestamp; Date and time when the Token was issued.
    "nonce": "6a6b57a9d4e1a130b0edbe1ec4ae8823",
    "claims": { ...
    }
  }
}

Usage

Prerequisites

It is assumed that either the user (NP/LE) and the RP have an EBSI-DID and can use their private keys to sign a given payload.

For instance:

// User DID
const userDid = "did:ebsi:0xcAe6EFa4461262842BB58188579Ef2602c7A44fC";
// Relying Party DID
const enterpriseDid = "did:ebsi:0xDe07DBEe84cCB1F75A09e96b1f995560b7Cdf5aa";

Library Test

To run e2e you need to set these two environment variables either in a .env or passing as a parameter to yarn test:e2e.

You can use the .env.example from the repo and renamed it to .env.

# unit tests
$ yarn test:unit

# e2e tests
$ yarn test:e2e

# all tests
$ yarn test

Licensing

Copyright (c) 2019 European Commission
Licensed under the EUPL, Version 1.2 or - as soon they will be approved by the European Commission - subsequent versions of the EUPL (the "Licence"); You may not use this work except in compliance with the Licence. You may obtain a copy of the Licence at:

• https://joinup.ec.europa.eu/page/eupl-text-11-12

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licence for the specific language governing permissions and limitations under the Licence.