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.

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.

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.

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.

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.

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

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.

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.

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.

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:

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

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: