How To Guides
How to authenticate with JWT
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.