Keys, KeyTokens, and Preferences
This page documents the GPII data model that is designed based on this document.
Contents
Data Model
The figures below are drawn using entity-relationship diagrams. The arrows used express cardinality, where a single vertical line indicates "at least one", and the crow's foot, "one or more". For example, a Prefs Safe
has one or more GPII Keys
, or in other words, one or more keys can reference the same safe.
This data model assumes the mapping between GPII keys and server URIs are done through other external mechanisms such as DNS.
Future Data Model
Steven Githens' universal pull request for supporting PPT adds the user management feature. It creates the next version of data model.
Document Descriptions
GPII keys
Name | Type | Required or Optional | Description | Default |
---|---|---|---|---|
id
|
String | Required | The value of the key written onto key tokens. | None |
type
|
String | Required | The document type for storing GPII keys. | The value must be "gpiiKey". |
schemaVersion
|
String | Required | The version of the schema that the current document structure corresponds with. | |
prefsSafeId
|
String | Optional | The ID of the preferences safe that the GPII key connects with. Set to null if the GPII key does not have a preferences safe connected. | null |
prefsSetId
|
String | Optional | The key of the preferences set in a preferences safe that the GPII key points to. The identifier matches a key within the contexts block of a preference set. For example, the default prefsSetId is a fixed name "gpii-default".
|
null |
revoked
|
Boolean | Required | Whether this GPII key has been revoked. | false |
revokedReason
|
String | Optional | The revoked reason. | null |
timestampCreated
|
Date | Required | The timestamp when the token is created. | now() |
timestampUpdated
|
Date | Optional | The timestamp when the token is updated. | null |
timestampRevoked
|
Date | Optional | The timestamp when the token is revoked. | null |
Prefs Safes
Name | Type | Required or Optional | Description | Default |
---|---|---|---|---|
id
|
String | Required | The ID of the preferences safe. | None |
type
|
String | Required | The document type for storing preferences safes. | The value must be "prefsSafe". |
schemaVersion
|
String | Required | The version of the schema that the current document structure corresponds with. | |
prefsSafeType
|
enum of ["snapset", "user"] | Required | Indicates whether this preferences safe is allowed to be modified: the ones with "snapset" type are unmodifiable while the ones with "user" type are modifiable. | "user" |
name
|
String | Optional | The user defined name for this preferences safe. A “preference-safe-name and password” pair can potentially be used as a key. | null |
password
|
String | Optional | The user defined password for this preferences safe. A “preference-safe-name and password” pair can potentially be used as a key. | null |
email
|
String | Optional | The user email. | null |
preferences
|
Object | Required | The user preferences. Refer to the "More Document Field Examples and Explanations" section for an example of this field. | null |
timestampCreated
|
Date | Required | The timestamp when the prefs safe is created. | now() |
timestampUpdated
|
Date | Optional | The timestamp when the prefs safe is updated. | null |
Client Credentials
Name | Type | Required or Optional | Description | Default |
---|---|---|---|---|
id
|
String | Required | The ID of the client credential. | None |
type
|
String | Required | The document type for storing client credentials. | The value must be "clientCredential". |
schemaVersion
|
String | Required | The version of the schema that the current document structure corresponds with. | |
clientId
|
String | Required | The client id that this client credential belongs to. | None |
oauth2ClientId
|
String | Required | The unique identifier issued to a registered OAuth2 client by the authorization server. | None |
oauth2ClientSecret
|
String | Required | Confidential shared secret between the client and the authorization server, used to verify the identity of the client. | None |
revoked
|
Boolean | Required | Whether this client credential has been revoked. | false |
revokedReason
|
String | Optional | The revoked reason. | null |
timestampCreated
|
Date | Required | The timestamp when the prefs safe is created. | now() |
timestampRevoked
|
Date | Optional | The timestamp when this client credential is revoked. | null |
GPII App Installation Clients
Name | Type | Required or Optional | Description | Default |
---|---|---|---|---|
id
|
String | Required | The ID of the GPII app installation client. | None |
type
|
String | Required | The document type for storing GPII app installation clients. | The value must be "gpiiAppInstallationClient". |
schemaVersion
|
String | Required | The version of the schema that the current document structure corresponds with. | |
name
|
String | Required | The user provided client name. | null |
userId or gpiiKey
|
String | Optional | The id of the user or the GPII key who creates this client. The intention of this field is to identify the person who manages this client. It's still in question whether this field should record userId or gpiiKey. | null |
computerType
|
enum of ["public", "private", "shared by trusted parties"] | Required | Identify the type of the computer where this GPII app is installed. | None |
timestampCreated
|
Date | Required | The timestamp when the prefs safe is created. | now() |
timestampUpdated
|
Date | Optional | The timestamp when the prefs safe is updated. | null |
GPII App Installation Authorizations
Name | Type | Required or Optional | Description | Default |
---|---|---|---|---|
id
|
String | Required | The ID of this authorization record. | None |
type
|
String | Required | The document type for storing GPII app installation authorizations. | The value must be "gpiiAppInstallationAuthorization". |
schemaVersion
|
String | Required | The version of the schema that the current document structure corresponds with. | |
clientId
|
String | Required | The client id that this authorization is assigned to. | None |
gpiiKey
|
String | Required | The GPII key whose associated user preferences that this authorization is authorized to access. | None |
clientCredentialId
|
String | Required | The client credential id that is used to request this authorization. | None |
accessToken
|
String | Required | The access token used to retrieved the protected user preferences. | None |
revoked
|
Boolean | Required | Whether this authorization has been revoked. | false |
revokedReason
|
String | Optional | The revoked reason. | null |
timestampCreated
|
Date | Required | The timestamp when the authorization is created. | now() |
timestampRevoked
|
Date | Optional | The timestamp when this authorization is revoked. | null |
timestampExpires
|
Date | Required | The timestamp when this authorization expires. | None |
More Document Field Examples and Explanations
prefsSafes.preferences
Object. Required.
- Each preferences set in a preferences safe is keyed by an internally generated id. The default preferences set is keyed by a fixed string "gpii-default".
- Each preferences set contains a field called "name" that is to save the user defined name for this preferences set.
Example:
{ "flat": { "contexts": { "gpii-default": { "name": "Default preferences", // user defined name "preferences": { "http://registry.gpii.net/common/highContrastEnabled": true, "http://registry.gpii.net/common/highContrastTheme": "white-black", "http://registry.gpii.net/common/cursorSize": 0.5 }, "metadata": [ { "type": "required", "scope": [ "http://registry.gpii.net/common/screenReaderTTSEnabled" ], "value": 1024 }, { "type": "priority", "scope": [ "http://registry.gpii.net/applications/com.freedomScientific.jaws" ], "value": 1024 } ] }, "internalID-1": { "name": "subway", // user defined name "preferences": { "http://registry.gpii.net/common/highContrastEnabled": true, "http://registry.gpii.net/common/highContrastTheme": "white-black", "http://registry.gpii.net/common/cursorSize": 0.5 }, "metadata": [ { "type": "required", "scope": [ "http://registry.gpii.net/common/screenReaderTTSEnabled" ], "value": 1024 }, { "type": "priority", "scope": [ "http://registry.gpii.net/applications/com.freedomScientific.jaws" ], "value": 1024 } ], "conditions": [ { "type": "http://registry.gpii.net/conditions/inRange", "min": 400, "inputPath": "http://registry\\.gpii\\.net/common/environment/illuminance" } ] } } } "ISO24751": { "contexts": { "gpii-default": { "name": "Default preferences", "preferences": { "display": { "screenEnhancement": { "fontSize": 24 } }, "control": { "onscreenKeyboard": true } } } } } }
clientCredentials
This document contains all OAuth2 client credentials assigned to all OAuth clients, including: 1. GPII app installation clients; 2. Privileged prefs creator clients; 3. Web prefs consumer clients.
- At any time, each client should only have one active un-revoked client credential in this document.
- TODO: there's an ongoing discussion on whether to stop support privileged prefs creator clients and web prefs consumer clients.
Entities Involved
The information in this section is collected from Keys & KeyToken - Their Role and Use .docx
- Key
- "A unique character string used as a pointer to a set of preferences or to a set of preference sets"
- "Keys can take different forms. But all of them are used to point to a safe where preferences are stored."
- Used as key to Preference Safe (and/or Preference Set?)
- A Key may be created without a Preference Safe and may later be linked
- May contain 3 parts:
- URI of Preferences Server
- Identifier to address Preferences Safe (I don't think this can be a Preferences Safe id directly; I think we will need some indirection if we want multiple Keys to point to a single Safe)
- Identifier to address Preferences Set Context within Safe (default to Context "MAIN")
- [THE STRUCTURE OF KEYS AND WHICH INFORMATION IS STORED WHERE WAS DISCUSSED 2017-09-11 -- THE ABOVE IS NOT FINAL]
- KeyToken
- "Physical device that carries a key"
- Preferences Server
- Many-to-one Mapping of [Key -> Preference Safe]
- More than one Key can map to a single Preference Safe
- Preferences Cloud Safe
- One or more mapping of [Context -> Preference Set]
- Privacy Profile (or in Preference Set?)
- I think we will need a read-only flag to ensure that shared-use snapset KeyTokens cannot be used to edit preferences ("frozen")
- Preferences Set
- "All of the generic and solution-specific preferences"
- "The default preference set is REGULAR".
- "The user can rename the REGULAR preference set to any other name. (the default name is currently “My Regular Preferences”"
- One or more Preferences
- Preference
- "A single preferred setting for a Solution"
- Example:
-
"http://registry.gpii.net/common/magnification": 2.0
-
Notes
- "There are no "accounts" - just safes"
- Some Notes from sgithens on moving login credentials from safes to a key type.
- Enhanced Data Model for NOVA Deployment