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 Server 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 Server 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 Server. The device then proves possession of the private key by signing a challenge issued by WSO2 Identity Server.

WSO2 Identity Server 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 Server 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 Server 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 Server 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 Server 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.

Enable device management

Device management is disabled by default. To enable it, add the following configuration to the deployment.toml file found in the <IS_HOME>/repository/conf directory and restart WSO2 Identity Server.

[device_management]
disable_apis = false
disable_registration_executor = false
Property Description
disable_apis When set to true (default), the device management and policy management REST APIs are disabled. The Console pages for device assurance policies and user devices use these APIs, so set this to false to manage policies and devices.
disable_registration_executor When set to true (default), the Device Registration step isn't available in the Flow Builder and the Basic + Device Registration template isn't shown. Set this to false to register devices through registration flows.

Device token cleanup

To prevent replay, WSO2 Identity Server records the identifier (jti) of every device token it accepts and rejects any token that is used again. A cleanup task removes expired records periodically. You can change its behavior with the following configuration in the deployment.toml file.

[device_token.cleanup]
enable_expired_jti_cleanup = true
clean_expired_jti_every = "1d"
Property Description Default
enable_expired_jti_cleanup Whether the cleanup task runs. true
clean_expired_jti_every How often the cleanup task runs. 1d

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.