Skip to content

Backplane Auth Manager

The Backplane API uses OAuth 2.0 authentication flow, combined with OpenID Connect (OIDC), providing a simple identity layer on top. The following figure illustrates an authentication flow example:

new authentication flow example

There is a description of each connection considered during the authentication flow described before:

  1. Secured endpoint query: Clients are expected to include the access_token and id_token headers when requesting a Backplane authenticated endpoint.
  2. Retrieve JWKS: The OIDC uses token asynchronous validation, so the Backplane just needs to retrieve the JWKS in order to validate each token offline using EdDSA signature algorithm
  3. Validate tokens: The Backplane internally validates the tokens signature and verifies that the user has the required claims to access the endpoint
  4. Query: The query is redirected to the subsystem, together with the id_token header, containing a JWT Token that describes the requester.

Current deployment is using OIDC instance, supporting OIDC authentication. In some scenarios, it may be required to change the identity provider, so a new backplane image has to be build.

Obtain access_token and id_token

The Backplane integrates the service OIDC Provider, it includes the required endpoints to perform an OAuth2 Authorization code flow.

For testing purposes, we are also including a login authentication endpoint to automatically generate those credentials

GET /auth/openid/login

Swagger references here.

In order to call the previous endpoint you will need to have a wallet installed and configured

Create a test credential with Desktop wallet

- Install and configure a Desktop wallet

Please refer to desktop wallet documentation

- Request a VC for our identity

The following request is requesting a consumer credential, for more information please refer to api specification:


How to enable Authentication/Authorization in subsystems endpoints

While subsystems do not need to worry about authentication, they need to indicate in their OAS specification, which of their endpoints are protected and which are not. To mark an endpoint as protected, it must include:

  • JWT: To tell the Backplane to use JWT authentication and which scopes user must have to access an endpoint, they must be written inside the security section of the specification (OAS). Note that the scopes array can be empty, to allow any authenticated user to access.
    "security": [
          "jwt": ["user", "consumer"]
    If the endpoint needs the information about the user making the requests it must also include:
  • JWT Security Schema: Add the following security schema to the subsystem OpenApi Specification (OAS):
     "securitySchemes": {
      "jwt": {
        "type": "apiKey",
        "in": "header",
        "name": "id_token"
    With the above stated OAS modifications, the Service Integrator Engine will add the required authentication mechanism to each endpoint, automatically, during Backplane deployment pipeline.


We are providing an authenticated OAS as an example, please refer to the greeter service OAS file, specially the /hello/consumer endpoint

How to test authorization at Backplane level

In order to test endpoints authorization at Backplane level, the following steps need to be performed:

Query secured endpoint

- Obtain an Access Token and Id token

Refer to Obtain access_token and id_token section

- Perform the query


Headers: ['id_token': , 'access_token': ]

Id_token format

Id_token follows the JWT standard, signed with EdDSA, meaning that we need a Public Key to validate the Signature. This key can be found in the OIDC provider, under the /jwks endpoint. Matching with the kid present in the JWT header

  "alg": "EdDSA",
  "typ": "JWT",
  "kid": "5F-hg3nVZT_9SZyF2hqAe5NQIBF9_M900ULvIx045vs"


  "sub": "did:ethr:i3m:0x02c1740be3975069c8faf2ef1f4f550a23cb9283f9118e665092ec6bee287b47da",
  "verified_claims": {
    "trusted": [],
    "untrusted": [
  "at_hash": "_Q4tf0VMgwwiIf45DR0CgoZRO2Va9GKU1PP1d-3WonQ",
  "aud": "IYunmpgrLShA__Pg4YmpM",
  "exp": 1649333684,
  "iat": 1649330084,
  "iss": ""

VC JWT format


  "alg": "ES256K",
  "typ": "JWT"


  "vc": {
    "credentialSubject": {
      "consumer": true
    "@context": [
    "type": [
  "credentialStatus": {
    "id": "",
    "type": "0x43978149D2ae5805a590DB162412aaDfb3f2336e"
  "sub": "did:ethr:i3m:0x02c1740be3975069c8faf2ef1f4f550a23cb9283f9118e665092ec6bee287b47da",
  "nbf": 1649330026,
  "iss": "did:ethr:i3m:0xda4481982a024b5ae7e57756ad649d79ddcafb09"

I3-Market Developers - Notes

The backplane expects to get the following authentication headers when querying secured endpoints:

  • id_token
  • access_token

Subsystems can expect to obtain the user information through the id_token header in JWT format.

Change the backplane OIDC Provider

This section is partially deprecated, as now the Backplane isn't directly performing OIDC authentication. At the moment only the OIDC_PROVIDER_WELL_KNOWN_URL env variable is mandatory.

  • Clone Backplane repository
    git clone
  • Create a .env file with the following variables, using the new OIDC provider information:

    OIDC_CLIENT_ID=<Backplane's OIDC client Id>
    OIDC_CLIENT_SECRET=<Backplane's OIDC client >
    OIDC_PROVIDER_WELL_KNOWN_URL=<OIDC Provider well-known url>
    PUBLIC_URI=<Backplane's public uri>
    PORT=<Backplane's public port>(3000)
    HOST=<Backplane's listening host>(
    # Only set if you have created the `certificates` folder in a different location (defaults to ./certificates)
    CERTS_PATH=<Path to the certificates directory>
    # You probably won't have to set that one never
    SECRETS_PATH=<Path to the secrets file>
    # Optional - Disable de smart subsystem's server election on startup
    # Optional - Apply a filter to the servers defined in the OAS definiton (comma separated strings), ignore if empty

  • Integrate required OAS (refer to the Integration section)

  • Build the docker image
    docker build
    For additional information check the Backplane repository README

Last update: 2022-12-22
Created: 2022-04-06
Back to top