PB3 Feature - Optional Authorization

  • Article

Optional Authorization

The current application authorization scheme only supports a single decision by the user - either they grant the application access to all the types the application might ever want to use, or they don't.

This doesn't allow users to test-drive an application by granting access to some data types initially, and then granting access to more types later. Nor does it support an "a la carte" approach, where users can pay to use some modules of applications but not others.

Optional Authorization will provide much more support for these scenarios. It results in the following changes:

  1. Application authors must decide which data types are required, and which ones are optional.
  2. Application authors must provide (as part of the go-live process) a "why" string for each of the data types that the application may want to authorize. This allows the user to have a better understanding of the benefit that they get by granting access.
  3. Applications cannot assume that they have access to a specific data type in a specific user's record - they will need to query the platform to see what access has been granted.
  4. When an application wishes to ask the user for access to an additional type, they need to make the appropriate platform call.

Here are some more details about each of these changes:

Identify required and optional data types

The times when optional data types appear and whether they are checked by default is controlled on a per-data-type basis.

For the first-time auth - the auth that the user currently sees - optional types can behave in three different ways:

  1. By default, an optional data type is not listed on the authorization page.
  2. If the developer sets the DisplayFirstTime flag, the optional authorization will be displayed to the user. This gives the user the opportunity to expand their authorization if they know at the outset that they will be using more than the basic features.
  3. If the developer sets the CheckedFirstTime flag, the optional authorization will be displayed to the user and it will be checked. This encourages the user to grant the optional authorization but indicates that the application will still function without it.

When an app asks a user to grant new access, there are only two options:

  1. The optional authorization is displayed to the user
  2. The optional authorization is displayed and checked. This is controlled with the CheckedByDefault option, which also controls the first time experience if not overriden.

Provide "why" strings

Why strings provide additional information about the benefit of granting an application access to a specific type. For future applications, we will require these strings for all types that the application will ever use, including both optional and required types.

Query to find out whether a data type can be accessed

As mentioned earlier, applications will need to determine what kind of access a record grants on a specific type. This can be done with the following code:

    HealthRecordItemTypePermission SelectRecordQueryPermission(Guid typeId)
    {
        List<Guid> items = new List<Guid>();
        items.Add(typeId);
        return PersonInfo.SelectedRecord.QueryPermissions(items)[0];
    }

and then called with this code:

    HealthRecordItemTypePermission heightPermission = SelectRecordQueryPermission(Height.TypeId);

The returned permission mask will describe what access the application is granted (create/read/update/delete) in both online and offline modes.

Ask the user for access to a new data type

The user is asked to authorize access to a new type (or types) through the appauth redirect. As part of the query string to this redirect, the following information is passed:

  • The application id
  • A list of rule identifiers

The parameter names for the rule identifiers are the series onopt1, onopt2, onopt3, ... and offopt1, offopt2, offopt3, ... , where the number is just sequential so the parameters have different names, and the "on" or "off" part denotes online or offline access.

So, we have something like:

onopt1=<id>&offopt2=<id>

The ids are defined when the application authorization is done as part of the "go live" process. There is currently no way for the application to query the platform for a list of these identifiers, though we do hope to add that ability in the future.

Here's an example of using optional authorization.

    string TargetQuery = “appid=11111111-1111-1111-1111-111111111111&onopt1=name1&onopt2=name2”;
    HealthServicePage ServicePage = new HealthServicePage();
    ServicePage.RedirectToShellUrl(“APPAUTH”, TargetQuery);