Difference between revisions of "Enhanced Data Model for NOVA"

From wiki.gpii
Jump to: navigation, search
Line 52: Line 52:
 
2. The point i) in [https://issues.gpii.net/browse/GPII-3719 the GPII-3719 JIRA] says: "That the new OAuth grant type should be in effect for sessions secured by access tokens granted to clients presenting a matching machine secret/client credentials". Seems to me no data model change is required for this point. It would be helpful to discuss about this at reviewing this document.
 
2. The point i) in [https://issues.gpii.net/browse/GPII-3719 the GPII-3719 JIRA] says: "That the new OAuth grant type should be in effect for sessions secured by access tokens granted to clients presenting a matching machine secret/client credentials". Seems to me no data model change is required for this point. It would be helpful to discuss about this at reviewing this document.
  
''Answer'': From the same discussion on May 8, 2019, we will explore another option that is, rather than adding a special OAuth grant type for NOVA, the existing grant type could be reused to accommodate both NOVA use case and current use case for libraries and AJCs by checking the existence of "allowedIPBlocks", "allowedPrefsToWrite" or the flag of "isCreatePrefsSafeAllowed". These fields will only exist for NOVA and with "isCreatePrefsSafeAllowed === true".
+
''Answer'': From the same discussion on May 8, 2019, we will explore another option that is, rather than adding a special OAuth grant type for NOVA, the existing grant type could be reused to accommodate both NOVA use case and current use case for libraries and AJCs by either checking the existence of new fields ("allowedIPBlocks", "allowedPrefsToWrite", "isCreatePrefsSafeAllowed") or the boolean value of "isCreatePrefsSafeAllowed === true". These fields will only exist for NOVA and with "isCreatePrefsSafeAllowed === true".
  
  

Revision as of 16:13, 8 May 2019

This page documents the enhanced data model for the final NOVA deployment. The content is for discussion and reviews.

Data Model

The enhanced data model adds 3 fields in 2 document types. These new fields are marked with light-red background.

GPII data model NOVA.png

Example of a New Client Credentials document

{
    "_id": "clientCredential-1",
    "type": "clientCredential",
    "schemaVersion": "0.1",
    "clientId": "gpiiAppInstallationClient-1",
    "oauth2ClientId": "oauth2ClientId-for-NOVA",
    "oauth2ClientSecret": "oauth2ClientSecret-for-NOVA",
    "allowedIPBlocks": [
        "125.19.23.0/24",          // IPv4 block
        "2001:cdba::3257:9652",    // IPv6 block
        "62.230.58.1"              // IP string
    ],
    "allowedPrefsToWrite": [
        // common registry settings
        "http://registry.gpii.net/common/language",
        "http://registry.gpii.net/common/DPIScale",
        "http://registry.gpii.net/common/highContrast/enabled",
        "http://registry.gpii.net/common/selfVoicing/enabled",
        // application specific settings
        "http://registry.gpii.net/applications/com.microsoft.windows.mouseSettings"
    ],
    "revoked": false,
    "revokedReason": null,
    "timestampCreated": "2017-11-21T18:11:22.101Z",
    "timestampRevoked": null
}

Note: A npm module for ip range check: https://www.npmjs.com/package/ip-range-check

Questions

1. The new field "gpiiAppInstallationAuthorization.assignedIP" is to record the IP assigned to a particular access token. This IP must be the same with the IP that /settings GET (or PUT) requests using this access token are sent from. This is to ensure it is the same computer that requests the access token and uses this access token. Is this second verification to ensure it's the same computer using this access token necessary?

Answer: From discussion on May 8, 2019, it's decided:

(1) The extra verification on /settings GET/PUT handlers is unnecessary;

(2) There should be a flag to allow the creation of prefs safe.

These decisions result in 2 changes on the data model: (1) remove "assignedIP" field from "GpiiAppInstallationAuthorization" document type; (2) Add a new field "isCreatePrefsSafeAllowed" in "ClientCredential" document type.


2. The point i) in the GPII-3719 JIRA says: "That the new OAuth grant type should be in effect for sessions secured by access tokens granted to clients presenting a matching machine secret/client credentials". Seems to me no data model change is required for this point. It would be helpful to discuss about this at reviewing this document.

Answer: From the same discussion on May 8, 2019, we will explore another option that is, rather than adding a special OAuth grant type for NOVA, the existing grant type could be reused to accommodate both NOVA use case and current use case for libraries and AJCs by either checking the existence of new fields ("allowedIPBlocks", "allowedPrefsToWrite", "isCreatePrefsSafeAllowed") or the boolean value of "isCreatePrefsSafeAllowed === true". These fields will only exist for NOVA and with "isCreatePrefsSafeAllowed === true".


3. Discuss the timing of making the actual code work with the data model versus adding schema validation. Who is doing what, and when? Do we need schemas for the current data model? For how long?

Answer: The same author of the code who requires the validation should learn and write the schema validation part.


4. Sync up the use of "settings" and "preferences" keywords. Tony's JIRA comment refers to "prefsSafe.preferences" field as "prefsSafe.settings".

Pros

Helps to distinguish "prefsSafe.preferences" with another "preferences" path down in its own structure. An example of a typical prefsSafe document that has 2 "preferences" paths:

{
    "_id": "prefsSafe-GPII-270-rbmm-demo",
    "type": "prefsSafe",
    "schemaVersion": "0.1",
    "prefsSafeType": "snapset",
    "name": "GPII-270-rbmm-demo",
    "email": null,
    "preferences": {
        "flat": {
            "contexts": {
                "gpii-default": {
                    "name": "Default preferences",
                    "preferences": {
                        "http://registry.gpii.net/common/matchMakerType": "ruleBased",
                        "http://registry.gpii.net/common/fontSize": 24,
                        "http://registry.gpii.net/common/foregroundColor": "white",
                        "http://registry.gpii.net/common/backgroundColor": "black",
                        "http://registry.gpii.net/common/fontFaceFontName": [
                            "Comic Sans"
                        ],
                        "http://registry.gpii.net/common/fontFaceGenericFontFace": "sans serif",
                        "http://registry.gpii.net/common/magnification": 2,
                        "http://registry.gpii.net/common/tracking": "mouse",
                        "http://registry.gpii.net/common/speechRate": 42,
                        "http://registry.gpii.net/common/trackingTTS": "mouse",
                        "http://registry.gpii.net/common/speakTutorialMessages": true,
                        "http://registry.gpii.net/common/keyEcho": true,
                        "http://registry.gpii.net/common/wordEcho": true,
                        "http://registry.gpii.net/common/announceCapitals": false,
                        "http://registry.gpii.net/common/screenReaderBrailleOutput": false,
                        "http://registry.gpii.net/common/punctuationVerbosity": "some",
                        "http://registry.gpii.net/common/readingUnit": "word",
                        "http://registry.gpii.net/common/auditoryOutLanguage": "GR",
                        "http://registry.gpii.net/common/screenReaderTTS/enabled": true,
                        "http://registry.gpii.net/common/pitch": 0.4,
                        "http://registry.gpii.net/common/volumeTTS": 0.5,
                        "http://registry.gpii.net/applications/com.microsoft.windows.highContrast": {
                            "HighContrastOn": {
                                "path": "pvParam.dwFlags.HCF_HIGHCONTRASTON",
                                "value": true
                            }
                        }
                    }
                }
            }
        }
    },
    "timestampCreated": "2019-03-15T13:58:06.037Z",
    "timestampUpdated": null
}

Cons

Just to my understanding (I'm not sure if it's correct), "preferences" is used for generic common or application specific terms such as:

{
    "http://registry.gpii.net/common/matchMakerType": "ruleBased",
    "http://registry.gpii.net/common/fontSize": 24,
    "http://registry.gpii.net/common/foregroundColor": "white",
    "http://registry.gpii.net/common/backgroundColor": "black"
}

"settings" is after preferences go thru the matchmaking process and are converted into actual application settings that will be applied to computers. An example of a setting is to set the screen reader speech rate to 200 words per minute.