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.

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

Note: This version 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, accesses an Institution web site, i.e. the RP, and clicks on a Login button.
• The RP creates an Open ID URI Request calling RP.createAuthenticationRequest with the following 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:zcPNLbvojYtj7R3B6pJXaFy" // RP did
  kid: "https://api.test.intebsi.xyz/did-registry/v2/identifiers/did:ebsi:zcPNLbvojYtj7R3B6pJXaFy#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 RP.createAuthenticationRequest(didAuthRequestCall);

• The 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&nonce=_fRDy4lli3gTctXx9evaLJowCZkb2xQcrqnlcNrruKk&request=eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QiLCJraWQiOiJodHRwczovL2FwaS50ZXN0LmludGVic2kueHl6L2RpZC1yZWdpc3RyeS92Mi9pZGVudGlmaWVycy9kaWQ6ZWJzaTpCZEZuZU5wbmlXM0RFNjM5eVk2c0VnYTlHaHdkWjNqU2RmSjFFeVVSTVB4NSNrZXlzLTEifQ.eyJpYXQiOjE2MTg5MDQ0MDEsImV4cCI6MTYxODkwNDcwMSwiaXNzIjoiZGlkOmVic2k6QmRGbmVOcG5pVzNERTYzOXlZNnNFZ2E5R2h3ZFozalNkZkoxRXlVUk1QeDUiLCJzY29wZSI6Im9wZW5pZCBkaWRfYXV0aG4iLCJyZXNwb25zZV90eXBlIjoiaWRfdG9rZW4iLCJjbGllbnRfaWQiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvZGVtby9zcGFuaXNoLXVuaXZlcnNpdHkiLCJzdGF0ZSI6IjdiMjQzMzFmNzNmZDY1YTM3YTBlYTkxNSIsIm5vbmNlIjoiX2ZSRHk0bGxpM2dUY3RYeDlldmFMSm93Q1prYjJ4UWNycW5sY05ycnVLayJ9.h2nlz3AeflzTkh_E2oIvjR_h_0OdB1DDW1maB9Zt3bcfzjYe0Yynl8BJbMB206GySJeZ4d53TuBm8kwSJ2HurA

Note: The RP needs to store the nonce found inside the Request token, so it can be used during the response validation process.

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

2. verifyAuthenticationRequest (NP/LE)

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

const agent = new Agent({
  privateKey:
    "0x431ee55d0ce21e5585c0d138a17e09a334ab30e5645f969ef7385562b6fc5b83",
  didRegistry: "https://api.test.intebsi.xyz/did-registry/v2/identifiers",
});

// Verify DID-Auth request
const params = new URLSearchParams(didAuthUri);
const didAuthRequestJwt = params.get("request") || "";
const requestPayload: DidAuthRequestPayload =
  await agent.verifyAuthenticationRequest(didAuthRequestJwt);
console.log(requestPayload); // verified didAuthRequestJwt payload
/*
{
      iat: 1618912769,
      exp: 1618913069,
      iss: 'did:ebsi:zcPNLbvojYtj7R3B6pJXaFy',
      scope: 'openid did_authn',
      response_type: 'id_token',
      client_id: 'http://localhost:8080/demo/spanish-university',
      nonce: 'sSvVr4kc-Bh76Z4kA5hJ7M9FnoIjxHoZ6GMiQklykGA'
    }
*/

3. createAuthenticationResponse (NP/LE)

• After a successful validation, the user creates an EBSI SIOP Auth Response JWT token calling agent.createAuthenticationResponse.

const agent = new Agent({
  privateKey:
    "0x431ee55d0ce21e5585c0d138a17e09a334ab30e5645f969ef7385562b6fc5b83",
  didRegistry: "https://api.test.intebsi.xyz/did-registry/v2/identifiers",
});

// Create a DID-Auth RESPONSE
const didAuthResponseCall: DidAuthResponseCall = {
  did: "did:ebsi:zsSgDXeYPhZ3AuKhTFneDf1", // User DID
  nonce: "aEfTn8Y8-AseN87GbJkJ7M9FnoIjxHoZ6GMiQkltH80", // random nonce defined by the user
  redirectUri, // parsed URI from the DID Auth Request payload
};
const didAuthResponseJwt = await agent.createAuthenticationResponse(
  didAuthResponseCall
);

• The 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)

• The RP verifies the DID Auth Response token calling RP.verifyAuthenticationResponse with the stored nonce:

const response = await RP.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:zub5ZZUfHLLptCduwEy8xRj#keys-1',
    type: 'Secp256k1VerificationKey2018',
    controller: 'did:ebsi:zub5ZZUfHLLptCduwEy8xRj',
    publicKeyHex: '044490262f40c4f6e9dd16f4d365a44320b48f7c6f55ee87b4a3484b2231df381ed8deb985954e323fd02165e5c2be2e159b2b968d053406eeba2cd4dacbf54c5a'
  },
  payload: {
    did: 'did:ebsi:zub5ZZUfHLLptCduwEy8xRj',
    iat: 1618928334,
    exp: 1618928634,
    iss: 'https://self-issued.me/v2',
    sub: 'og9XbdC0JgtydhaR_SHMKMSvOAV5lRMfo2N8fnKVZRk',
    aud: 'http://localhost:8080/demo/spanish-university',
    nonce: 'BDuATmO9cHP-GcerBzR7kULmgaGaZYXAuKIK8CKCr7o',
    sub_jwk: {
      kid: 'did:ebsi:zub5ZZUfHLLptCduwEy8xRj#key-1',
      kty: 'EC',
      crv: 'secp256k1',
      x: 'c6f81999b3e89f6b6e58e7637ab7c17594bf06e371e20083ee513113f74ca8bb',
      y: 'cbc7af2b19c67cf64725fe4d054820d995a27cd6a23aaebdb120aefbb5957e92'
    }
  }
}
*/

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

{
  "signatureValidation": true,
  "payload": {
    "iss": "https://self-issued.me/v2",
    "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": { ...
    }
  }
}

5. createAccessToken (RP)

The RP creates an access token. The access token is encrypted using the AKE Protocol.

const response = await RP.verifyAuthenticationResponse(...params);

const session = new Session({
  privateKey:
    "0x96543caf05b1aa403e4b67783b9b16d290a8a3a3afdc3bfb04079afbfb48ce6c",
  appName: "authorisation-api",
  kid: "https://api.test.intebsi.xyz/did-registry/v2/identifiers/did:ebsi:zcPNLbvojYtj7R3B6pJXaFy#keys-1",
  did: "did:ebsi:zcPNLbvojYtj7R3B6pJXaFy",
  redirectUri: "http://localhost:8080/authorisation/v2/siop-sessions",
});
const result = await session.createAccessToken(response);
console.log(result);

/*
  {
      ake1_enc_payload: '544d78f20db88c6747577e24e6654d7e02acc5fc4e92aba33df1d6490333a905693bab24380f110878cc9234497aea1196f090be09a953b3841d874f859b7a159a59334b0ca1ea2edf40057f1e1258f9b071a19a4fc6bc82ff91d788ce30186e20998bda8b37b0072ff200fbc939f612901d7b029209cfc6e5662224fa90099d18b5ff74ec7f2e95e612b433543c89feb59577052c2bff5127bbda0ae158a6bea7c822738aaf8462886444a0eafa0e8e4991f9304d0fa80107835818e1cd42ba1041298dda4db2d8e8f01d73e30257f0fa4879a9b96595054eb6ac8407365c8b08512a0e1e4b31c106022702bcd259d8e05379632d9d0ddd1388fc79cc206e69e017adadc4fa46c3a08b323c8522c33c8f4fe379ac228946bf427e9ff70eb3a1128649680874188b25bcc7ce62a26f574a72a6e4c252c72543f9bff6714009ea7df7d3173509efd186ea15abc8b39803628b778b944e03871ffc0a2799b947f2c894877b461551ce04e1bfee013125fd9b70a878ed2563d2b68fe2b2c6c84920e842ee83495eeef15d6935a600ba9969a09e2657e327ce47a994960b9e23f24d938182cae570eb111121e4b3df15f7be0624b7373392789ab84581ef1d46bb9daaa083a9eb3312f2b93e5cc18dee3071732e8022ef32b7827456539fff3c321cdc391913610b7b1654dbe926ed3953f9b9f3a78ce19ae646e59e27db55ff47bd30f79a77e432553d465f3179cdee06f27834c313cc53046f56433699e16e384394ec76968a169da8b65c2a33923fab393d20d8a392a9facbb995e9f9ddcbf958183077542049c71528f64f711472f1d3796f1ebee2d633918e54ab106d42a449128b5e7978d6cad90a42f224d47ed69c8679c513d44f624ecc0fc89ba2c9deba1e4ffdd9b3d2f2c64538830564931f43b0fd6c72df855641825cf85faf48a2c86c4fac09530add87f2a03abc7f797dd6ec4cda3b3698e3094053ac3eebca3aa60723dc0b9e8e604420deca93ae0bd5a19027d3628517092c112d0a57986d83d3efec7d304225eb07720865b05a423bd730b2c9794bf75cc65c1b7dc4f8c71ed681577e557ed9b52ca6a7c4ffc8fa11a65deb2225fe1119a1babc2c5a95cce72e3d8359ab4c654ba41eb8b0ac59314b8f41c81043901505a448788147f29dcfc956367a150c28d4bb207f7b3187b6d94b0a2dc848085f1cd51c99b8db0bf790d421',
      ake1_sig_payload: {
        iat: 1619454427,
        exp: 1619455327,
        ake1_nonce: 'ERX46g_sVz6gi1Fd2vmsMGAvsntCcNQvxKEChLbqYAc',
        ake1_enc_payload: '544d78f20db88c6747577e24e6654d7e02acc5fc4e92aba33df1d6490333a905693bab24380f110878cc9234497aea1196f090be09a953b3841d874f859b7a159a59334b0ca1ea2edf40057f1e1258f9b071a19a4fc6bc82ff91d788ce30186e20998bda8b37b0072ff200fbc939f612901d7b029209cfc6e5662224fa90099d18b5ff74ec7f2e95e612b433543c89feb59577052c2bff5127bbda0ae158a6bea7c822738aaf8462886444a0eafa0e8e4991f9304d0fa80107835818e1cd42ba1041298dda4db2d8e8f01d73e30257f0fa4879a9b96595054eb6ac8407365c8b08512a0e1e4b31c106022702bcd259d8e05379632d9d0ddd1388fc79cc206e69e017adadc4fa46c3a08b323c8522c33c8f4fe379ac228946bf427e9ff70eb3a1128649680874188b25bcc7ce62a26f574a72a6e4c252c72543f9bff6714009ea7df7d3173509efd186ea15abc8b39803628b778b944e03871ffc0a2799b947f2c894877b461551ce04e1bfee013125fd9b70a878ed2563d2b68fe2b2c6c84920e842ee83495eeef15d6935a600ba9969a09e2657e327ce47a994960b9e23f24d938182cae570eb111121e4b3df15f7be0624b7373392789ab84581ef1d46bb9daaa083a9eb3312f2b93e5cc18dee3071732e8022ef32b7827456539fff3c321cdc391913610b7b1654dbe926ed3953f9b9f3a78ce19ae646e59e27db55ff47bd30f79a77e432553d465f3179cdee06f27834c313cc53046f56433699e16e384394ec76968a169da8b65c2a33923fab393d20d8a392a9facbb995e9f9ddcbf958183077542049c71528f64f711472f1d3796f1ebee2d633918e54ab106d42a449128b5e7978d6cad90a42f224d47ed69c8679c513d44f624ecc0fc89ba2c9deba1e4ffdd9b3d2f2c64538830564931f43b0fd6c72df855641825cf85faf48a2c86c4fac09530add87f2a03abc7f797dd6ec4cda3b3698e3094053ac3eebca3aa60723dc0b9e8e604420deca93ae0bd5a19027d3628517092c112d0a57986d83d3efec7d304225eb07720865b05a423bd730b2c9794bf75cc65c1b7dc4f8c71ed681577e557ed9b52ca6a7c4ffc8fa11a65deb2225fe1119a1babc2c5a95cce72e3d8359ab4c654ba41eb8b0ac59314b8f41c81043901505a448788147f29dcfc956367a150c28d4bb207f7b3187b6d94b0a2dc848085f1cd51c99b8db0bf790d421',
        did: 'did:ebsi:zub5ZZUfHLLptCduwEy8xRj',
        iss: 'did:ebsi:zcPNLbvojYtj7R3B6pJXaFy'
      },
      ake1_jws_detached: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraWQiOiJodHRwczovL2FwaS50ZXN0LmludGVic2kueHl6L2RpZC1yZWdpc3RyeS92Mi9pZGVudGlmaWVycy9kaWQ6ZWJzaTpCZEZuZU5wbmlXM0RFNjM5eVk2c0VnYTlHaHdkWjNqU2RmSjFFeVVSTVB4NSNrZXlzLTEifQ..fmniiLuGsV5AGhQDNqR9dOvoLFIN-Xz5MjUMm7bcByp2JE0Z39W_jNf-0BASyONgNe10T99RYEG-9GI3yLzb5A',
      did: 'did:ebsi:zcPNLbvojYtj7R3B6pJXaFy'
    }
 */

6. Agent - verifyAuthenticationResponse (User)

The user decrypts the AKE response and verifies the access token:

const agent = new Agent({
  privateKey:
    "0x431ee55d0ce21e5585c0d138a17e09a334ab30e5645f969ef7385562b6fc5b83",
  didRegistry: "https://api.test.intebsi.xyz/did-registry/v2/identifiers",
});
const accessToken = await agent.verifyAuthenticationResponse(result, nonce);
console.log(accessToken);

/*
  eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraWQiOiJodHRwczovL2FwaS50ZXN0LmludGVic2kueHl6L2RpZC1yZWdpc3RyeS92Mi9pZGVudGlmaWVycy9kaWQ6ZWJzaTpCZEZuZU5wbmlXM0RFNjM5eVk2c0VnYTlHaHdkWjNqU2RmSjFFeVVSTVB4NSNrZXlzLTEifQ.eyJpYXQiOjE2MTk0NTQ0MjcsImV4cCI6MTYxOTQ1NTMyNywic3ViIjoiZGlkOmVic2k6QWFFa243M3NlY0ZNVVRTZzR2VExraFg3OWtKRThvYUFLNzQ4VG9TOFlzOWUiLCJhdWQiOiJlYnNpLWNvcmUtc2VydmljZXMiLCJub25jZSI6IjYyN2U2NjU4LTI1NWMtNGJhMi04YjgzLWZkMTRjODNhMzUxNiIsImxvZ2luX2hpbnQiOiJkaWRfc2lvcCIsImlzcyI6ImRpZDplYnNpOkJkRm5lTnBuaVczREU2Mzl5WTZzRWdhOUdod2RaM2pTZGZKMUV5VVJNUHg1In0.4BCLxAHbnphvEcgg5mZANI29mK_uOzR169XRw6VMRgFZV6ZkjNjeM-ZX6XWBPuEO7IIR7_9xIB90viPwtuK7qw
 */

7. verifyAccessToken (RP)

Client uses the access token to access an API, and the API verifies the access token

const payloadAccessToken = new Session({
  didRegistry: "https://api.test.intebsi.xyz/did-registry/v2/identifiers",
}).verifyAccessToken(accessToken, "did:ebsi:zcPNLbvojYtj7R3B6pJXaFy");

/*
{
  iat: 1619455732,
  exp: 1619456632,
  sub: 'did:ebsi:zub5ZZUfHLLptCduwEy8xRj',
  aud: 'ebsi-core-services',
  nonce: 'a437f30d-ec82-47bd-9082-bbd756dc4cf6',
  login_hint: 'did_siop',
  iss: 'did:ebsi:zcPNLbvojYtj7R3B6pJXaFy'
}
 */

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:zsSgDXeYPhZ3AuKhTFneDf1";
// Relying Party DID
const enterpriseDid = "did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ";

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.