From 1a5c0d2fa571205268aaec95b875f4123564cc18 Mon Sep 17 00:00:00 2001 From: Malith-19 Date: Wed, 2 Sep 2026 12:43:39 +0530 Subject: [PATCH] docs: add device management guides Document device assurance policies, per-platform device attributes, attestation verdicts, login-time policy enforcement, device registration flows, and the per-user device listing for WSO2 Identity Server (next). --- .../configure-device-registration.md | 1 + .../device-assurance-policies.md | 1 + .../device-management/device-attestation.md | 1 + .../device-management/device-attributes.md | 1 + .../enforce-device-policy-at-login.md | 1 + .../docs/guides/device-management/index.md | 1 + .../device-management/view-user-devices.md | 1 + en/identity-server/next/mkdocs.yml | 8 +++ .../configure-device-registration.md | 48 +++++++++++++++++ .../device-assurance-policies.md | 49 +++++++++++++++++ .../device-management/device-attestation.md | 51 ++++++++++++++++++ .../device-management/device-attributes.md | 52 ++++++++++++++++++ .../enforce-device-policy-at-login.md | 54 +++++++++++++++++++ en/includes/guides/device-management/index.md | 30 +++++++++++ .../device-management/view-user-devices.md | 11 ++++ 15 files changed, 310 insertions(+) create mode 100644 en/identity-server/next/docs/guides/device-management/configure-device-registration.md create mode 100644 en/identity-server/next/docs/guides/device-management/device-assurance-policies.md create mode 100644 en/identity-server/next/docs/guides/device-management/device-attestation.md create mode 100644 en/identity-server/next/docs/guides/device-management/device-attributes.md create mode 100644 en/identity-server/next/docs/guides/device-management/enforce-device-policy-at-login.md create mode 100644 en/identity-server/next/docs/guides/device-management/index.md create mode 100644 en/identity-server/next/docs/guides/device-management/view-user-devices.md create mode 100644 en/includes/guides/device-management/configure-device-registration.md create mode 100644 en/includes/guides/device-management/device-assurance-policies.md create mode 100644 en/includes/guides/device-management/device-attestation.md create mode 100644 en/includes/guides/device-management/device-attributes.md create mode 100644 en/includes/guides/device-management/enforce-device-policy-at-login.md create mode 100644 en/includes/guides/device-management/index.md create mode 100644 en/includes/guides/device-management/view-user-devices.md diff --git a/en/identity-server/next/docs/guides/device-management/configure-device-registration.md b/en/identity-server/next/docs/guides/device-management/configure-device-registration.md new file mode 100644 index 0000000000..07fca64273 --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/configure-device-registration.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/configure-device-registration.md" %} diff --git a/en/identity-server/next/docs/guides/device-management/device-assurance-policies.md b/en/identity-server/next/docs/guides/device-management/device-assurance-policies.md new file mode 100644 index 0000000000..1274b55dfa --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/device-assurance-policies.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/device-assurance-policies.md" %} diff --git a/en/identity-server/next/docs/guides/device-management/device-attestation.md b/en/identity-server/next/docs/guides/device-management/device-attestation.md new file mode 100644 index 0000000000..f343b5f323 --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/device-attestation.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/device-attestation.md" %} diff --git a/en/identity-server/next/docs/guides/device-management/device-attributes.md b/en/identity-server/next/docs/guides/device-management/device-attributes.md new file mode 100644 index 0000000000..62ec7e2cc9 --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/device-attributes.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/device-attributes.md" %} diff --git a/en/identity-server/next/docs/guides/device-management/enforce-device-policy-at-login.md b/en/identity-server/next/docs/guides/device-management/enforce-device-policy-at-login.md new file mode 100644 index 0000000000..b14070231c --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/enforce-device-policy-at-login.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/enforce-device-policy-at-login.md" %} diff --git a/en/identity-server/next/docs/guides/device-management/index.md b/en/identity-server/next/docs/guides/device-management/index.md new file mode 100644 index 0000000000..7f33085fcb --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/index.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/index.md" %} diff --git a/en/identity-server/next/docs/guides/device-management/view-user-devices.md b/en/identity-server/next/docs/guides/device-management/view-user-devices.md new file mode 100644 index 0000000000..20716735b1 --- /dev/null +++ b/en/identity-server/next/docs/guides/device-management/view-user-devices.md @@ -0,0 +1 @@ +{% include "../../../../../includes/guides/device-management/view-user-devices.md" %} diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index d2c4f7f940..903c97b44d 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -755,6 +755,14 @@ nav: - SAML artifact binding: guides/authentication/saml/saml-artifact-binding.md - Implement SAML federated IdP-initiated SSO: guides/authentication/saml/saml-federated-idp-initiated-sso.md - SAML back-channel logout: guides/authentication/saml/saml-back-channel-logout.md + - Device management: + - Device management: guides/device-management/index.md + - Device assurance policies: guides/device-management/device-assurance-policies.md + - Device attributes: guides/device-management/device-attributes.md + - Device attestation: guides/device-management/device-attestation.md + - Enforce a device policy at login: guides/device-management/enforce-device-policy-at-login.md + - Configure device registration: guides/device-management/configure-device-registration.md + - View the devices of a user: guides/device-management/view-user-devices.md - Authorization: - Authorization: guides/authorization/index.md - API authorization: diff --git a/en/includes/guides/device-management/configure-device-registration.md b/en/includes/guides/device-management/configure-device-registration.md new file mode 100644 index 0000000000..35beb05b8a --- /dev/null +++ b/en/includes/guides/device-management/configure-device-registration.md @@ -0,0 +1,48 @@ +# Configure device registration + +Before {{product_name}} can assert anything about a device, the device has to be registered. Registration links a device to a user account and establishes the credential the device uses to identify itself afterwards. + +## App-native authentication is required + +Registration requires the device to generate a cryptographic key pair, hold the private key in the secure hardware of the device, and sign a challenge with it. Only a native mobile or desktop application can do that. A browser-based redirect sign-in has no access to the key store of the device, so device registration cannot be offered in that case. + +In practice, your application must be a native application using [app-native authentication]({{base_path}}/guides/authentication/app-native-authentication/) before any of this applies. Users who sign in through a standard browser redirect do not see a device registration step and cannot be enrolled. + +## Registration flows + +A device can be registered through three different flows. Which one you use depends on when in the lifecycle of the user you want the device enrolled. All three run inside app-native authentication. + +### Self-registration + +The user signs themselves up and registers their device as part of creating their account. Registration happens at the same moment the account is created, so the user has a trusted device from their first sign-in. + +Use this when users onboard themselves through a public sign-up page. See [Self registration]({{base_path}}/guides/flows/self-registration/). + +### Invited user registration + +An administrator invites the user, the user accepts the invitation, and the device is registered as part of accepting it. The account already exists, and the invitation flow completes the setup, including enrolling the device. + +Use this when access is granted by an administrator rather than requested by the user, which is the usual pattern inside an organization. See [Invited user registration]({{base_path}}/guides/flows/invited-user-registration/). + +### Dedicated device registration flow + +A standalone flow whose only purpose is registering a device against an account that already exists. The user authenticates as they normally would, then goes through device registration on its own. + +Use this for the cases the other two flows do not cover, which in practice is most of the ongoing work: + +- A user who already had an account before device assurance was introduced. + +- A user who has replaced their phone. + +- A user who needs a second device, such as a tablet alongside a phone, or a work laptop alongside both. + +Most organizations end up using this flow far more than the other two once the initial rollout is done. + +## Attach a policy to registration + +Any of the three flows can optionally enforce a [device assurance policy]({{base_path}}/guides/device-management/device-assurance-policies/) at registration time. Set the policy name on the device registration step in the flow, and non-compliant devices are refused at the point of registration rather than allowed in and blocked later. + +If you leave the policy name unset, the device is registered without any posture check. 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]({{base_path}}/guides/device-management/enforce-device-policy-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 at the start of a working day when they are trying to get to work. diff --git a/en/includes/guides/device-management/device-assurance-policies.md b/en/includes/guides/device-management/device-assurance-policies.md new file mode 100644 index 0000000000..3065e83590 --- /dev/null +++ b/en/includes/guides/device-management/device-assurance-policies.md @@ -0,0 +1,49 @@ +# Device assurance policies + +A device assurance policy is a named set of conditions that a device must meet. You define the policy once and then reference it by name in two places: at [registration time]({{base_path}}/guides/device-management/configure-device-registration/) and at [login time]({{base_path}}/guides/device-management/enforce-device-policy-at-login/). + +A policy is made up of one rule per platform. You do not write a single rule that covers every operating system. Instead, you write an Android rule, an iOS rule, a macOS rule, and a Windows rule, and {{product_name}} evaluates each one only against devices of that platform. + +This design exists because the security attributes of an Android phone and a Windows laptop do not overlap. Asking a Windows machine whether it is jailbroken is meaningless. + +## How a policy is structured + +The following example shows a policy named `Corporate Device Policy` with a rule for each of the four platforms. + +```text +Policy: "Corporate Device Policy" + ├── android → rule: isRooted equals false AND lockScreen equals true AND diskEncryption equals true + ├── ios → rule: jailbreak equals false AND passcode equals true + ├── macos → rule: diskEncryption equals true AND secureEnclave equals true + └── windows → rule: trustedPlatformModule equals true AND windowsHello equals true +``` + +When a device presents itself, {{product_name}} reads its `platform` attribute, picks the matching rule, and evaluates only that rule. If the device reports a platform that has no rule, no condition applies to it and the device passes. + +!!! warning + Leaving a platform out of a policy means devices on that platform are never checked. Add a rule for every platform you intend to enforce. + +## Create a policy + +Policies are created and managed from the {{product_name}} Console. Each policy needs the following: + + + + + + + + + + + + + + + + + + +
FieldDescription
NameA name that is unique within the organization. This is the name you reference from the registration flow and from the adaptive authentication script, so pick something stable. The name cannot be changed after you create the policy.
RulesOne rule per platform you want to cover. Leave a platform out entirely if you do not want to enforce anything on it.
+ +When you build a rule, the Console offers only the attributes that apply to the platform whose rule you are editing. For the full set, see [Device attributes]({{base_path}}/guides/device-management/device-attributes/). diff --git a/en/includes/guides/device-management/device-attestation.md b/en/includes/guides/device-management/device-attestation.md new file mode 100644 index 0000000000..a9d3a13de5 --- /dev/null +++ b/en/includes/guides/device-management/device-attestation.md @@ -0,0 +1,51 @@ +# Device attestation + +Attestation is how {{product_name}} learns whether a device is genuine rather than an emulator, a modified build, or a repackaged copy of your application. Google and Apple each provide an attestation service, and {{product_name}} turns their verdict into a [device attribute]({{base_path}}/guides/device-management/device-attributes/) that you can write policy conditions against. + +## Configure attestation + +Attestation is configured per application, on the **Advanced** tab of the application under the **Client Attestation** section. For the full steps, including the service account credentials needed for Android and the app ID needed for Apple, see [Secure app-native authentication flows]({{base_path}}/guides/authentication/app-native-authentication/secure-app-native-authentication-flows/#using-client-attestation). + +!!! note + Until attestation is configured for an application, the `Android integrity` and `iOS device genuine` attributes carry no useful verdict. A policy that depends on them will not behave as you expect. + +## Android integrity levels + +Google returns a verdict, and {{product_name}} maps it to one of the following values, strongest first. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueWhat Google is saying
MEETS_STRONG_INTEGRITYGenuine device, recent security updates, and strong hardware-backed guarantees.
MEETS_DEVICE_INTEGRITYGenuine Android device running genuine Android software.
MEETS_BASIC_INTEGRITYThe device passes basic checks, but Google cannot fully vouch for it.
MEETS_VIRTUAL_INTEGRITYAn emulator running genuine Android software, rather than a physical device.
INTEGRITY_FAILEDGoogle could not verify the device, or attestation is not working.
+ +Because these values are ordered, a sensible rule is `Android integrity` equals `MEETS_DEVICE_INTEGRITY` or stronger, rather than merely "not failed". + +## iOS device genuine + +Attestation from Apple is a simpler yes-or-no verdict. Either the device and the application passed verification (`true`) or they did not (`false`). diff --git a/en/includes/guides/device-management/device-attributes.md b/en/includes/guides/device-management/device-attributes.md new file mode 100644 index 0000000000..d3cc6c169c --- /dev/null +++ b/en/includes/guides/device-management/device-attributes.md @@ -0,0 +1,52 @@ +# Device attributes + +These are the attributes you can build [device assurance policy]({{base_path}}/guides/device-management/device-assurance-policies/) conditions from. Each attribute is only available on the platforms listed below, and the Console offers only the attributes that make sense for the platform whose rule you are editing. + +## Available on every platform + +| Attribute | What it checks | Values | +| --------- | -------------- | ------ | +| **platform** | The operating system the device runs. {{product_name}} uses this to select which rule applies, so you rarely need to test it inside a rule. | `android`, `ios`, `macos`, `windows` | +| **lock screen** | Whether the device has any screen lock configured at all. This is the broadest check for whether a device is locked when idle. | `true`, `false` | + +## Android + +| Attribute | What it checks | Values | +| --------- | -------------- | ------ | +| **Android OS version** | The Android major version the device runs. Supports `equals`, `greater than or equal to`, and `in`. | `9` through `17` | +| **is rooted** | Whether the device has been rooted, giving apps and the user unrestricted system access. A rooted device can defeat most other protections, so this is often the first condition to add. | `true`, `false` | +| **USB debugging** | Whether developer-mode USB debugging is turned on. When enabled, anyone with physical access and a cable can read application data and drive the device. | `true`, `false` | +| **hardware keystore** | Whether cryptographic keys are held in dedicated security hardware rather than in software. Hardware-held keys cannot be copied off the device. | `true`, `false` | +| **biometric** | Whether the user has enrolled a fingerprint or a face for unlocking. | `true`, `false` | +| **screen lock complexity** | How strong the screen lock is. `high` means a long password or a complex PIN. `low` means something trivially guessable, such as a four-digit PIN or a swipe pattern. | `high`, `medium`, `low` | +| **disk encryption** | Whether device storage is encrypted at rest, so data cannot be read by pulling the storage out of a lost or stolen device. | `true`, `false` | +| **network proxies** | Whether a network proxy is configured. A proxy can be legitimate corporate infrastructure, but it can also be an attacker intercepting traffic. Decide which case applies in your environment before enforcing this. | `true`, `false` | +| **WiFi network security** | Whether the Wi-Fi network the device is currently on is encrypted rather than an open public network. | `true`, `false` | +| **Android integrity** | Google's verdict on whether this is a genuine, unmodified Android device. This attribute is only meaningful when [device attestation]({{base_path}}/guides/device-management/device-attestation/) is configured. | `MEETS_STRONG_INTEGRITY`, `MEETS_DEVICE_INTEGRITY`, `MEETS_BASIC_INTEGRITY`, `MEETS_VIRTUAL_INTEGRITY`, `INTEGRITY_FAILED` | + +## iOS + +| Attribute | What it checks | Values | +| --------- | -------------- | ------ | +| **iOS version** | The iOS major version the device runs. Supports `equals`, `greater than or equal to`, and `in`. | `14` through `26`, plus `LATEST_IOS` and `SECOND_LATEST_IOS` | +| **jailbreak** | Whether the device has been jailbroken. Jailbreaking gives the same unrestricted access that rooting gives on Android, and is equally worth blocking. | `true`, `false` | +| **passcode** | Whether the user has set a device passcode. Without one, most of the data protection in iOS does nothing. | `true`, `false` | +| **Touch ID or Face ID** | Whether the user has enrolled a fingerprint or a face for unlocking. | `true`, `false` | +| **iOS device genuine** | The verdict from Apple on whether this is a genuine iOS device running a genuine copy of your application. See [device attestation]({{base_path}}/guides/device-management/device-attestation/). | `true`, `false` | + +## macOS + +| Attribute | What it checks | Values | +| --------- | -------------- | ------ | +| **macOS version** | The macOS major version. Supports `equals`, `greater than or equal to`, and `in`. | `12` through `15`, plus `LATEST_MACOS` and `SECOND_LATEST_MACOS` | +| **disk encryption** | Whether FileVault is on, encrypting the disk at rest. | `true`, `false` | +| **secure enclave** | Whether the Mac has a Secure Enclave, the dedicated security chip that holds keys and biometric data separately from the main processor. | `true`, `false` | + +## Windows + +| Attribute | What it checks | Values | +| --------- | -------------- | ------ | +| **Windows version** | The Windows major version. Supports `equals`, `greater than or equal to`, and `in`. | `10`, `11`, plus `LATEST_WINDOWS` and `SECOND_LATEST_WINDOWS` | +| **disk encryption** | Whether BitLocker is on, encrypting the drive at rest. | `true`, `false` | +| **Windows Hello** | Whether Windows Hello, the built-in biometric or PIN sign-in, is configured. | `true`, `false` | +| **Trusted Platform Module** | Whether a TPM is present and enabled. The TPM is the hardware that makes BitLocker and Windows Hello meaningfully secure rather than merely convenient. | `true`, `false` | diff --git a/en/includes/guides/device-management/enforce-device-policy-at-login.md b/en/includes/guides/device-management/enforce-device-policy-at-login.md new file mode 100644 index 0000000000..f3cfe04603 --- /dev/null +++ b/en/includes/guides/device-management/enforce-device-policy-at-login.md @@ -0,0 +1,54 @@ +# Enforce a device policy at login + +Registration decides whether a device is allowed to be registered. Login decides whether a device is allowed in today. These are separate checks on purpose. A phone that was compliant when it registered six months ago may have been rooted since, or may have fallen behind on operating system updates. + +Login enforcement is done through a [conditional authentication]({{base_path}}/guides/authentication/conditional-auth/) script on the sign-in flow of the application. The script has access to the data reported by the device and can decide what to do with it: allow the sign-in, block it, or step up to an additional factor. + +## Enforcement patterns + +Because the decision sits in a script, you can be more nuanced than a simple pass or fail. The following patterns are common: + +- **Hard block** - The device is non-compliant, so refuse the sign-in and tell the user what to fix. + +- **Step up** - The device is non-compliant, so require an additional factor rather than refusing outright. + +- **Sensitive applications only** - Enforce the policy on the finance application but not on the cafeteria menu application. + +- **Grace period** - Warn users for a period before enforcing, so they have time to bring devices into line. + +## Add the script + +To enforce a policy on the login flow of an application: + +1. On the {{product_name}} Console, click **Applications**. + +2. Select the relevant application and go to its **Login Flow** tab. + +3. Add the following script, replacing `Main Policy` with the name of your [device assurance policy]({{base_path}}/guides/device-management/device-assurance-policies/). + + ```js + var onLoginRequest = function(context) { + executeStep(1, { + onSuccess: function(context) { + var failedFields = isDevicePolicyCompliant(context, "Main Policy"); + if (failedFields) { + fail({ + "errorCode": "DEVICE_NON_COMPLIANT", + "errorMessage": "Device policy failed for: " + failedFields + }); + } + } + }); + }; + ``` + +4. Click **Update** to confirm. + +## How it works + +`isDevicePolicyCompliant(context, policyName)` evaluates the named policy against the device that is making the request and returns the fields that failed. When the device satisfies every condition in the rule for its platform, the function returns nothing and the sign-in proceeds. + +The example above passes the failed fields into the error message, so the user is told what to fix rather than being refused without explanation. To step up instead of blocking, call `executeStep` for an additional factor in place of `fail`. + +!!! note + The policy name in the script must match the name of the policy exactly. Since a policy name cannot be changed after creation, the reference stays valid once you have set it. diff --git a/en/includes/guides/device-management/index.md b/en/includes/guides/device-management/index.md new file mode 100644 index 0000000000..f20dba4d28 --- /dev/null +++ b/en/includes/guides/device-management/index.md @@ -0,0 +1,30 @@ +# 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 {{product_name}} once, and from then on it can prove that it is the same device on every request. + +On top of that, you can define device assurance policies that check the security posture of a device — whether it is rooted, whether the screen is locked, whether the disk is encrypted — and block 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 {{product_name}} and gets linked to a user. + +- **Assurance** - How you check, on every sign-in, that the device still meets your security requirements. + +!!! note "Before you begin" + Device registration is only supported in [app-native authentication]({{base_path}}/guides/authentication/app-native-authentication/). Your users must sign in through a native application rather than through a browser redirect. See [Configure device registration]({{base_path}}/guides/device-management/configure-device-registration/) to understand what this means for your rollout. + +## Explore device management + +The guides below start with policies, because a policy is the thing you reference everywhere else. + +- [Device assurance policies]({{base_path}}/guides/device-management/device-assurance-policies/) - Define the conditions a device must meet, one rule per platform. + +- [Device attributes]({{base_path}}/guides/device-management/device-attributes/) - Look up the attributes available on each platform and the values they can take. + +- [Device attestation]({{base_path}}/guides/device-management/device-attestation/) - Verify that a device is genuine using the attestation services of Google and Apple. + +- [Enforce a device policy at login]({{base_path}}/guides/device-management/enforce-device-policy-at-login/) - Check device posture on every sign-in with an adaptive authentication script. + +- [Configure device registration]({{base_path}}/guides/device-management/configure-device-registration/) - Enroll devices through self-registration, invited user registration, or a dedicated registration flow. + +- [View the devices of a user]({{base_path}}/guides/device-management/view-user-devices/) - Review the devices registered against a user account. diff --git a/en/includes/guides/device-management/view-user-devices.md b/en/includes/guides/device-management/view-user-devices.md new file mode 100644 index 0000000000..637cd72488 --- /dev/null +++ b/en/includes/guides/device-management/view-user-devices.md @@ -0,0 +1,11 @@ +# View the devices of a user + +As an administrator, you can review the devices registered against a user account from the {{product_name}} Console. + +1. On the {{product_name}} Console, go to **User Management** > **Users**. + +2. Select the user whose devices you want to review. + +3. Go to the **Devices** tab. + +The tab lists the devices currently registered to that user. Use it to confirm that a user has enrolled a device, or to see how many devices a user has registered before asking them to enroll another one through the [dedicated device registration flow]({{base_path}}/guides/device-management/configure-device-registration/#dedicated-device-registration-flow).