Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

OKTA-577368: add new fields to device profile object #4182

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

OKTA-577368: add new fields to device profile object #4182

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b5d3b2b
OKTA-577368: add new fields to device profile object
chrisclare-okta Jun 5, 2023
65d58d0
added screenLockType to response examples
chrisclare-okta Jun 6, 2023
454ddeb
update limit messaging to say recommended 20 instead of max 200
chrisclare-okta Jun 6, 2023
13f5a85
Updating based on PR comments
chrisclare-okta Jun 9, 2023
00c8bff
Updated doc with suggestions
chrisclare-okta Jun 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 70 additions & 21 deletions packages/@okta/vuepress-site/docs/reference/api/devices/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (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 |

Expand Down Expand Up @@ -526,6 +526,7 @@ curl -v -X GET \
"users":[
{
"managementStatus": "MANAGED",
"screenLockType": "BIOMETRIC",
"created":"2021-10-01T16:52:41.000Z",
"user":{
"id":"${userId}",
Expand Down Expand Up @@ -622,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
Expand All @@ -639,6 +650,7 @@ curl -v -X GET \
{
"created":"2021-08-20T17:13:35.000Z",
"managementStatus":"NOT_MANAGED",
"screenLockType":"BIOMETRIC",
"user":{
"id":"00u17vh0q8ov8IU881d7",
"status":"ACTIVE",
Expand Down Expand Up @@ -1151,23 +1163,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 (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. 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 (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 |
| `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`

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please add a section here for the possible values for ScreenLockType, similar to diskEncryptionType?

Copy link
Contributor Author

@chrisclare-okta chrisclare-okta Jun 9, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can add that, however I wasn't clear where to add them. There is no "possible value" description for managementStatus either.

Should I add them both in this page and appended it to the Response description where it says the description returns an array of users? or should I add it to the user object here

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. Please don't update the user object.
Feel free to add managementStatus possible values as well
Suggesting the new header as Device - User attributes for these properties

#### Device profile examples

```json
{
Expand All @@ -1182,9 +1208,32 @@ 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": "ALL_INTERNAL_VOLUMES"
}
}
```

```json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need 2 examples if the only difference is that the second one has integrityJailbreak while the first one does not? Can we clump it to 1?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could, but one is a device profile for MACOS and another is IOS. iOS can have different properties so wanted to express that in an example.

Copy link
Contributor Author

@chrisclare-okta chrisclare-okta Jun 9, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thoughts?

CC @brentschaus-okta

{
"profile": {
"displayName": "Bob - New Device",
"platform": "IOS",
"manufacturer": "Apple Inc.",
"model": "iPhone 13 Pro Max",
"osVersion": "15.1.1",
"serialNumber": "C02VW333HTDF",
"imei": null,
"meid": null,
"udid": "36A56558-1793-5B3A-8362-ECBAA14EDD2D",
"sid": null,
"tpmPublicKeyHash": null,
"registered": true,
"secureHardwarePresent": false,
"diskEncryptionType": "FULL",
"integrityJailbreak": false
}
}
```
Expand Down