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:
- ID Token
- JSON web token (JWT)
- 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:
- Create a new class that extends HSPortal.OAuth2.Client.IdentifierEnrollmentConfiguration .
- Override the OAuth2AccessTokenType to select your access token type. By default this is set to IdToken. Other available options are JWT and Opaque.
-
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
-
-
-
Override the PATIENTLOOKUPTYPE parameter, which is used to distinguish enrollment configurations.
-
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:
-
Log into the Management Portal for Personal Community as a user with the %EnsRole_Administrator role and switch to the Personal Community namespace.
-
Go to the SSL/TLS Configurations page ( System Administration > Security > SSL/TLS Configurations ) and select Create New Configuration .
-
Enter a name of your choice for the configuration.
-
Make sure that the configuration is enabled: the Enabled checkbox should already be selected.
-
For Type , make sure that Client is selected.
-
For Server certificate verification , make sure that None is selected.
-
For Protocols , make sure that TLSv1.1 and TLSv1.2 are selected.
-
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:
-
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.
-
Copy the source files for the public certificate and private key to the machine that hosts the Personal Community installation.
-
Log in to the Management Portal for Personal Community as an InterSystems IRIS user who has the
%Manager
role. -
Navigate to System Administration > Security > X.509 Credentials .
-
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:
-
Log into the Management Portal for Personal Community as a user with the %EnsRole_Administrator role and switch to the Personal Community namespace.
-
Go to the OAuth 2.0 Client page ( System Administration > Security > OAuth 2.0 > Client ) and select Create Server Description .
-
Select Manual for manual setup.
-
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
-
- 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 |
|
|
|