EBSI App JWT Library

Library to create sessions between Apps registered in the Trusted Apps Registry.

Table of Contents

1. Installation
2. Usage
3. Library Test
4. Licensing

Installation

npm install @cef-ebsi/oauth2-auth

or if you use yarn

yarn add @cef-ebsi/oauth2-auth

Usage

In the following example, the app "ebsi-wallet" (Agent) creates a request to access "ebsi-ledger".

const { Agent } = require("@cef-ebsi/oauth2-auth");

// The client "ebsi-wallet" creates a request to access the "ebsi-ledger"
const cliPrivKey =
  "64e4a7a1e2e463e95e2e3413deb7676221544e92b951705142fd9c719ea4af3e";
// The client "ebsi-wallet" provides its TAR kid
const kid =
  "https://api.test.intebsi.xyz/trusted-apps-registry/v2/apps/0xb12...ada5f";
const agent = new Agent(cliPrivKey, { issuer: "ebsi-wallet", kid });
// The client "ebsi-wallet" uses its agent to create a Request
const request = await agent.createRequestPayload("ebsi-ledger", {
  nonce: "123",
}); // Optional: defining nonce or defining any more fields in the payload of the request
console.log(request);
/*
{
  grantType: 'client_credentials',
  clientAssertionType: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
  clientAssertion: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraWQiOiJHNW01TmxiaTdGWlhPTVlHN2ctZ0tCLVVGdkVBSVUyUFkzSFQ3SFZtYkJzIn0.eyJpc3MiOiJlYnNpLXdhbGxldCIsImF1ZCI6ImVic2ktbGVkZ2VyIiwiaWF0IjoxNTkxODkxMDU4LCJleHAiOjE1OTE4OTEwNzN9.rvuAbEAOof5hilA3vdcWg_d81MAGSSMWGlR-kJ15ZqzlZQgbzGCAJHlG1jK3UGh2NP_cFRivfSErT-K_7HrV4g',
  scope: 'openid did_authn'
}
*/

The Agent makes a call to "authorisation-api" (Relying Party) in the endpoint "/sessions" and put this request in the body as Content-Type: application/json.

The Relying Party receives this request and creates a new session using the class "Session":

const { Session } = require("@cef-ebsi/oauth2-auth");
const express = require("express");
const router = express.Router();

const apiPrivKey =
  "9d678b6edef394cd0182cbc76be7fd69021c2d90c8739837737afea3723314e2";

// Optional: set none, one, some or all
const apiName = "authorisation-api"; // Name of the service using Session instance
const tarProvider = "https://api.test.intebsi.xyz/trusted-apps-registry/v2"; // Define custom TAR provider endpoint
const didResolver = "https://api.test.intebsi.xyz/did-registry/v2/identifiers"; // Define a custom resolver for DIDs
const expiration = {
  requestToken: 10,
  accessToken: 800,
}; // Set a different expiration time for the request token and access token (by default 15 and 900 respectively):
const kid =
  "https://api.test.intebsi.xyz/trusted-apps-registry/v2/apps/0xa33...fef6a"; // custom kid that resolves the publickey

const session = new Session(apiPrivKey, {
  appName: apiName,
  tarProvider,
  didResolver,
  expiration,
  kid,
});

router.post("/sessions", async (req, res, next) => {
  try {
    const requestComponent = req.body;
    // The Relying party first verifies the authentication response provided
    const pubKey = await session.verifyAuthenticationResponse(
      requestComponent.clientAssertion,
      {
        tarProvider,
      }
    );
    // If verification succeeded, an access token is created
    const ake1Response = await session.createAccessToken(
      requestComponent,
      pubKey
    );
    res.send(ake1Response);
  } catch (error) {
    next(error);
  }
});

module.exports = router;

The response is a JSON object containing ake1_enc_payload, ake1_sig_payload, ake1_jws_detached, and kid:

{ ake1_enc_payload:
   '9501a7d322d9f08156827866fd74673c029b35d809a9c2e73709483639b7b45876dfe49fc2a70c00ddd4836f8d8e04a09d2f3455620d1f82580468162eff2f04ba1539e454796faad7d29b845a8a7cd855e2ef76cb215d3ca58478be28de0ba88b537d033d55cdd0f62c026e58204b94211f0635c774f1c77349b0233085344aade8db8700d4129ed41b7e70d98385aed615bd1433f3eee069088919f17fa7701c2610770e46cc9f33d8736f0249897c6d4a597f10f63038b335f860dc4a303ea1398575fe462bcab122870fc36f2f5ee5a1919fbc943b063cbb6ad4049d11c4847b9113595118863dfc49f2a962a72bd639005c61824434d48727ee75c796a8cb50b8fe8ef6fe68a04dda2077513193cba862061f325a4cf38eb616f5e75fca24549f22af7ecda457b710c2b2e4db4a4a9299fdd954b8270489890f36dc14f2ccaa1abcb592cb91d629daf4057eafa2a147b86da8d0d518f4b50c8d27daaf5e2fbf9906949e87059a917287d23396b8a1293d9619593cbccfd749c412729349dc6bc24c74a24e18adef1cec65ae79d8683c7f10c2422c713e7ad3bfa6c118793ddf0935d830dde1ce667e12d9c686cc2a752701a86d0ea4953d18c8fe7556bc9af685adf41c2825e81af2ece580ad66b809849a8f7dcd422c2d42864831de0bc0273cd0aeba5f8417bc131aeda6b5c2b8486ab670c71ee0a1e89842572a5080bdeafe20b7767770ffa725c3bd854510df7507c422f404f510fab4a5bef2d94357f6757570ba8360c3207a9aa9dc36725925067292254c7924ee6b5c1f34b40feed108b2dfe7b7ed2afca67c5f4b4908fd42d9bb55d9b0997e2100f423e1dcc5d90573b0709ab3c3260dc748d414aee637b6dd6ccdc1856d787a4a013b633f6ce1bc29c88fbe6b4d703adfda6a59595db322a44fe1ca50de778581e5f7659dbf4e670ed36adcd2578eca84f7c6d3059b0066f7f8534b496bae6d6891a547dcc82dda8f976cf2840ae601216dc22426c472ccfc0b3694ddae46b3daa87e35ba1edb651d89da5a8ad021d86c6967756c5437962fbee9a19385b7d399ac632350ae8db8e30a650339154d2e99f94d3b57cfda7d6446efec8f529e65e790e38d537ec5696fa69a104791db8ce7c82d5fc8eec013afd47c4afd12c4b18206800ff4d57cfa37b2bc136fd136aa8670e5f54663906b130e8292d50cb1a130b9544e995e7622ae0ecb7798d8cbcb9ffb740e50f1f7',
  ake1_sig_payload: {
        iat: 1617877199,
        exp: 1617878099,
        ake1_nonce: '123',
        ake1_enc_payload: '9501a7d322d9f08156827866fd74673c029b35d809a9c2e73709483639b7b45876dfe49fc2a70c00ddd4836f8d8e04a09d2f3455620d1f82580468162eff2f04ba1539e454796faad7d29b845a8a7cd855e2ef76cb215d3ca58478be28de0ba88b537d033d55cdd0f62c026e58204b94211f0635c774f1c77349b0233085344aade8db8700d4129ed41b7e70d98385aed615bd1433f3eee069088919f17fa7701c2610770e46cc9f33d8736f0249897c6d4a597f10f63038b335f860dc4a303ea1398575fe462bcab122870fc36f2f5ee5a1919fbc943b063cbb6ad4049d11c4847b9113595118863dfc49f2a962a72bd639005c61824434d48727ee75c796a8cb50b8fe8ef6fe68a04dda2077513193cba862061f325a4cf38eb616f5e75fca24549f22af7ecda457b710c2b2e4db4a4a9299fdd954b8270489890f36dc14f2ccaa1abcb592cb91d629daf4057eafa2a147b86da8d0d518f4b50c8d27daaf5e2fbf9906949e87059a917287d23396b8a1293d9619593cbccfd749c412729349dc6bc24c74a24e18adef1cec65ae79d8683c7f10c2422c713e7ad3bfa6c118793ddf0935d830dde1ce667e12d9c686cc2a752701a86d0ea4953d18c8fe7556bc9af685adf41c2825e81af2ece580ad66b809849a8f7dcd422c2d42864831de0bc0273cd0aeba5f8417bc131aeda6b5c2b8486ab670c71ee0a1e89842572a5080bdeafe20b7767770ffa725c3bd854510df7507c422f404f510fab4a5bef2d94357f6757570ba8360c3207a9aa9dc36725925067292254c7924ee6b5c1f34b40feed108b2dfe7b7ed2afca67c5f4b4908fd42d9bb55d9b0997e2100f423e1dcc5d90573b0709ab3c3260dc748d414aee637b6dd6ccdc1856d787a4a013b633f6ce1bc29c88fbe6b4d703adfda6a59595db322a44fe1ca50de778581e5f7659dbf4e670ed36adcd2578eca84f7c6d3059b0066f7f8534b496bae6d6891a547dcc82dda8f976cf2840ae601216dc22426c472ccfc0b3694ddae46b3daa87e35ba1edb651d89da5a8ad021d86c6967756c5437962fbee9a19385b7d399ac632350ae8db8e30a650339154d2e99f94d3b57cfda7d6446efec8f529e65e790e38d537ec5696fa69a104791db8ce7c82d5fc8eec013afd47c4afd12c4b18206800ff4d57cfa37b2bc136fd136aa8670e5f54663906b130e8292d50cb1a130b9544e995e7622ae0ecb7798d8cbcb9ffb740e50f1f7',
        kid: 'https://api.test.intebsi.xyz/trusted-apps-registry/v2/apps/0xf0c34a721e1...d7bb5c0b11d108aa52a5de0337',
        iss: 'authorisation-api'
      },
  ake1_jws_detached: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraWQiOiJodHRwczovL2FwaS50ZXN0LmludGVic2kueHl6L3RydXN0ZWQtYXBwcy1yZWdpc3RyeS92Mi9hcHBzLzB4ZjBjMzRhNzIxZTFiYjc2MDZkZTMzYTZlNDRhYjMwNjk4ZTgwNzZkN2JiNWMwYjExZDEwOGFhNTJhNWRlMDMzNyJ9..Wn2SYvSFucbrHO2I1EelnXH4U_UiYGI3D5tDNewzl0sVLEJ_fZMqAm39PfxmJjY7e_DraHtirvZGYjsSUZdmqw',
  kid: 'https://api.test.intebsi.xyz/trusted-apps-registry/v2/apps/0xf0c34a721e1...d7bb5c0b11d108aa52a5de0337'
}

Once the Agent receives this response, it is ready to decrypt it with its private key (set when creating Agent instance) and get the accessToken to consume the ebsi-ledger api services afterwards.

const accessToken = await agentComponent.verifyAuthenticationResponse(
  ake1Response,
  nonce // 123 according to the example set above
);

The Agent can use now this access token to connect to ebsi-ledger requested. This service, ebsi-ledger, will make use of the library as well to verify this access token by means of its instance:

const { Session } = require("@cef-ebsi/oauth2-auth");
const express = require("express");
const router = express.Router();

const apiPrivKey =
  "245b68357e77cb8204ee711019c4c9e00eb9b39e1b06e0a0020e461c16f1e033";
const apiName = "ebsi-ledger";
const tarProvider = "https://api.test.intebsi.xyz/trusted-apps-registry/v2";
const didResolver = "https://api.test.intebsi.xyz/did-registry/v2/identifiers";

const kid =
  "https://api.test.intebsi.xyz/trusted-apps-registry/v2/apps/0x177...d885b";
const session = new Session(apiPrivKey, {
  appName: apiName,
  tarProvider,
  didResolver,
  kid,
});
const payload = await session.verifyAccessToken(accessToken);
// console.log(payload);
/*
{
      iat: 1618209341,
      exp: 1618210241,
      iss: 'authorisation-api',
      sub: 'ebsi-wallet',
      aud: 'ebsi-ledger',
      atHash: 'Du-_vQjvv73vv73vv73vv70l77-9Rnfvv71zG--_vSjvv73vv705Qe-_vXXvv71H77-977-9xKxgCjs',
      nonce: 'yLS/hjgOX/YHCh63TgvYng=='
    }
*/

Reference: https://ec.europa.eu/cefdigital/wiki/pages/viewpage.action?spaceKey=BLOCKCHAININT&title=DID+Authentication+Library

Trusted App Registry

Check if a token has been issued by a Trusted App and verify it:

const { TrustedAppsRegistry } = require("@cef-ebsi/oauth2-auth");
const provider = "https://api.test.intebsi.xyz/trusted-apps-registry/v2";
const tar = new TrustedAppsRegistry(provider);
const pubKey = await tar.verify(token);
// pubKey: public key retrieved from TAR that verified the token

Check if an App is authorized

const { TrustedAppsRegistry } = require("@cef-ebsi/oauth2-auth");
const provider = "https://api.test.intebsi.xyz/trusted-apps-registry/v2";
const tar = new TrustedAppsRegistry(provider);
try {
  await tar.checkAuthorization("ebsi-ledger", "ebsi-wallet");
  console.log("valid authorization");
} catch (error) {
  console.log(error);
}
/*
  true
*/

Utils

Utils contains a set of functions related to generation of private keys and verification of tokens.

Import utils

const { utils } = require("@cef-ebsi/oauth2-auth");

Check if headers follow EBSI standards

utils.checkHeaders(
  {
    alg: "ES256K",
    typ: "JWT",
  },
  { scope: "ebsi profile component" }
);
// true

Check if assertion token payload follows EBSI standards

utils.checkAssertionTokenPayload(requestToken);

Check if access token payload follows EBSI standards

utils.checkAccessTokenPayload(accessToken);

Check headers and payload but not signature

utils.checkHeadersPayload(token);

// force a specific scope and audience
utils.checkHeadersPayload(token, {
  scope: "ebsi profile component",
  audience: "app",
});

Library Test

Create an .env file using .env.example and update the corresponding values.

# unit 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.