Strong Customer Authentication

Overview

This guide explains how to implement Strong Customer Authentication in your Solaris Digital Assets (SDA) solution using the platform's ApprovalMethod and ApprovalGroup resources.

ApprovalMethods

An ApprovalMethod defines the multifactor authentication (MFA) mechanism that an Entity uses to approve Transactions. You must create an ApprovalMethod for each Entity before they can make Transactions.

When you register an ApprovalMethod, it will have the initial state of PENDING. Either the customer or Solaris (depending on the ApprovalMethod type) must activate the ApprovalMethod (transitioning it to the state of ACTIVATED) before the customer can begin making Transactions.

note
  • Currently, you can only register one ApprovalMethod per Entity.
  • If you wish to use the DSA_ED25519 ApprovalMethod, then please contact your Onboarding Manager beforehand. This type of ApprovalMethod has different security assumptions than the other types and requires manual setup.

The SDA platform offers multiple types of ApprovalMethods:

  • AUTHY_PUSH: Uses a push notification from the Authy app. All Entity types can use this ApprovalMethod type.
  • SMS: Uses an SMS message to the customer's registered mobile number. All Entity types can use this ApprovalMethod type.
  • DSA_ED25519: Uses a digital-signature-based MFA mechanism. This ApprovalMethod is designed for automated systems or custom integrations. Only Business and Partner Entities can use this ApprovalMethod type.
  • GROUP: Represents a group of approvers with a quorum. Only Business Entities can use this ApprovalMethod type.

    • Note: Only Solaris can create GROUP ApprovalMethods.

How to set up ApprovalMethods

Each ApprovalMethod type has its own setup and activation process:

AUTHY_PUSH

warning

If your solution uses Authy for approving transactions, then your customers must download the Authy app before they can make Transactions. They must also register for Authy with the same mobile number that they provided you during onboarding.

Before you can activate an AUTHY_PUSH ApprovalMethod, two conditions must be met:

  1. The customer must have downloaded the Authy app and registered for Authy.
  2. The customer must have successfully completed the KYC process.

When you register an AUTHY_PUSH ApprovalMethod, the customer will receive a push notification in their Authy app. Once they confirm the push notification, the ApprovalMethod will be activated.

SMS

ApprovalMethods of type SMS will automatically activate as long as the customer has completed the KYC process.

DSA_ED25519

To use the DSA_ED25519 ApprovalMethod, you must generate and store an approval key (an Ed25519 key pair) in your system.

When you register an ApprovalMethod of type DSA_ED25519, submit the public part of the approval key as the value of the pub_key property in your API request.

warning

The approval key must be different from your API key.

The approval process for Transactions using DSA_ED25519 is as follows:

  1. The SDA platform creates a challenge in a deterministic way based on the Transaction attributes.
  2. The Transaction initiator signs the challenge using the private portion of the approval key.
  3. Send the signature to Solaris using the POST Approve an ApprovalRequest of type DSA_ED25519 method.
  4. The platform verifies the response using the public portion of the approval key and then marks the transaction as approved.

Solaris will activate this ApprovalMethod using a manual process. Solaris may contact you to confirm the validity of the provided public key.

GROUP activation

ApprovalMethods of type GROUP are connected to ApprovalGroups. An ApprovalGroup is a group of individuals who must reach quorum (i.e., a minimum threshold of individuals approving) before a Transaction can be approved.

Solaris will configure the ApprovalGroup and its members. Each member will be an Entity of type REPRESENTATIVE_PERSON who has successfully completed the KYC process.

ApprovalMethod API endpoints

Use the following API endpoints to create and query information about ApprovalMethods:

POST Create an ApprovalMethod

This endpoint registers a new ApprovalMethod for the Entity specified in the request URL.

Request URL:

POST /entities/{entity_id}/approval_methods

Request example:

Copy
Copied
{
  "type": "DSA_ED25519",
  "pub_key": "f7bdb63a96ecee424a821d1a5e1f7d582eaabac453ba0560d4e05ff67ece2f20"
}

Response example:

Copy
Copied
{
  "id": "6ec2fbc16ccb8238cbc89b3bf7ea7f39apmt",
  "entity_id": "31adbcbbcede1a7a8cffb4a0e598ad5centy",
  "type": "DSA_ED25519",
  "state": "ACTIVATED",
  "created_at": "2019-11-03T12:21:16Z",
  "updated_at": "2019-11-03T12:46:10Z"
}

Click here to view the full API reference.

GET List all ApprovalMethods

This endpoint returns an array containing all ApprovalMethods associated with the Entity specified in the request URL.

Request URL:

GET /entities/{entity_id}/approval_methods

Response example:

Copy
Copied
{
  "items": [
    {
      "id": "6ec2fbc16ccb8238cbc89b3bf7ea7f39apmt",
      "entity_id": "31adbcbbcede1a7a8cffb4a0e598ad5centy",
      "type": "AUTHY_PUSH",
      "state": "ACTIVATED",
      "created_at": "2019-11-03T12:21:16Z",
      "updated_at": "2019-11-03T12:46:10Z"
    }
  ],
  "pagination": {
    "next": 0,
    "prev": 0
  }
}

Click here to view the full API reference.

GET Retrieve an ApprovalMethod

This endpoint returns information about the ApprovalMethod specified in the request URL.

Request URL:

GET /entities/{entity_id}/approval_methods/{approval_method_id}

Response example:

Copy
Copied
{
  "id": "6ec2fbc16ccb8238cbc89b3bf7ea7f39apmt",
  "entity_id": "31adbcbbcede1a7a8cffb4a0e598ad5centy",
  "type": "AUTHY_PUSH",
  "state": "ACTIVATED",
  "created_at": "2019-11-03T12:21:16Z",
  "updated_at": "2019-11-03T12:46:10Z"
}

Click here to view the full API reference.

ApprovalRequests

Any Transaction initiated by an API request (i.e., a Withdrawal or Transfer) must be approved by the account holder of the originating account (i.e., the Entity that owns it, or an authorized REPRESENTATIVE_PERSON Entity) before the SDA platform will process it.

The SDA platform facilitates this process using the ApprovalRequest resource.

The process for approving an ApprovalRequest differs based on the ApprovalMethod active for the Transaction initiator. The instructions for each type of ApprovalMethod are described in detail below.

AUTHY_PUSH approval process

The process for approving Transactions using AUTHY_PUSH is as follows:

  1. The customer requests a Transaction.
  2. Request an ApprovalRequest from the SDA platform by calling the POST Request ApprovalRequest endpoint.
  3. The SDA platform sends a challenge to the customer's smartphone via a secure channel.
  4. The customer approves or denies the ApprovalRequest.

    • If the customer approves the ApprovalRequest, then the platform will process the transaction.
    • If the customer denies the ApprovalRequest, then the platform will cancel the transaction.
    • If the customer takes no action on the ApprovalRequest, then the ApprovalRequest will fail after a period that can be configured for your solution. This will also fail the Transaction.

Note that you can fetch the state of the ApprovalRequest using the GET Retrieve an ApprovalRequest API endpoint.

SMS approval process

The process for approving Transactions using the SMS method is as follows:

  1. The customer requests a Transaction.
  2. Request an ApprovalRequest from the SDA platform by calling the POST Request ApprovalRequest endpoint.
  3. The SDA platform sends a challenge to the customer's smartphone via SMS.
  4. The customer submits the SMS code in your frontend.
  5. Pass the customer's SMS code to the platform using the POST Approve ApprovalRequest endpoint.
  6. If the customer provided the correct code, then the platform will process the Transaction.
warning

For security reasons, the SDA platform only allows one attempt to confirm each SMS ApprovalRequest. If the attempt fails, then the platform will cancel the Transaction.

DSA_ED25519 approval process

The process for approving Transactions using the DSA_ED25519 method is as follows:

  1. The customer requests a Transaction.
  2. Request an ApprovalRequest from the SDA platform by calling the POST Request ApprovalRequest endpoint.
  3. The response to the above API call will contain the challenge.attrs property, which contains the attributes needed to construct the challenge string. Generate the challenge string (as a SHA-256 digest) according to the instructions below.
  4. In your frontend, the customer confirms the transaction. On the backend, your solution signs the challenge string using the private approval key.
  5. Pass the customer's signature to the platform using the POST Approve ApprovalRequest endpoint.
  6. When the platform successfully validates the provided challenge, it will begin to process the Transaction.

How to generate the challenge string

To construct the challenge string, you must use properties from the Transaction to be approved.

Query the Transaction resource using GET Retrieve a Transaction and use the properties as follows:

  1. For each attribute in the challenge.attrs list, concatenate the following strings into a single attribute_string:

    • The attribute name (e.g., account_id)
    • An ASCII colon (:)
    • An ASCII space
    • The value of the attribute (e.g., 09934947ffdd4bef50ba88ddc5eab0bfacct)
  2. Construct the challenge_string value by concatenating all attribute_string values in the order they are listed in the challenge.attrs array, using the ASCII newline character (\n) as a delimiter. Do not end the string with a newline character.
  3. Sign the challenge_string using the private approval key.

The result is a hexadecimal representation of the Ed25519 signature of the challenge message.

Example

Suppose there is a Withdrawal Transaction:

Copy
Copied
{
  "id": "f4342c75f714405d89007ef13ce68688atrx",
  "account_id": "f52b22a8256cd2b0ad21f3c2cc2c5875acct",
  "type": "WITHDRAWAL",
  "state": "PENDING",
  "amount": "-0.00000001",
  "fee_amount": "1.00000000",
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "reference": "some-reference-ea1ee054",
  "created_at": "2019-08-21T10:47:34Z",
  "updated_at": "2019-08-21T10:47:34Z"
}

And the API returns an ApprovalRequest with the following challenge after calling the POST endpoint:

Copy
Copied
200 OK

{
  "id": "ba9e224ba82ea200114803e5ce3ee839aprq",
  "resource_id": "f4342c75f714405d89007ef13ce68688atrx",
  "resource_type": "TRANSACTION",
  "type": "DSA_ED25519",
  "state": "PENDING",
  "challenge": {
    "attrs": ["id","account_id","type","amount","fee_amount","address","reference"]
  },
  "created_at": "2019-08-21T10:47:34Z",
  "updated_at": "2019-08-21T10:47:34Z"
}

In this case, you would build the challenge string out of the following lines:

id: f4342c75f714405d89007ef13ce68688atrx\n
account_id: f52b22a8256cd2b0ad21f3c2cc2c5875acct\n
type: WITHDRAWAL\n
amount: -0.00000001\n
fee_amount: 1.00000000\n
address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa\n
reference: some-reference-ea1ee054

Suppose the approval key looks as follows:

{
  "type": "ed25519",
  "prv_key": "9d7d82e1a21d87abc328630f7844d8a7054edad004210043e6f2aa7674dbd93c",
  "pub_key": "d7be9b9a905185869bf063d36587722646b44e15d6c577e7523187614f79cca9"
}

Use the prv_key value to sign the challenge string. The signature would look like this:

4c989d1dd671f6092fe835e39170521e59ead4b85d2fa7cf68322f9b27e064ee3765680fa8dca0e48c572f65d7ca25666a32389890474041fbcfc11b46b74d0a

Submit this value to the POST Approve an ApprovalRequest endpoint as the value of response.

Optionally, you can provide a SHA-256 digest of the challenge message as the value of sha256 within the challenge object. The API will validate the digest in addition to the signature. The SHA-256 digest of this challenge message would be:

d5779cee74f98ef140c2c62ae452a9dcd4a94a9959e70a5ad69472ae714d9f49

GROUP approval process

The process for approving Transactions with the GROUP method is as follows:

  1. The customer requests a transaction.
  2. Request an ApprovalRequest of type GROUP from the SDA platform by calling the POST Request ApprovalRequest endpoint.
  3. Request an ApprovalRequest of type APPROVAL_REQUESTS for each member of the approval group using the above API method.
  4. The members of the group will approve or deny the ApprovalRequest using the ApprovalMethod created for them.
  5. If quorum is reached (i.e., the designated number of approval group members approve the Transaction), then the platform will process the Transaction.