@cef-ebsi/oauth2-auth NPM

EBSI App JWT Library

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

Installation
Usage
License

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 "requester-app-xx" (Agent) creates a request to access "ledger-api".

const { Agent } = require("@cef-ebsi/oauth2-auth");
const trustedAppsRegistry =
  "https://api-pilot.ebsi.eu/trusted-apps-registry/v4/apps";

// 1. The agent creates an authentication request
const agent = new Agent({
  privateKey:
    "5d77ca8e567042028075f36d765092b6bcf170cfdb57ee3aff13e36bad599c47",
  name: "requester-app-xx",
  trustedAppsRegistry,
});

const authRequest = await agent.createRequest("ledger-api", {
  nonce: "123",
});
console.log(authRequest);
/*
{
    "grantType": "client_credentials",
    "clientAssertionType": "urn:ietf:params:oauth:client-assertion
                            -type:jwt-bearer",
    "scope": "openid did_authn",
    "clientAssertion": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraW
      QiOiJodHRwOi8vbW9jay50YXIvcmVxdWVzdGVyLWFwcC14eCJ9.eyJpYXQiO
      jE2NDY5ODgyMDYsImV4cCI6MTY0Njk4ODIyMSwianRpIjoiOGExZDMxNTctY
      zYxYS00M2Q3LWJmZjUtN2UyZDYwYTQ0NzY3IiwiYXVkIjoibGVkZ2VyLWFwa
      SIsInN1YiI6InJlcXVlc3Rlci1hcHAteHgiLCJub25jZSI6IjEyMyIsImlzc
      yI6InJlcXVlc3Rlci1hcHAteHgifQ.fESWUtIALmywTMXXcuWOUT5FvOY4zK
      NQplpOmgIlmZQmVNgCuesfFg3tgjgWzOV7U85FPpPv9x_BCK4Un8cvxg"
  }
*/

The Agent makes a call to "authorisation-api" (Relying Party) in the endpoint "/oauth2-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 "RP":

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

const rp = new RP({
  privateKey:
    "7705d9d89ba2612ac4a635b32e30b941ff5942e14d3900b6aec6e15439141e52",
  name: "authorisation-api-xx",
  trustedAppsRegistry,
});

// 2. The RP verifies the authentication request
const resVerification = await verifyJwtTar(authRequest.clientAssertion, {
  trustedAppsRegistry,
});

console.log(resVerification);
/*
{
  "payload": {
    "iat": 1646988206,
    "exp": 1646988221,
    "jti": "8a1d3157-c61a-43d7-bff5-7e2d60a44767",
    "aud": "ledger-api",
    "sub": "requester-app-xx",
    "nonce": "123",
    "iss": "requester-app-xx"
  },
  "protectedHeader": {
    "typ": "JWT",
    "alg": "ES256K",
    "kid": "https://api-pilot.ebsi.eu/trusted-apps-registry/v4/apps/requester-app-xx"
  },
  "publicKeyHex": "0419185fee40ea59d37088a7986e31b4080593339d782d87ab90298a12e2bbec5a8740c1268c50f64ccc437079b4de8565e5af1869e102c24111db1ce88cc9ba9e",
  "publicKey": { Object }
}
*/

// 3. The RP creates an access token
const akeAccessToken = await rp.createAccessToken(authRequest, resVerification);

console.log(akeAccessToken);

/*
{
  "ake1_enc_payload": "fc7bbb2905097c98ac483272df58464e03f542d7c0e400
     ca69321c41ecb3e720ac8a8e5815f2e32ba4d7a953ff8c84d80b30304a63de8c
     f0d6a3dd5cd403c5f09ce579b1ce70d94668d5041669ef15db3d914ab9144394
     e0b7c75aeeff5a2eb42df9161c88405d42483d989201e62d435784c7e8f4a8e0
     a262f1ef37cdc304c405626d919416e0670c6299e38f710fb6ffb7bbee3b6d86
     731cca345eee4e4ea659f875642d647e81b0915af59500be62e17bc94e7393ad
     3c43f12b8627986ca3c3b1c839cd8a0182f86fc6451951fc2d8a1cf36caa1298
     48093eca78963f4771eee6c4464f7b3eba607c4461e08943d85c558535f1ef47
     87fe710b02ea813561e27fc34a8040ef05c9d9ee613ac4cac22551b9982c153d
     a1ad3659d957a6f9f81a654f82627f24129c02c5831e65a85b9235cc9b1140f2
     816320e4c45691344086fefc0d3bdecb9ff216c66ef81668ea4aa6e7e6e0e0d9
     8aef41a8ea46e7f8e97c37b2afebac01be1bf3ccc22f41215c1107e13f51e22b
     1a7923f9abe53ee8b4b765e1198728b2d9953e68968b21a5ec1d47d164b515e5
     7015dd4539c946f57f5f4f6b8d1a60974eda367bc8a99a66691dda1dae60c097
     1479e9675e46afdbd11dbdec6da90056b4f7b08e1a8a5b0ea616bcc1293594f8
     453b458f345a121a18d4dca8e4ec8a61e1aab9e5320425ac71f3d4494ebd78cc
     61113bb40975f64d4dfb67371ab57471c6edb18b38272c8d580e89926363a6e5
     7a8ac9b16734ac179d12a51cd2e27a1cd1ef21fb1c6e73c2b6bc43c556724aa7
     7b0c62def4a137f07a9d24f64b5d5113521211afa4a81ae37cbd2fd264ca29a7
     e47e22474f03080bc9c830115ac66445ddb63f5eb3831a2f1e73881031bb669c
     4d90f74414cb03512d75",
  "ake1_sig_payload": {
    "iat": 1646988206,
    "exp": 1646989106,
    "ake1_nonce": "123",
    "ake1_enc_payload": "fc7bbb2905097c98ac483272df58464e03f542d7c0e4
    00ca69321c41ecb3e720ac8a8e5815f2e32ba4d7a953ff8c84d80b30304a63de8
    cf0d6a3dd5cd403c5f09ce579b1ce70d94668d5041669ef15db3d914ab9144394
    e0b7c75aeeff5a2eb42df9161c88405d42483d989201e62d435784c7e8f4a8e0a
    262f1ef37cdc304c405626d919416e0670c6299e38f710fb6ffb7bbee3b6d8673
    1cca345eee4e4ea659f875642d647e81b0915af59500be62e17bc94e7393ad3c4
    3f12b8627986ca3c3b1c839cd8a0182f86fc6451951fc2d8a1cf36caa12984809
    3eca78963f4771eee6c4464f7b3eba607c4461e08943d85c558535f1ef4787fe7
    10b02ea813561e27fc34a8040ef05c9d9ee613ac4cac22551b9982c153da1ad36
    59d957a6f9f81a654f82627f24129c02c5831e65a85b9235cc9b1140f2816320e
    4c45691344086fefc0d3bdecb9ff216c66ef81668ea4aa6e7e6e0e0d98aef41a8
    ea46e7f8e97c37b2afebac01be1bf3ccc22f41215c1107e13f51e22b1a7923f9a
    be53ee8b4b765e1198728b2d9953e68968b21a5ec1d47d164b515e57015dd4539
    c946f57f5f4f6b8d1a60974eda367bc8a99a66691dda1dae60c0971479e9675e4
    6afdbd11dbdec6da90056b4f7b08e1a8a5b0ea616bcc1293594f8453b458f345a
    121a18d4dca8e4ec8a61e1aab9e5320425ac71f3d4494ebd78cc61113bb40975f
    64d4dfb67371ab57471c6edb18b38272c8d580e89926363a6e57a8ac9b16734ac
    179d12a51cd2e27a1cd1ef21fb1c6e73c2b6bc43c556724aa77b0c62def4a137f
    07a9d24f64b5d5113521211afa4a81ae37cbd2fd264ca29a7e47e22474f03080b
    c9c830115ac66445ddb63f5eb3831a2f1e73881031bb669c4d90f74414cb03512
    d75",
    "kid": "https://api-pilot.ebsi.eu/trusted-apps-registry/v4/apps/requester-app-xx",
    "iss": "authorisation-api-xx"
  },
  "ake1_jws_detached": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraWQiO
    iJodHRwOi8vbW9jay50YXIvYXV0aG9yaXNhdGlvbi1hcGkteHgifQ..EQntDHAzJ4
    SE5D0H3WYEqvLFZejcxoWuJqbmENV9QpIYaYG6-Gal2Qyo9HJnQ5z27Z00yS_yDJP
    7xGShccqdVw",
  "kid": "https://api-pilot.ebsi.eu/trusted-apps-registry/v4/apps/authorisation-api-xx"
}
*/

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 ledger-api services afterwards.

const accessToken = await agent.verifyAkeResponse(akeAccessToken, {
  nonce: "123",
});

console.log(accessToken);

/*
   "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksiLCJraWQiOiJodHRwOi8vb
    W9jay50YXIvYXV0aG9yaXNhdGlvbi1hcGkteHgifQ.eyJpYXQiOjE2NDY
    5ODgyMDYsImV4cCI6MTY0Njk4OTEwNiwic3ViIjoicmVxdWVzdGVyLWFw
    cC14eCIsImF1ZCI6ImxlZGdlci1hcGkiLCJhdEhhc2giOiJkSFg5bWppZ
    zlBUTFXS0dEWFM3X2hvbTZwV3B4UGJQWnZfQmVoQk9IQ0dVIiwibm9uY2
    UiOiI4MDM4M2E1NS04MDIxLTQ5NzUtOWFkNS1hYzQ3NGQ3YTk4ZjMiLCJ
    pc3MiOiJhdXRob3Jpc2F0aW9uLWFwaS14eCJ9.GbIE9GQAUBEroyp_zeL
    zgLu_xbIxlBViFoTiOWWmXEiyupOKaW6D8bR77dXX6PJXZwvW7_21CDOU
    LW44Q0swxQ"
*/

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

const verification = await verifyJwtTar(accessToken, {
  trustedAppsRegistry,
  op: "authorisation-api",
});

console.log(verification);

/*
{
  "payload": {
    "iat": 1646988206,
    "exp": 1646989106,
    "sub": "requester-app-xx",
    "aud": "ledger-api",
    "atHash": "dHX9mjig9AQ1WKGDXS7_hom6pWpxPbPZv_BehBOHCGU",
    "nonce": "80383a55-8021-4975-9ad5-ac474d7a98f3",
    "iss": "authorisation-api-xx"
  },
  "protectedHeader": {
    "typ": "JWT",
    "alg": "ES256K",
    "kid": "https://api-pilot.ebsi.eu/trusted-apps-registry/v4/apps/authorisation-api-xx"
  },
  "publicKeyHex": "043724f2bcc9515f0d1cefccea203d065bf05ecbd8b8c7cba115dec28e17d4ea5a57bdd35a149d8ed0d2fdb3d7980c6780666d0ccb5d0195f9345982ad74430414",
  "publicKey": {}
}
*/

Reference: https://ec.europa.eu/digital-building-blocks/wikis/pages/viewpage.action?pageId=367298094

License

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.