OAuth Authentication Workflow Diagram Text Description

1. On any instance in the federation, a user requests access to a HealthShare user interface page.

2. The local instance invokes the GetCredentials method in the ZAUTHENTICATE routine.

3. Then the local instance invokes the OnGetCredentials callback in HS.Local.ZAUTHENTICATE. Note that this callback should not be implemented when using OAuth:

   • If no access token is found, then the local instance redirects the user to the OAuth server.

   • If an access token is found, then the "token found" workflow proceeds, which is described later.

4. The OAuth server invokes the BeforeAuthenticate callback in HS.Local.OAuth2.Server.Authenticate.

5. The OAuth server invokes the DelegatedAuthentication callback in HS.Local.OAuth2.Server.Authenticate:

   • If the callback returns a redirect URL, then the "delegated authentication" workflow proceeds, which is described later.

   • If the callback does not return a redirect URL, which is the standard workflow, then the OAuth server redirects the user to the HealthShare Login Page, where the user enters credentials. Note that a separate password reset workflow may occur here if password reset is enabled. The password reset workflow is described in a separate diagram later in this chapter.

6. Once the user enters credentials on the login page, the OAuth server sends the authentication request to the HealthShare Registry in an AuthenticateAuthorize message. The workflow at the Registry is described in a separate diagram later in this chapter.

7. The Registry returns to the OAuth server a username and a set of roles for the user. These may have come from the HealthShare user/clinician registry or an external source like LDAP.

8. The OAuth server stores the username and roles in a local variable:

   • If two-factor authentication is not enabled, then the OAuth server invokes the ValidateUser callback in HS.Local.OAuth2.Server.Validate.

   • If two-factor authentication is enabled, then the OAuth server kicks off the two-factor workflow on the Registry before invoking the ValidateUser callback in HS.Local.OAuth2.Server.Validate. The two-factor workflow is shown in a separate diagram later in the chapter.

9. The OAuth server invokes the GenerateAccessToken callback in HS.Local.OAuth2.Server.Generate.

10. The OAuth server constructs and stores a JSON Web Token, or JWT, with the necessary claims from the username and roles.

11. If the earlier DelegatedAuthentication callback returned a redirect URL, then the delegated authentication workflow is followed rather than the standard OAuth workflow:

    1. Instead of displaying the HealthShare Login Page, the OAuth server redirects to a third party identity provider.

    2. The third party identity provider authenticates the user and obtains roles.

    3. The OAuth server then invokes the ValidateDelegatedAuthentication callback in HS.Local.OAuth2.Server.Validate, which should construct and store a JWT with the necessary claims.

12. Now, whether using the standard or delegated authentication workflow, the OAuth server invokes the DisplayPermissions callback in HS.Local.OAuth2.Server.Authenticate.

13. Then the OAuth server invokes the AfterAuthenticate callback in HS.Local.OAuth2.Server.Authenticate.

14. Now the OAuth server returns an authorization code to the OAuth client on the local instance where the user originally tried to access the HealthShare user interface page.

15. The OAuth client on the local instance sends the code back to the OAuth server in order to exchange it for an access token.

16. The OAuth server passes the access token back to the user interface page that was originally requested.

17. Now the local instance invokes the GetCredentials method in the ZAUTHENTICATE routine again, which again calls the OnGetCredentials callback in HS.Local.ZAUTHENTICATE, but this time with an access token.

18. The local instance sets the access token as a password, but only as a mechanism to pass it along through the workflow.

19. The local instance invokes the Main method in the ZAUTHENTICATE routine.

20. Then the local instance invokes the OnZAUTHENTICATE callback in HS.Local.ZAUTHENTICATE:

    • If the callback directly sets the username and roles, then the local instance invokes the OnAfterProperties callback in HS.Local.ZAUTHENTICATE.

    • If the callback does not set the username and roles, which is the standard workflow, then the local instance validates the access token and extracts the claims and uses them to set the username and roles. The local instance then invokes the OnAfterProperties callback in HS.Local.ZAUTHENTICATE.

21. Now, in either case, the local instance provides the user access to the page.