Minka Ledger Docs
How To Guides

How to authenticate with JWT

DateResponsibleChanges
May 8, 2023@Luis FidelisInitial version

Ledger SDK allows users to authenticate to ledger by sending tokens.

The JWT options object (JwtConfig) has the following definition

type JwtConfig = {
  /**
   * Represents a client identifier.
   *
   */
  iss: string
 
  /**
   * Represents a user identifier of the token sender.
   *
   */
  sub: string
 
  /**
   * Represents a recipient for which a token is intended, ledger public key or handle
   *
   * */
  aud: string
 
  /**
   * Time after which a token expires, seconds since epoch.
   *
   */
  exp: number
 
  /**
   * Unique id of the token, can be used to prevent replay attacks
   *
   */
  jti?: string
 
  /**
   * Defines the request hash claim (hsh) must
   * be created and sent.
   *
   * Set as "true" if this value is not
   * given.
   */
  createHsh?: boolean
 
  /**
   * ED25519 Key pair for signing token
   *
   */
  keyPair: LedgerKeyPair
 
  /**
   * Token verification key identifier.
   * Accepts a public key or a ledger signer handle.
   */
  kid?: LedgerHandle | LedgerKeyPair['public']
}

JWT configuration can be set and mixed at three different levels - SDK, client and request.

SDK - Securing SDK instance

SDK can be secured when initializing a new object by using the property secure of SDK constructor options.

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
    format: 'ed25519-raw',
    public: '<your ledger public key>'
  },
  secure: {
    aud: '<token audience>',
    iss: '<token issuer>',
    keyPair: {
      public: '<signature public key>',
      format: '<signature key format>',
      secret: '<signature secret key>'
    },
    sub: '<token sub>',
    exp: 3600 // (1 hour)
    createHsh: true,
    kid: '<token verification key identifier>',
  }
})

This can also be set dynamically after creating a new instance with the method setAuthParams

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
    format: 'ed25519-raw',
    public: '<your ledger public key>'
  }
})
 
sdk.setAuthParams({
  aud: '<token audience>',
  iss: '<token issuer>',
  keyPair: {
	  public: '<signature public key>',
    format: '<signature key format>',
    secret: '<signature secret key>'
  },
  sub: '<token sub>',
  exp: 3600 // (1 hour)
  createHsh: true,
  kid: '<token verification key identifier>',
})

Client - Securing SDK Client

A client can be dynamically secured with the method setAuthParams

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
    format: 'ed25519-raw',
    public: '<your ledger public key>'
  }
})
 
// Securing wallet client
sdk.wallet.setAuthParams({
  aud: '<token audience>',
  iss: '<token issuer>',
  keyPair: {
    public: '<signature public key>',
    format: '<signature key format>',
    secret: '<signature secret key>'
  },
  sub: '<token sub>',
  exp: 3600 // (1 hour)
  createHsh: true,
  kid: '<token verification key identifier>',
})

Request - Securing a API call

A request can be dynamically secured with the method setAuthParams

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
		format: 'ed25519-raw',
		public: '<your ledger public key>'
	}
})
	
// Securing a search for a wallet 
const { wallet } = await sdk.wallet.read('wallet-handle', {
aud: '<token audience>',
  iss: '<token issuer>',
  keyPair: {
    public: '<signature public key>',
    format: '<signature key format>',
    secret: '<signature secret key>'
  },
  sub: '<token sub>',
  exp: 3600 // (1 hour)
  createHsh: true,
  kid: '<token verification key identifier>',
})

See About Authentication for more details.

On this page