From b5d3b2b975172a9510c04847b0b1d419c0bcd5e0 Mon Sep 17 00:00:00 2001 From: Chris Clare <97486608+chrisclare-okta@users.noreply.github.com> Date: Mon, 5 Jun 2023 16:10:34 -0600 Subject: [PATCH 1/5] OKTA-577368: add new fields to device profile object --- .../docs/reference/api/devices/index.md | 78 ++++++++++++++----- 1 file changed, 58 insertions(+), 20 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index d278c03678b..65d74ad5e4c 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -1151,23 +1151,37 @@ The following diagram shows the state object for a Device: #### Device profile properties -| Property | Type | Description | -| :----------------- | :--------- | :---------------------------------------------------------------------------------------------| -| `displayName` | String | The display name of the device (from 1 through 255 characters) | -| `platform` | String | OS platform of the device. Possible values: `MACOS`, `WINDOWS`, `ANDROID`, `IOS`. | -| `registered` | Boolean | Indicates if the device is registered at Okta | -| `imei` | String | (Optional) International Mobile Equipment Identity of the device (from 15 through 17 numeric characters) | -| `manufacturer` | String | (Optional) Name of the manufacturer of the device (from 0 through 127 characters) | -| `meid` | String | (Optional) Mobile equipment identifier of the device (14 characters) | -| `model` | String | (Optional) Model of the device (127 characters) | -| `osVersion` | String | (Optional) Version of the device OS (127 characters) | -| `serialNumber` | String | (Optional) Serial number of the device (127 characters) | -| `sid` | String | (Optional) Windows Security identifier of the device (256 characters) | -| `udid` | String | (Optional) macOS Unique Device identifier (47 characters) | -| `tpmPublicKeyHash` | String | (Optional) Windows Trusted Platform Module hash value | -| `secureHardwarePresent` | Boolean | (Optional) Indicates if the device contains a secure hardware functionality | - -#### Device profile example +| Property | Type | Description | Applicable Platforms | +| :----------------------- | :--------- | :-----------------------------------------------------------------------------------------------------------------| :---------------------------| +| `displayName` | String | The display name of the device (from 1 through 255 characters) | All | +| `platform` | Enum | OS platform of the device. Possible values: `MACOS`, `WINDOWS`, `ANDROID`, `IOS`. | All | +| `registered` | Boolean | Indicates if the device is registered at Okta | All | +| `diskEncryptionType` | Enum | (Optional) The type of disk encryption on the device. [Possible Values for `diskEncryptionType`](#possible-values-for-diskencryptiontype) | All | +| `imei` | String | (Optional) International Mobile Equipment Identity of the device (from 15 through 17 numeric characters) | All | +| `integrityJailbreak` | Boolean | (Optional) Indicates if the device is jailbroken or rooted | `IOS` and `ANDROID` | +| `manufacturer` | String | (Optional) Name of the manufacturer of the device (from 0 through 127 characters) | All | +| `meid` | String | (Optional) Mobile equipment identifier of the device (14 characters) | All | +| `model` | String | (Optional) Model of the device (127 characters) | All | +| `osVersion` | String | (Optional) Version of the device OS (127 characters) | All | +| `serialNumber` | String | (Optional) Serial number of the device (127 characters) | All | +| `sid` | String | (Optional) Windows Security identifier of the device (256 characters) | All | +| `udid` | String | (Optional) macOS Unique Device identifier (47 characters) | All | +| `tpmPublicKeyHash` | String | (Optional) Windows Trusted Platform Module hash value | All | +| `secureHardwarePresent` | Boolean | (Optional) Indicates if the device contains a secure hardware functionality | All | + +##### Possible Values for `diskEncryptionType` + +| Value | Description | Applicable Platforms | +| :-------------------------- | :--------------------------------------------------------| :---------------------------| +| `NONE` | No encryption has been set | All | +| `FULL` | Disk is fully encrypted | `IOS` and `ANDROID` | +| `USER` | Encryption key is tied to the user or profile | `ANDROID` | +| `ALL_INTERNAL_VOLUMES` | All internal disks are encrypted | `WINDOWS` and `MACOS` | +| `SYSTEM_VOLUME` | Only the system volume is encrypted | `WINDOWS` and `MACOS` | + +**Note:** The following values map to Disk Encryption ON (otherwise OFF): `FULL`, `USER`, `ALL_INTERNAL_VOLUMES` + +#### Device profile examples ```json { @@ -1182,9 +1196,33 @@ The following diagram shows the state object for a Device: "meid": null, "udid": "36A56558-1793-5B3A-8362-ECBAA14EDD2D", "sid": null, - "tpmPublicKeyHash":null, - "registered":true, - "secureHardwarePresent":false + "tpmPublicKeyHash": null, + "registered": true, + "secureHardwarePresent": false, + "diskEncryptionType": null + } +} +``` + +```json +{ + "profile": { + "displayName": "Bob - New Device", + "platform": "IOS", + "manufacturer": "Apple Inc.", + "model": "iPhone 13 Pro Max", + "osVersion": "15.1.1", + "serialNumber": "C02VW333HTDF", + "imei": null, + "integrityJailbreak": , + "meid": null, + "udid": "36A56558-1793-5B3A-8362-ECBAA14EDD2D", + "sid": null, + "tpmPublicKeyHash": null, + "registered": true, + "secureHardwarePresent": false, + "diskEncryptionType": "FULL", + "integrityJailbreak": false } } ``` From 65d58d0c63665bbddd733b4fbf8e74525c1189eb Mon Sep 17 00:00:00 2001 From: Chris Clare <97486608+chrisclare-okta@users.noreply.github.com> Date: Tue, 6 Jun 2023 09:53:48 -0600 Subject: [PATCH 2/5] added screenLockType to response examples --- .../@okta/vuepress-site/docs/reference/api/devices/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index 65d74ad5e4c..0eab6e63f87 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -526,6 +526,7 @@ curl -v -X GET \ "users":[ { "managementStatus": "MANAGED", + "screenLockType": "BIOMETRIC", "created":"2021-10-01T16:52:41.000Z", "user":{ "id":"${userId}", @@ -639,6 +640,7 @@ curl -v -X GET \ { "created":"2021-08-20T17:13:35.000Z", "managementStatus":"NOT_MANAGED", + "screenLockType":"BIOMETRIC", "user":{ "id":"00u17vh0q8ov8IU881d7", "status":"ACTIVE", From 454ddebaadc7c7b9df2fdc2d8c8704e4a5049ad9 Mon Sep 17 00:00:00 2001 From: Chris Clare <97486608+chrisclare-okta@users.noreply.github.com> Date: Tue, 6 Jun 2023 10:47:05 -0600 Subject: [PATCH 3/5] update limit messaging to say recommended 20 instead of max 200 --- .../@okta/vuepress-site/docs/reference/api/devices/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index 0eab6e63f87..7c4cbedca50 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -217,7 +217,7 @@ None | Parameter | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `search` | String | Searches for devices with a supported [filtering](/docs/reference/core-okta-api/#filter) expression for most properties | -| `limit` | Number | Specifies the number of results returned (maximum `200`) | +| `limit` | Number | Specifies the number of results returned (recomended `20`) | | `after` | String | Specifies the pagination cursor for the next page of devices | | `expand=user` | String | Lists associated users for the device in `_embedded` element | From 13f5a85e75569cb2fd92e54c6ce2a957aa17107f Mon Sep 17 00:00:00 2001 From: Chris Clare <97486608+chrisclare-okta@users.noreply.github.com> Date: Fri, 9 Jun 2023 10:17:00 -0600 Subject: [PATCH 4/5] Updating based on PR comments --- .../vuepress-site/docs/reference/api/devices/index.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index 7c4cbedca50..a2999482cbf 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -1155,13 +1155,13 @@ The following diagram shows the state object for a Device: | Property | Type | Description | Applicable Platforms | | :----------------------- | :--------- | :-----------------------------------------------------------------------------------------------------------------| :---------------------------| -| `displayName` | String | The display name of the device (from 1 through 255 characters) | All | +| `displayName` | String | The display name of the device (max 255 chars) | All | | `platform` | Enum | OS platform of the device. Possible values: `MACOS`, `WINDOWS`, `ANDROID`, `IOS`. | All | | `registered` | Boolean | Indicates if the device is registered at Okta | All | -| `diskEncryptionType` | Enum | (Optional) The type of disk encryption on the device. [Possible Values for `diskEncryptionType`](#possible-values-for-diskencryptiontype) | All | -| `imei` | String | (Optional) International Mobile Equipment Identity of the device (from 15 through 17 numeric characters) | All | +| `diskEncryptionType` | Enum | (Optional) The type of disk encryption on the device. See [Possible values for `diskEncryptionType`](#possible-values-for-diskencryptiontype) | All | +| `imei` | String | (Optional) International Mobile Equipment Identity of the device (15-17 numeric chars) | All | | `integrityJailbreak` | Boolean | (Optional) Indicates if the device is jailbroken or rooted | `IOS` and `ANDROID` | -| `manufacturer` | String | (Optional) Name of the manufacturer of the device (from 0 through 127 characters) | All | +| `manufacturer` | String | (Optional) Name of the manufacturer of the device (0-127 chars) | All | | `meid` | String | (Optional) Mobile equipment identifier of the device (14 characters) | All | | `model` | String | (Optional) Model of the device (127 characters) | All | | `osVersion` | String | (Optional) Version of the device OS (127 characters) | All | @@ -1171,7 +1171,7 @@ The following diagram shows the state object for a Device: | `tpmPublicKeyHash` | String | (Optional) Windows Trusted Platform Module hash value | All | | `secureHardwarePresent` | Boolean | (Optional) Indicates if the device contains a secure hardware functionality | All | -##### Possible Values for `diskEncryptionType` +##### Possible values for `diskEncryptionType` | Value | Description | Applicable Platforms | | :-------------------------- | :--------------------------------------------------------| :---------------------------| @@ -1216,7 +1216,6 @@ The following diagram shows the state object for a Device: "osVersion": "15.1.1", "serialNumber": "C02VW333HTDF", "imei": null, - "integrityJailbreak": , "meid": null, "udid": "36A56558-1793-5B3A-8362-ECBAA14EDD2D", "sid": null, From 00c8bff4ea1312e0f9c9746d9de759cc2974b5bb Mon Sep 17 00:00:00 2001 From: Chris Clare <97486608+chrisclare-okta@users.noreply.github.com> Date: Fri, 9 Jun 2023 14:07:45 -0600 Subject: [PATCH 5/5] Updated doc with suggestions --- .../docs/reference/api/devices/index.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index a2999482cbf..1375fd1fe63 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -217,7 +217,7 @@ None | Parameter | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `search` | String | Searches for devices with a supported [filtering](/docs/reference/core-okta-api/#filter) expression for most properties | -| `limit` | Number | Specifies the number of results returned (recomended `20`) | +| `limit` | Number | Specifies the number of results returned (recommended `20`) | | `after` | String | Specifies the pagination cursor for the next page of devices | | `expand=user` | String | Lists associated users for the device in `_embedded` element | @@ -623,6 +623,16 @@ Lists all [Users](/docs/reference/api/users/#user-object) for a Device by `devic Array of [Users](/docs/reference/api/users/#user-object) +##### Device - User attributes + +The following device attributes will be added to each user object in array of users. + +| Property | Type | Description | +| :----------------------- | :--------- | :-----------------------------------------------------------------------------------------------------------------| +| `managementStatus` | ENUM | Management status of the device for the user. Possible values are `NOT_MANAGED` and `MANAGED` | +| `screenLockType` | ENUM | Screen lock type of the device for the user. Possible values are `NONE`, `PASSCODE` and `BIOMETRICS` | + + #### Request example ```bash @@ -1201,7 +1211,7 @@ The following diagram shows the state object for a Device: "tpmPublicKeyHash": null, "registered": true, "secureHardwarePresent": false, - "diskEncryptionType": null + "diskEncryptionType": "ALL_INTERNAL_VOLUMES" } } ```