Configure device registration¶

Before WSO2 Identity Platform can assert anything about a device, the device has to be registered. Registration links a device to a user account and establishes the key the device uses to identify itself afterwards.

Devices are registered through the Device Registration step of a flow you design in the Flow Builder. The step is available in the following flows:

Self registration - The user signs themselves up and registers their device as part of creating the account, so the user has a registered device from their first sign-in.
Invited user registration - An administrator invites the user, and the user registers their device while accepting the invitation and setting up the account.

Before you begin¶

If you want to allow only compliant devices, create a device assurance policy.
Make sure your application can register a device. A native application registers the device directly while it runs the flow. See Integrate device management in your app.

How the step works¶

When the flow reaches the Device Registration step, WSO2 Identity Platform issues a one-time challenge. The application on the device signs the challenge with a key that it generates and keeps on the device, and sends the public key and the signature back. WSO2 Identity Platform verifies the signature and, if a policy is set on the step, evaluates the policy against the device attributes the application reports. A device that doesn't comply with the policy is refused, and the user sees which conditions failed.

The device is registered to the user only when the whole flow completes successfully.

An authentication step must come first

The Device Registration step must come after a step that authenticates the user, such as an Email OTP View, SMS OTP View, Magic Link View, or Passkey View, or a sign-up with a social connection. This makes sure the device is linked to a user who has proven control of the account. The Flow Builder shows the following error when you save a flow that doesn't meet this requirement: Device registration needs an authentication step, such as Email OTP, SMS OTP or Passkey, before it in the flow.

Add device registration to self-registration¶

You can start from the Basic + Device Registration template, or add the step to an existing flow.

Use the template¶

The Basic + Device Registration template collects the user's details, verifies the email address, and registers the user's device.

On the WSO2 Identity Platform Console, go to Flows.
Click the Self Registration card.
Under Starter Templates, click the + icon next to Basic + Device Registration to load it onto the canvas.
Optionally, attach a device assurance policy to the Device Registration step.
Click Save Draft, and turn the toggle on the top-right corner ON to publish the flow.

Add the step to an existing flow¶

On the WSO2 Identity Platform Console, go to Flows and click the Self Registration card.
From the Steps panel, drag and drop a Device Registration step onto the canvas.
Connect the step after an authentication step. For example, delete the connection from the Email OTP View to the End node, draw a connection from the Email OTP View to the Device Registration step, and then from the Device Registration step to the End node.
Optionally, attach a device assurance policy to the step.
Click Save Draft, and turn the toggle on the top-right corner ON to publish the flow.

Add device registration to invited user registration¶

On the WSO2 Identity Platform Console, go to Flows and click the Invited User Registration card.
From the Steps panel, drag and drop a Device Registration step onto the canvas.
Connect the step after an authentication step, such as an Email OTP View, SMS OTP View, or Passkey View. If the flow doesn't have one yet, add it from the Steps panel and place it before the Device Registration step.
Optionally, attach a device assurance policy to the step.
Click Save Draft, and turn the toggle on the top-right corner ON to publish the flow.

Attach a device assurance policy¶

Any flow can optionally enforce a device assurance policy at registration time, so that non-compliant devices are refused at the point of registration rather than allowed in and blocked later.

In the Flow Builder, click the Device Registration step on the canvas.
In the properties panel on the right, select a policy from the Device policy list.
Click Save Draft.

If you leave Device policy empty, any device can be registered. The device is identified, but nothing is asserted about how secure it is.

Tip

Enforcing at registration is worth doing even when you also enforce at login. It gives the user a clear failure at a moment when they are already setting something up and expecting to follow instructions, rather than when they are trying to sign in to get work done.

Troubleshooting¶

The following errors can occur at the Device Registration step.

Error code	Cause
`DR-60002`	The device signature is invalid. The application must sign the challenge from the current step with the private key that matches the public key it sends.
`DR-60004`	The device doesn't comply with the policy set on the step. The error lists the attributes that failed.
`DR-60005`	A policy is set on the step, but the application didn't send device data.
`DR-60006`	The user wasn't verified by an authentication step before the Device Registration step. Add an authentication step before it.
`DPM-60010`	The policy set on the step doesn't exist, for example because it was deleted. Select another policy on the step.