Skip to main content

Leveraging Personal Community APIs from a Mobile Application




1. Overview

As part of a larger digital front door strategy, organizations may provide thier users with a mobile application.  Organizations building their own mobile applications may wish to make direct use of Personal Community APIs to provide Personal Community functionality to their users.  Calling the APIs directly allows a site to maintain control over the user experience for the broader application.  This document outlines the setup and workflows needed in both Personal Community and the calling mobile application to support direct API access.

2. Requirements

Sites wishing to leverage the Personal Community APIs from their own mobile application must meet the following requirements:

  • Mobile application authenticates its user over OAuth 2.0 and can act as an identity provider (IdP) to Personal Community.
  • Personal Community must be configured as a service provider to the IdP following the external credentials setup.
  • Mobile application users must be enrolled in Personal Community following the external credentials workflow.
  • Mobile application user must exist in the associated Unified Care Record prior to Personal Community enrollment.
  • The IdP must be able to provider Personal Community with an identifier that can be used to match the user to an existing patient in the Unified Care Record.
  • Mobile applications will be required to call an API to register their application within Personal Community.
  • Personal Community will return a cookie that will be used by the mobile application for all subsequent calls.  Personal Community maintains its own session for the user once they are authorized, this session is integral to how the Personal Community application works.

3. Configuring Personal Community to Support External Credentials

This section describes how to set up an external identity provider for enrollment. 

3.1. Supported Access Token Types for Sign-In

Personal Community can act as a service provider to an external identity provider using OAuth 2.0.  Personal Community is designed to support the following access token types:

  1. ID Token
  2. JSON web token (JWT)
  3. Opaque token with token introspection

While configuring Personal Community to act as a service provider, organizations will need to choose which of the access token types to use during sign-in and enrollment.

3.2.  Enrollment Using External Credentials

With external credentials, members enroll by authenticating themselves with the external identity provider. 

After successful authentication, Personal Community matches the member’s identity to a patient’s health record in the Unified Care Record. This results in a member account being created.

The external identity provider should provide an OpenID Connect (OIDC) userInfo endpoint to be used during the enrollment. This endpoint is required when using ID Token and Opaque token authentication, and is strongly recommended to be used with JWT as well.

The OIDC userInfo endpoint will provide Personal Community the unique identifier for the patient that will be used to identify the member within the Unified Care Record. Additionally, the userInfo should provide Personal Community with additional demographic information about the member.  This information can be used to populate the Personal Community demographics for the member.

If an external identity provider is using a JWT and not providing an OIDC userInfo endpoint, the JWT will need to provide a unique identifier to Personal Community that can be used to match the patient in the Unified Care Record.  If the JWT can provide additional demographic information about the member, that will be used to populate the Personal Community demographics during enrollment.  If it cannot, demographic information from the Unified Care Record will be used.

3.2.1. Creating an Enrollment Configuration Class

You must use an enrollment configuration class to determine what information, given by the external identity provider, is used to match members with a patient’s health record in the Unified Care Record. This is required for successful enrollment. Optionally, this class also contains the condition(s) to be met for member enrollment to be permitted.

To create a site-specific enrollment configuration class:

  1. Create a new class that extends   HSPortal.OAuth2.Client.IdentifierEnrollmentConfiguration .
  2. Override the OAuth2AccessTokenType   to select your access token type. By default this is set to IdToken. Other available options are JWT and Opaque.
  3. Override the following methods in order to implement the required workflow behavior for your site:

    • RetrieveMRNFromUserInfo   Required - Determines which identifier to use from the u serInfo   object from the OIDC userInfo endpoint or the JWT object that Personal Community receives from the external system. This identifier is used to match the member’s identity to a patient’s health record in the Unified Care Record. For example, in the   HSPortal.OAuth2.Client.Vendor.NHSLogin.v1.NHSLoginEnrollmentConfiguration   class, this is defined as: pUserInfoObject."nhs_number"

    • IsEnrollmentPermitted   Optional - Determines the condition(s) to be met for member enrollment to be permitted. By default, all authenticated members are permitted for enrollment. This method uses the   UserInfo   object that Personal Community receives from the external system as input. For example:

       Set tIsPermitted = 
           ''$ListFind(tNHSNumberAllowList,pUserInfoObject."nhs_number")
       Quit tIsPermitted
      

      where tNHSNumberAllowList is a list of MRNs for members you permit for enrollment.

    • UpdateEnrollmentData   Optional - Updates a patient’s demographic data by populating data from the external system via the u serInfo   object from the OIDC userInfo endpoint or the JWT object  that Personal Community receives from the external system. Demographic data that is not available from the external system will be populated from existing data for the patient from the UCR.

      The method signature is as follows:

      Method UpdateEnrollmentData(
                           pUserInfoObject As %RegisteredObject,
                           pScope As %String,
                           ByRef pEnrollmentData As %Zen.proxyObject)
      {}
      

      This method maps property values from   pUserInfoObject   to property values in   pEnrollmentData , based on the OpenID scope specified by   pScope .

      By default, the following property values are populated from the UserInfo object:

      pEnrollmentData Property Name pUserInfoObject Property Name
      pEnrollmentData.FirstName pUserInfoObject."given_name"
      pEnrollmentData.LastName pUserInfoObject."family_name"
      pEnrollmentData.DateOfBirth pUserInfoObject."birthdate"
      pEnrollmentData.Email pUserInfoObject."email"

      You can choose from the following property values to populate from the   UserInfo   object:

      • FirstName

      • MiddleName

      • LastName

      • DateOfBirth

      • Sex

      • Address1

      • Address2

      • City

      • State

      • Zipcode

      • Email

  4. Override the   PATIENTLOOKUPTYPE   parameter, which is used to distinguish enrollment configurations.

  5. Compile your new class.

3.3. Creating an SSL/TLS Configuration on Your Personal Community Instance

To create an SSL/TLS configuration on your instance of Personal Community:

  1. Log into the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role and switch to the Personal Community namespace.

  2. Go to the   SSL/TLS Configurations   page ( System Administration   >   Security   >   SSL/TLS Configurations ) and select   Create New Configuration .

  3. Enter a name of your choice for the configuration.

  4. Make sure that the configuration is enabled: the   Enabled   checkbox should already be selected.

  5. For   Type , make sure that   Client   is selected.

  6. For   Server certificate verification , make sure that   None   is selected.

  7. For   Protocols , make sure that   TLSv1.1   and   TLSv1.2   are selected.

  8. Select the   Save   button to save the new configuration.

IMPORTANT

If your installation of Personal Community is mirrored, you must complete these same steps on both members of the mirror.


3.4. Creating an X.509 Credential Set for OpenID Connect

To create an X.509 credential set:

  1. Determine which public certificate and private key will be used for OpenID Connect, as specified by the policies your organization has adopted regarding public key cryptography, especially private keys.

  2. Copy the source files for the public certificate and private key to the machine that hosts the Personal Community installation.

  3. Log in to the Management Portal for Personal Community as an InterSystems IRIS user who has the   %Manager   role.

  4. Navigate to   System Administration   >   Security   >   X.509 Credentials .

  5. Create and save a credential set   as indicated below:

    • Alias   — An identifying name of your choice

    • File containing X.509 certificate   — The full pathname of the public certificate file

    • File containing associated private key   — The full pathname of the private key file


3.5. Setting up an OAuth 2.0 Client Server

You must set up an OAuth 2.0 client server with your external identity provider. To do so:

  1. Log into the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role and switch to the Personal Community namespace.

  2. Go to the   OAuth 2.0 Client   page ( System Administration   >   Security  >   OAuth 2.0   >   Client ) and select   Create Server Description .

  3. Select   Manual   for manual setup.

  4. You will need to obtain the following information from your external identity provider:

    • Endpoints   — you will need the URLs for:

      • the Issuer endpoint.

      • the Authorization endpoint.

        Note

        There is a case where patients do not have to authenticate with the external identity provider. This occurs when the patient signs in with external credentials, signs out, and signs back in immediately without closing the browser. Because the patient has an active session with the external identity provider, they are not prompted to authenticate again.

        You may wish to enforce that a patient is  always  prompted to authenticate with the external identity provider. Provided that your external identity provider supports this, this can be enforced by adding  ?prompt=login   to the end of the authorization endpoint.

      • the Token endpoint.

      • the Userinfo endpoint.

      • the JWKS endpoint.

    • Credentials   — you will need a valid username and password for the OAuth authorization service, referred to as the OAuth client ID and client secret.

    • Scope   — the following scope, at a minimum, is required for enrollment to function properly: openid profile

  5. With the given information, configure accordingly.

3.6. Updating the Home Page

Note

You must obtain SVG files from your external identity provider for sign-in button that will appear on the Personal Community home page.


To configure the Personal Community public application home page for enrollment and sign-in with external credentials, you must make the following InterSystems IRIS for Health™ Terminal call in your Personal Community namespace:

set status = ##class(HSPortal.OAuth2.Client).CreateOrUpdateOAuth2Client(
                       pApplicationName,
                       pLoginFilename,
                       pEnrollFilename,
                       pLoginModalFilename,
                       pEnrollModalFilename,
                       pIssuer)

where:

  • pApplicationName   — the name of the OAuth 2.0 client server you created.

  • pLoginFilename   — the path to an SVG file for sign-in with external credentials.

  • pEnrollFilename   — the path to an SVG file for enrollment with external credentials.

  • pLoginModalFilename   — the path to an SVG file for the sign-in modal.

  • pEnrollModalFilename   — the path to an SVG file for the enrollment modal.

  • pIssuer   — optional - the custom issuer used to validate the Access Token and ID Token. By default, this is set as the value stored in  Issuer endpoint  in your  OAuth 2.0 Client  configuration.

3.7. Creating or Updating an External Enrollment Configuration

To establish enrollment with your external identity provider, call the  CreateOrUpdateEnrollmentConfiguration() method in your enrollment configuration class with the following values for parameters:

  • pApplicationName  — the name of the OAuth 2.0 client server you created.
  • pAssigningAuthorityName  — the name of the assigning authority, as defined in the Unified Care Record.
  • pUse  — the identifier type, as defined in the Unified Care Record.
  • pOAuth2Audience –  Optional. The OAuth2 Audience. OAuth2 Audience (aud) verifies if the access token is intended for a specific recipient or audience, ensuring that the token is used by the right party or application.
  • pOAuth2AccessTokenType —  the access token type selected in your enrollment configuration class. For existing implementations, this will be IdToken.

4. Calling APIs from your Mobile Application

4.1. API Documentation

You can find the REST API documentation at   http:// PersonalCommunity_hostname : port / <workbench-web-application> / HSPortal.Workbench.UI.APIDocumentation.zen .

4.2. API Workflows

In order for APIs from Personal Community to be used, the mobile application user must have an associated Personal Community account.  This account can be created and accessed in real time from the mobile application following the workflows defined below.

4.2.1. Enrollment 

In order for subsequent APIs to be used, the mobile application user must first be enrolled within Personal Community to create a Personal Community account.

The high level workflow is as follows:


Patient Workflow Mobile Application Identity Provider Personal Community Unified Care Record
1. Patient accesses the mobile application Patient is redirected to sign in User authentication occurs

2. Patient accesses the area of the mobile application that will be populated via Personal Community APIs

Application calls the following Personal Community API to register the application

POST

/auth/sp/oauth/2.0/authorizationURL/ {applicationName} ?isPrivateDevice= {isPrivateDevice} &isEnroll= {isEnroll} &isMobileApp= {isMobileApp }


Session ID and Application name are stored within Personal Community

Session cookie is returned


3.

Application calls to sign the patient into Personal Community

POST

/auth/login

passing in the session cookie


Login response returns AttemptToEnroll = 1 indicating the patient needs to enroll
4.

Application calls to get the Personal Community Terms of Use

GET

/users/0/termsOfUse

passing in the session cookie


Personal Community returns the terms of use
5.

OPTIONAL

(If cleared by organization's legal team to infer acceptance)

Terms of use are presented to the patient to accept





6.

OPTIONAL

(If cleared by organization's legal team to infer acceptance)

Patient accepts the terms of use

Application calls to enroll the patient in Personal Community passing in the accepted terms of use

POST

/users/sp/oauth/2.0/enroll

passing in the session cookie and with the payload including information about the terms (from step 4).  For example

{
   "TermsAccepted": {
      "ID": 2,
      "HashBase64": "5fhrZuU6YWvvzZwnkVWTyXxcvfQ="
    }
 }





7.

Returns access token Calls to obtain the access token
8.


Validates token based on access token type
9.

Returns the userInfo object Calls the OIDC userInfo endpoint to obtain information about the patient
10.


Calls the Unified Care Record passing in the identifier for the patient Uniquely matches patient
11.


Patient is enrolled and activated

Success is returned to the mobile application


12.
Subsequent API calls may now be made to Personal Community passing in the session cookie


13. Patient obtains information from these subsequent calls




4.2.2. Sign-In

In order for subsequent APIs to be used, the mobile application user must be signed into Personal Community.

The high level workflow is as follows:


Patient Workflow Mobile Application Identity Provider Personal Community
1. Patient accesses the mobile application Patient is redirected to sign in User authentication occurs
2. Patient accesses the area of the mobile application that will be populated via Personal Community APIs

Application calls the following Personal Community API  to register the application

/auth/sp/oauth/2.0/authorizationURL/ {applicationName} ?isPrivateDevice= {isPrivateDevice} &isEnroll= {isEnroll} &isMobileApp= {isMobileApp }


Session ID and Application name are stored within Personal Community

Session cookie returned

3.

Application calls to sign the patient into Personal Community

/auth/login 

using the session cookie



4.

Returns access token Calls to obtain the access token
5.


Validates token based on access token type
6.


Success is returned to the mobile application

7.
Subsequent API calls may now be made to Personal Community using the session cookie

8. Patient obtains information from these subsequent calls