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 client instance where the page resides invokes the GetCredentials() method in the ZAUTHENTICATE routine.

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

   • If an access token is found, the OAuth Authentication workflow is complete, and the "bearer token found" workflow proceeds. This workflow is described in a separate diagram later in this chapter. See the links below the diagram.

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

4. With no token found, 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 to the GetUser() method of HS.OAuth2.Server.Session.

6. The OAuth server checks if there is an existing SSO session for the user:

   • If there is no existing SSO session, the user is redirected to the HealthShare Login Page. This triggers the Univesal Login Page workflow, which is described in a separate diagram later in this chapter (see the links below the diagram). When that workflow is complete, control returns to the next step in this workflow.

   • Alternatively, if a browser cookie indicates an active SSO session, there is no need to redirect to the login page.

7. In either case, the next step is that the OAuth server invokes the ValidateUser() callback in HS.Local.OAuth2.Server.Validate.

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

   1. In this alternative workflow, 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.

9. Now, whether the standard or the delegated authentication workflow was followed, the OAuth server invokes the DisplayPermissions() callback in HS.Local.OAuth2.Server.Authenticate.

10. The OAuth server invokes the AfterAuthenticate() callback in HS.Local.OAuth2.Server.Authenticate.

11. The class HS.OAuth2.Server.Session calls either the Login() or Update() method to either establish a new SSO session or extend an active session.

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

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

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

15. The OAuth client on the client 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 client 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. This time, however, an access token is found, so control passes to the "bearer token found" workflow. This workflow is described in a separate diagram later in this chapter (see the links below the diagram). The bearer token found workflow will result in providing the user access to the requested user interface page.