OAuth2 Documentation for Providers of Third-Party Applications

Introduction

HIN enables the use of applications connected to the HIN platform via the HIN Access Control Service (ACS) using OAuth2. OAuth2 is an authorization framework that allows applications to access certain resources without the user having to disclose their login credentials. This document explains the basics of OAuth2 at HIN and introduces the two supported flows - Authorization Code Flow and Client Credentials Flow.

What is it about?

OAuth2 is needed to control access to certain applications and resources. An example of this is the service Covercard, which uses the Authorization Code Flow because it is assumed that the user can read the data on their insurance card. Another example is the E-Prescription, which also uses the Authorization Code Flow to ensure that only authorized users can access the prescriptions.

The Two OAuth Flows

HIN supports two different OAuth flows: the Authorization Code Flow and the Client Credentials Flow.

Authorization Code Flow

The Authorization Code Flow is suitable when a user wants to use an application that needs to access another application. The user is redirected to the HIN application (apps.hin.ch), where they must authenticate. The HIN application generates a temporary token (Auth Code), which is passed to the third-party application. With this Auth Code, the third-party application can obtain an Access Token, with which it can access the corresponding application.

Examples of using the Authorization Code Flow are the services Covercard and E-Prescription. For both applications, it is important that the user is authenticated before accessing the corresponding resources.

There are two ways to pass the Auth Code to the third-party application:

• Displaying the Auth Code in the apps.hin.ch web application: The Auth Code is displayed in the web application and transferred to the third-party application via copy/paste.
• Transmission via Query Parameters: When redirecting the user to apps.hin.ch, the third-party application already specifies the endpoint (Redirect_URI) to which it wants the Auth Code.

Client Credentials Flow

The Client Credentials Flow is suitable for machine-to-machine use cases where no user is involved. The Client Credentials Flow omits obtaining the Auth Code and thus the interaction with an end user. However, the issued Access Token is only valid for a specific, pre-configured user.

Further Information regarding E-Prescription

Further information can be found on the following webpage: E-Prescription