WebAuthn Preregistration

The WebAuthn preregistration API provides a flow to initiate and set up WebAuthn preregistration authenticator enrollments through third-party fulfillment providers.

Note: For information about using WebAuthn preregistration with YubiKeys, see Require phishing-resistant authentication with pre-enrolled YubiKey.

Use the following sequence of endpoints to set up WebAuthn preregistration authenticator enrollments.

  1. Generate a fulfillment request
  2. Enroll a preregistered WebAuthn factor
  3. Activate a preregistered WebAuthn factor

After you set up the preregistered WebAuthn factor, you can send the PIN to the user.

Activate a preregistered WebAuthn factor
Identity Engine
OAuth 2.0: okta.users.manage

Activates a preregistered WebAuthn factor. As part of this operation, Okta first decrypts and verifies the factor PIN and enrollment data sent by the fulfillment provider.

Request
Request Body schema: application/json

Enrollment activation request

Array of objects (WebAuthnCredResponse)

List of credential responses from the fulfillment provider

Array
authenticatorEnrollmentId
string

ID for a WebAuthn preregistration factor in Okta

credResponseJWE
string

Encrypted JSON Web Encryption (JWE) of the credential response from the fulfillment provider

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn preregistration factor

Value: "yubico"
pinResponseJwe
string

Encrypted JWE of the PIN response from the fulfillment provider

serial
string

Serial number of the YubiKey

userId
string

ID of an existing Okta user

version
string

Firmware version of the YubiKey

Array of objects (ECKeyJWK)

List of usable signing keys from Yubico (in JSON Web Key Sets (JWKS) format). The signing keys are used to verify the JSON Web Signature (JWS) inside the JWE.

Array
x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

kty
required
string

The type of public key

Value: "EC"
crv
required
string

The elliptic curve protocol

Value: "P-384"
use
required
string

The intended use for the key. This value is either enc (encryption) during enrollment, when Okta uses the ECKeyJWK to encrypt requests to Yubico. Or it's sig (signature) during activation, when Okta uses the ECKeyJWK to verify the responses from Yubico.

Enum: "enc" "sig"
kid
required
string

The unique identifier of the key

Responses
200

Success

400

PIN or cred requests generation failed

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/activate
Request samples
application/json
{
  • "credResponses": [
    • {
      }
    ],
  • "fulfillmentProvider": "yubico",
  • "pinResponseJwe": "eyJl5IjoiRUMiLCJjcnYcGsiOnsia3...",
  • "serial": "3632071",
  • "userId": "00us2hPODQncCkxef0g3",
  • "version": "5.4.3",
  • "yubicoSigningJwks": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "authenticatorEnrollmentIds": [
    • "fwf5ajzJEWqknX6lk0g4"
    ],
  • "fulfillmentProvider": "yubico",
  • "userId": "00us2hPODQncCkxef0g3"
}

Enroll a preregistered WebAuthn factor
Identity Engine
OAuth 2.0: okta.users.manage

Enrolls a preregistered WebAuthn factor. This WebAuthn factor has a longer challenge timeout period to accommodate the fulfillment request process. As part of this operation, Okta generates elliptic curve (EC) key-pairs used to encrypt the factor PIN and enrollment data sent by the fulfillment provider.

Request
Request Body schema: application/json

Enrollment initialization request

enrollmentRpIds
Array of strings

List of relying party hostnames to register on the YubiKey

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn preregistration factor

Value: "yubico"
userId
string

ID of an existing Okta user

object (ECKeyJWK)

Elliptic curve key in JSON Web Key (JWK) format. It's used during enrollment to encrypt fulfillment requests to Yubico, or during activation to verify Yubico's JWS (JSON Web Signature) objects in fulfillment responses. The currently agreed protocol uses P-384.

x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

kty
required
string

The type of public key

Value: "EC"
crv
required
string

The elliptic curve protocol

Value: "P-384"
use
required
string

The intended use for the key. This value is either enc (encryption) during enrollment, when Okta uses the ECKeyJWK to encrypt requests to Yubico. Or it's sig (signature) during activation, when Okta uses the ECKeyJWK to verify the responses from Yubico.

Enum: "enc" "sig"
kid
required
string

The unique identifier of the key

Responses
200

Success

400

PIN or cred requests generation failed

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/enroll
Request samples
application/json
{
  • "enrollmentRpIds": [
    • "myorg.okta.com"
    ],
  • "fulfillmentProvider": "yubico",
  • "userId": "00us2hPODQncCkxef0g3",
  • "yubicoTransportKeyJWK": {
    • "crv": "P-384",
    • "kid": "APCS-Ttrans-C19881-I009",
    • "kty": "EC",
    • "use": "enc",
    • "x": "r6AzcX3OSiJk1yQaBVYiBOtzFS9gNSpMDPvnVvl0CAX7el1ZyzmPG_BZ7u8sqTmF",
    • "y": "RxPyGH1Xg74E2f5AQGkkddzsvTNY1R3R7mXTEM5wQtr1Y7C4XHlvITNZfU6G"
    }
}
Response samples
application/json
{
  • "credRequests": [
    • {
      }
    ],
  • "fulfillmentProvider": "yubico",
  • "pinRequestJwe": "eyJlcGsa3R5IjoiRUMiLA...",
  • "userId": "00us2hPODQncCkxef0g3"
}

Generate a fulfillment request
Identity Engine
OAuth 2.0: okta.users.manage

Generates a fulfillment request by sending a WebAuthn preregistration event to start the flow. The WebAuthn preregistration integration for Okta Workflows uses a preregistration event to populate the fulfillment request.

Request
Request Body schema: application/json

Fulfillment request

object (FulfillmentData)

Fulfillment provider details

customizationId
string

ID for the set of custom configurations of the requested factor

inventoryProductId
string

ID for the specific inventory bucket of the requested factor

productId
string

ID for the make and model of the requested factor

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn preregistration factor

Value: "yubico"
userId
string

ID of an existing Okta user

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/initiate-fulfillment-request
Request samples
application/json
{
  • "userId": "00us2hPODQncCkxef0g3",
  • "fulfillmentProvider": "yubico",
  • "fulfillmentData": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Send a PIN to user
Identity Engine
OAuth 2.0: okta.users.manage

Sends the decoded PIN for the specified WebAuthn preregistration enrollment. PINs are sent to the user's email. To resend the PIN, call this operation again.

Request
Request Body schema: application/json

Send PIN request

authenticatorEnrollmentId
string

ID for a WebAuthn preregistration factor in Okta

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn preregistration factor

Value: "yubico"
userId
string

ID of an existing Okta user

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/send-pin
Request samples
application/json
{
  • "authenticatorEnrollmentId": "fwf5ajzJEWqknX6lk0g4",
  • "fulfillmentProvider": "yubico",
  • "userId": "00us2hPODQncCkxef0g3"
}
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all WebAuthn preregistration factors
Identity Engine
OAuth 2.0: okta.users.read

Lists all WebAuthn preregistration factors for the specified user

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/webauthn-registration/api/v1/users/{userId}/enrollments
Request samples 
Response samples 
application/json
[
  • {
    • "id": "fwf23789dfs9asdf782",
    • "factorType": "webauthn",
    • "provider": "FIDO",
    • "vendorName": "FIDO",
    • "fulfillmentProvider": "yubico",
    • "status": "ACTIVE",
    • "created": "2018-05-24T20:43:19.000Z",
    • "lastUpdated": "2018-05-24T21:43:32.000Z",
    • "profile": {
      },
    • "_links": {}
    }
]
Delete a WebAuthn preregistration factor
Identity Engine
OAuth 2.0: okta.users.manage
Deletes a specific WebAuthn preregistration factor for a user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
authenticatorEnrollmentId
required
string
ID for a WebAuthn preregistration factor in Okta


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/webauthn-registration/api/v1/users/{userId}/enrollments/{authenticatorEnrollmentId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Assign the fulfillment error status to a WebAuthn preregistration factor
Identity Engine
OAuth 2.0: okta.users.manage
Assigns the fulfillment error status to a WebAuthn preregistration factor for a user. The /mark-error path indicates that the specific FULFILLMENT_ERRORED AuthFactor status is set on the enrollment.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
authenticatorEnrollmentId
required
string
ID for a WebAuthn preregistration factor in Okta


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/webauthn-registration/api/v1/users/{userId}/enrollments/{authenticatorEnrollmentId}/mark-error
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}