Skip to content

Device management

Device management lets you tie a user's account to the specific devices they use, and decide whether a device is trusted enough to be allowed in. A device registers itself with WSO2 Identity Platform once. From then on, it can prove that it is the same registered device whenever it signs in.

On top of that, you can define device assurance policies that check the security posture of a device, such as whether it is rooted, whether the screen is locked, or whether the disk is encrypted, and refuse registration or sign-in when the device does not meet your requirements.

Device management has two halves, and it helps to keep them separate:

  • Registration - How a device first becomes known to WSO2 Identity Platform and gets linked to a user.

  • Assurance - How you check that the device meets your security requirements, both when it registers and when it signs in.

Key concepts

The following concepts are used throughout the device management guides.

Registered device

A registered device is a device that is linked to a user account. During registration, the application on the device generates a key pair, keeps the private key on the device, and sends the public key to WSO2 Identity Platform. The device then proves possession of the private key by signing a challenge issued by WSO2 Identity Platform.

WSO2 Identity Platform stores the following details about each registered device:

  • Device name - A display name for the device. By default, it is built from the username and the device model, for example alex's Pixel 8. Administrators and users can rename a device.

  • Device model - The hardware model the device reported during registration, if any.

  • Status - Either Active or Inactive. Only an active device can present itself at sign-in. An inactive device is treated as if no device information was sent, so a device policy that is enforced at login can't be satisfied by it.

  • Registered on - The time the device was registered.

A user can have more than one registered device. When a user is deleted, all devices registered to that user are deleted as well.

Device assurance policy

A device assurance policy is a named set of conditions that a device must meet. A policy has separate rules for each platform: Android, iOS, macOS, and Windows. The conditions are built from device attributes that the device reports, such as isRooted or diskEncryption, and from attestation verdicts that WSO2 Identity Platform obtains from Google or Apple.

The same policy can be used in two places:

  • At registration - Set the policy on the Device Registration step of a registration flow, so that only compliant devices can be registered. See Configure device registration.

  • At login - Evaluate the policy in the conditional authentication script of an application, and decide whether to allow the sign-in, block it, or ask for an additional factor. See Enforce a device policy at login.

How it works

The following steps describe how a device is registered and how it is checked afterwards.

  1. Registration - The user goes through a self-registration or invited user registration flow that includes a Device Registration step after an authentication step, such as Email OTP. At that step, WSO2 Identity Platform issues a one-time challenge. The application on the device signs the challenge with the device key and, when a policy is set on the step, sends its device attributes in a token signed with the same key. WSO2 Identity Platform verifies the signature, evaluates the policy, and registers the device to the user when the flow completes.

  2. Login - On later sign-ins, the application sends a short-lived device token, signed with the device key, in the X-Device-Token header (for app-native authentication) or in the device_token parameter (for redirect-based sign-in). WSO2 Identity Platform identifies the registered device from the token, verifies the signature, and rejects tokens that are expired or have already been used. The device attributes in the token are then available to the conditional authentication script of the application.

Note

Only a native mobile or desktop application can hold a device key and sign with it.

Explore device management

The guides below start with policies, because a policy is the thing you reference everywhere else.

APIs

You can also manage devices and device assurance policies programmatically.