Delegated Registration

POST /auth/registration/delegated

Only a Service Account can use this endpoint.

If you want to use your own authentication system, while still using Delegated Signing, you can use this endpoint to register a new User in your organization, without your user needing to receive an email from Dfns.

This endpoint will:

1. Create a new User attached to your organization

2. Initiates a User Registration Challenge and returns the registration challenge.

On successful creation, the user's registration challenge will be returned. You will then need to call Complete User Registration to complete the user's registration.

• Service account required. See Service Accounts for more information.

• User action signature required. See User Action Signing for more information.

• Request headers required. See Request Headers for more information.

• Authentication required. See Authentication Headers for more information.

Required Permissions

Name	Conditions
Auth:Register:Delegated	Always Required

Request body

email *	String	email of the user being created. For EndUser kind, this can also be some unique uuid of your system, not necessarily an actual email
kind *	String	kind of user being created. Can only beEndUser

Example:

{
  "email": "[email protected]",
  "kind": "EndUser"
}

Responses

• See Common Errors for common errors.

• See Delegated Authentication Errors for delegated authentication specific errors.

200

Success - an object containing the user's authentication options

The "challenge" is the value that needs to be sent to the user to be signed in order to Complete User Registration

Format:

{
  // 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

// In this example the challenge "MmE5YzRmMzMwY2NlNGUyMjhjZWYzMzlhZDBhZmIxNzk"
// needs to be sent to the user for signature to complete the registration
{
  "rp": {
    "id": "dfns.io",
    "name": "Dfns",
  },
  "user": {
    "id": "us-2ba0h-lvp2q-8v1860pcj1bh5irf",
    "name": "[email protected]",
    "displayName": "[email protected]"
  },
  "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"
  }
}