Create User Registration Challenge

POST /auth/registration/init

Starts a user registration session, returning a challenge that will be used to verify the user's identity.

Required Permissions

Since this endpoint is not authenticated, the permissions apply to the application only.

Name
Conditions

Auth:Users:Read

Always Required

Request body

username *

String

Email address of the user

registrationCode *

String

The secret value that the user received in their registration email

orgId *

String

ID of the target Org

Example:

{
  "username": "jdoe@example.co",
  "registrationCode": "1234-1234-1234-1234",
  "orgId": "or-34513-nip9c-8bppvgqgj28dbodrc"
}

Responses

Success - an object containing the user's authentication options

Format:

{
  // Relying Party information that identifies the application to the user
  "rp": {
    // the domain of the server that is requesting the credential. This must match the effective domain of the application communicating with the user's WebAuthn client
    "id": "string",
    // a user friendly name to help identify the server requesting the credential
    "name": "string",
  },
  // identifies the user that is being logged into the Dfns API
  "user": {
    // id that ties the user to the credential created in the user's WebAuthn client
    "id": "string",
    // additional value that will be displayed to the user on the WebAuthn client's display
    "name": "string",
    // name that will be displayed to the user on the WebAuthn client's display
    "displayName": "string"
  },
  // temporary authentication token that is used to identify the registration session with the matching call to Complete User Registration
  "temporaryAuthenticationToken": "string",
  // list of the kinds of credentials that the user can use when registering
  "supportedCredentialKinds": {
    // list of the credential kinds that are supported as a first factor credential
    "firstFactor": ["string"],
    // list of the credential kinds that are supported as a second factor credential
    "secondFactor": ["string"]
  },
  // random value used to uniquely identify the request. This value will be included in the data that is signed
  "challenge": "string",
  // list of objects that identify the signing algorithms that are supported
  "pubKeyCredParam": [
    {
      // will always be `public-key`
      "type": "public-key",
      // an integer that identifies a signing algorithm. Can be either `-7` for ES256 or `-257` for RS256
      "alg": "number"
    },
  ],
  // identifies the information needed to verify the user's signing certificate; can be one of the following:
  // * none: indicates no attestation data is required
  // * indirect: indicates the attestation data should be given, but that it can be generated using an Anonymization CA
  // * direct: indicates the attestation data must be given and should be generated by the authenticator
  // * enterprise: indicates the attestation data should include information to uniquely identify the user's device
  "attestation": "string",
  // a list of objects that identify credentials that the user's WebAuthn client should not use
  "excludeCredentials": [
    {
      // will always be `public-key`
      "type": "public-key",
      // ID that can identify the credential on the authenticator
      "id": "string",
      // types of transports that are not allowed. Can be one of the following:
      // * usb for usb support
      // * nfc for near field communication (NFC) support
      // * ble for bluetooth support
      // * internal for non-removable authenticators
      // * hybrid for multiple transport methods
      "transports": "string"
    }
  ],
  // identifies the criteria that the user's WebAuthn client should use when creating the credential
  "authenticatorSelection": {
    // optional value indicating the type of authenticators that are supported. If not set then the authenticator type is not restricted. Can be one of the following:
    // * platform for requiring the authenticator be tied to the users device (like a TPM)
    // * cross-platform for the authenticator to be an external device (like a Yubikey)
    "authenticatorAttachment": "string",
    // value indicating whether or not the authenticator should use resident keys. Can be one of the following:
    // * discouraged to indicate the authenticator should not use a resident key unless its the only option
    // * preferred to indicate the authenticator should try to use a resident key if supported
    // * required to indicate the authenticator must use a resident key
    "residentKey": "required",
    // value indicating if the authenticator needs to support resident keys
    "requireResidentKey": "boolean",
    // value indicating if the user should be prompted for a second factor. Can be one of the following values:
    // * required to indicate the user must be prompted for their pin, biometrics, or another second factor option
    // * preferred to indicate the user should be prompted for a second factor if it is supported
    // * discouraged to indicate the user should not be prompted for their second factor unless the device requires it
    "userVerification": "required"
  }
}

Examples

{
  "rp": {
    "id": "dfns.io",
    "name": "Dfns",
  },
  "user": {
    "id": "us-2ba0h-lvp2q-8v1860pcj1bh5irf",
    "name": "jane@example.co",
    "displayName": "jane@example.co"
  },
  "temporaryAuthenticationToken": "eyJ0eXAiOiJKV1Q...X1bwCg35kbzsjA",
  "supportedCredentialKinds": {
    "firstFactor": ["Fido2","Key", "PasswordProtectedKey"],
    "secondFactor": ["Fido2","Key", "PasswordProtectedKey"]
  },
  "challenge": "MmE5YzRmMzMwY2NlNGUyMjhjZWYzMzlhZDBhZmIxNzk",
  "pubKeyCredParam": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "attestation": "direct",
  "excludeCredentials": [],
  "authenticatorSelection": "",{
    "residentKey": "required",
    "requireResidentKey": true,
    "userVerification": "required"
  }
}

Last updated