Signing requests (User Action Signature)

All mutating requests need to be signed with a user or service account credential.

“User Action Signature” is required to unlock sensitive actions within the system and to audit changes at a later time. A cryptographically-signed audit-trail is available using the Audit Logs API for you to review who requested and validated every single action taken on Dfns.

Check out the API Reference to get details about how to implement the different signing flows.

Overall process

Signing is a four-steps process:

1. Get a challenge from the Dfns system.

   A signing challenge is returned from a call to: Get a User Action Challenge

   You will receive an object with the following properties (additional properties exist for signing with WebAuthn):

   field	description
   challenge	A string that will be signed with your private key
   challengeIdentifier	A JWT that identifies the signing session
   allowCredentials	The list of private key credentials that are enabled for the user

2. Sign the challenge

   This step differs depending on the type of credential you are using:

   • Human users often use passkeys, with which the signing process is all managed by their OS and browser in the frontend (website, mobile app, etc).
   • Machine users use asymetric keys that you need to use in the backend with a crypto library.

   You will need to format the challenge into a Client Data object, convert the object into a JSON string and sign the string using one of the credentials listed in allowCredentials.

   See the example flow below.

3. Return the signed challenge to the Dfns system

   Call the endpoint: Create the User Action Signature

   You will need to provide the base64url-encoded signed challenge from the previous step, as well as the (base64url-encoded) client data and the id of the credential that was used to sign.

   You will receive a token to use in the next step. This token is only valid once.

4. Get back a User Action Signature, and include it with your original API call

   This is when you call the actual endpoint you needed to call all along!

User signing flow using a Fido2 passkey

Example with a Fido2 passkey, where the use signs the challenge in your frontend:

User signing process using Fido2 passkeys

See how to implement this Fido2 signing flow in the API Reference.

You can test this flow with this tutorial.

Backend signing flow using an asymetric key pair

Your backend can use a service account to call the Dfns API, but the service account will also be required to sign its sensitive requests.

When creating a service account, you will have to generate a key pair and register its public key with Dfns.

The private key is used to sign the challenges.

Backend signing process using asymetric keys

See how to implement this Asymetric Keys signing flow in the API Reference.

Example of what the backend needs to do to sign the challenge. In the flow above this is represented by the “KMS”, as a recommend secure storage for your credentials.

const signChallenge = async (challenge: UserActionSignatureChallenge) : Promise<SignedChallenge> => {

  // The data being signed includes information that is important for validating the request originated from a valid location.
  const clientData: Buffer = Buffer.from(
    JSON.stringify({
      type: 'key.get',
      challenge: challenge.challenge,
      origin: origin,
      crossOrigin: false,
    } as ClientData)
  )

  // Signing can be done locally or by calling an external signer (like AWS KMS).
  const signature = crypto.sign(
    undefined,
    clientData,
    apiKeyPrivateKey
  )

  // Pass back the signature, and the data that was signed so both can be parsed and validated properly.
  return {
    clientData: clientData.toString('base64url'),
    credId: challenge.allowCredentials.key[0].id,
    signature: signature.toString('base64url'),
  }
}