HIN und OAuth2-Integration

HIN ermöglicht die Nutzung von Applikationen, die über den HIN Access Control Service (ACS) mittels OAuth2 an die HIN-Plattform angebunden sind. Dazu muss der ACS-Applikationsanbieter die Nutzung von OAuth bei HIN freigeben (E-Mail an info@hin.ch). HIN unterstützt die OAuth-Flows «Authorization Code» und «Client Credentials».

Authorization Code Flow

Die zugreifende Drittapplikation (OAuth: Client), die im Namen des Anwenders auf eine andere Applikation zugreifen möchte, leitet den Anwender auf eine geschützte HIN-Applikation (apps.hin.ch) weiter, an welcher er sich authentisieren muss. Apps.hin.ch generiert ein temporäres Token (OAuth: Auth Code) für den Bezug des Zugriff-Tokens (OAuth: Access Token). Der Auth Code wird über den Browser des Anwenders an die Drittapplikation weitergegeben. Hierfür gibt es zwei Varianten:

• Variante a): Anzeigen des Auth Code in der apps.hin.ch-Webapplikation: Der Auth Code wird in der Webapplikation angezeigt und per Copy/Paste in die Drittapplikation übertragen.

• Variante b): Übermittlung über Query Parameter: Bei der Weiterleitung des Anwenders an apps.hin.ch gibt die Drittapplikation bereits mit, auf welchen Endpunkt (OAuth: Redirect_URI) er den Auth Code möchte.

Mit dem Auth Code kann die Drittapplikation das Access Token beziehen. Mit dem Access Token kann die Drittapplikation dann auf die entsprechende Applikation über oauth2.<bestehendeURL> zugreifen. Access Token können entweder für eine URL oder für eine Gruppe von URLs gültig sein.

Client Credentials Flow

Der Client Credentials Flow wurde speziell für Machine-to-Machine-Anwendungsfälle konstruiert. Im Client Credentials Flow entfällt der Bezug des Auth Codes und somit die Interaktion mit einem Endbenutzer. Im Gegensatz zum Authorization Code Flow ist das ausgestellte Access Token jedoch auch nur für einen spezifischen, vorkonfigurierten Benutzer gültig. Der Client Credentials Flow eignet sich somit nicht, wenn ein Zugriff im Namen eines Endbenutzers erfolgen soll.

Weiterführende Informationen

Weitere Informationen und Antworten finden Sie auf der Support-Website von HIN: https://support.hin.ch/

1.0 OAuth 2.0 mit HIN e-ID

Dieses Kapitel bietet eine umfassende Übersicht über die OAuth 2.0-Implementierung mit HIN e-ID. Hier finden Sie alle notwendigen Informationen, Spezifikationen und Begriffserklärungen, um OAuth 2.0 mit HIN e-ID erfolgreich zu implementieren.

In den folgenden Abschnitten werden die verschiedenen Aspekte von OAuth 2.0 mit HIN e-ID erläutert, einschliesslich der unterstützten Flows, der Authentifizierung und Autorisierung, sowie der relevanten Begriffe und Konzepte.

1.1 Spezifikationen

Die folgenden Spezifikationen gelten für OAuth2 im HIN-System:

1.2 GLOSSAR

1.3 OAuth2-Downloads

Die OAuth2-Vorlage für Postman kann unter folgendem Link heruntergeladen werden: https://download.hin.ch/acs/oAuth_Vorlage.postman_collection.json.zip

2.1 OAuth 2.0 Authorization Code Flow mit HIN e-ID

Das Diagramm illustriert den OAuth 2.0 Authorization Code Flow zwischen dem HIN e-ID (CLIENT) und dem Access Control Service (ACS) unter Verwendung des HIN Identity Providers (IDP).

Schritt-für-Schritt-Erklärung:

1. Authorization Request an HIN (apps.hin.ch): Der HIN e-ID (CLIENT) sendet einen GET Request an HIN (apps.hin.ch), um den Autorisierungsprozess zu initiieren.
2. Authorization Code von HIN (apps.hin.ch): HIN (apps.hin.ch) antwortet mit einem Authorization Code, der an den HIN e-ID (CLIENT) zurückgesendet wird.
3. Token Request mit Authorization Code an HIN (IDP): Der HIN e-ID (CLIENT) sendet einen POST Request mit dem erhaltenen Authorization Code an HIN (IDP), um das Access Token zu erhalten.
4. Access Token von HIN (IDP): HIN (IDP) validiert den Authorization Code und antwortet mit einem Access Token, das an den HIN e-ID (CLIENT) gesendet wird.
5. Zugriff auf geschützte Ressourcen mit Access Token: Der HIN e-ID (CLIENT) verwendet das Access Token, um einen GET Request an den ACS zu senden und auf die geschützten Ressourcen zuzugreifen.
6. Datenübertragung zwischen ACS und HIN e-ID (CLIENT): Der ACS validiert das Access Token und ermöglicht den Zugriff auf die angeforderten Daten, die anschliessend an den HIN e-ID (CLIENT) übertragen werden.

2.1 OAuth 2.0 Authorization Code Flow mit HIN e-ID

Das Diagramm illustriert den OAuth 2.0 Authorization Code Flow zwischen dem HIN e-ID (CLIENT) und dem Access Control Service (ACS) unter Verwendung des HIN Identity Providers (IDP).

Schritt-für-Schritt-Erklärung:

1. Authorization Request an HIN (apps.hin.ch): Der HIN e-ID (CLIENT) sendet einen GET Request an HIN (apps.hin.ch), um den Autorisierungsprozess zu initiieren.
2. Authorization Code von HIN (apps.hin.ch): HIN (apps.hin.ch) antwortet mit einem Authorization Code, der an den HIN e-ID (CLIENT) zurückgesendet wird.
3. Token Request mit Authorization Code an HIN (IDP): Der HIN e-ID (CLIENT) sendet einen POST Request mit dem erhaltenen Authorization Code an HIN (IDP), um das Access Token zu erhalten.
4. Access Token von HIN (IDP): HIN (IDP) validiert den Authorization Code und antwortet mit einem Access Token, das an den HIN e-ID (CLIENT) gesendet wird.
5. Zugriff auf geschützte Ressourcen mit Access Token: Der HIN e-ID (CLIENT) verwendet das Access Token, um einen GET Request an den ACS zu senden und auf die geschützten Ressourcen zuzugreifen.
6. Datenübertragung zwischen ACS und HIN e-ID (CLIENT): Der ACS validiert das Access Token und ermöglicht den Zugriff auf die angeforderten Daten, die anschliessend an den HIN e-ID (CLIENT) übertragen werden.

2.2 OAuth 2.0 Client Credentials Flow für Machine-to-Machine-Kommunikation

Das Diagramm illustriert den OAuth 2.0 Client Credentials Flow zwischen dem ACS (Drittsoftware) und dem ACS (Eine andere Drittsoftware) unter Verwendung des HIN Identity Providers (IDP).

Schritt-für-Schritt-Erklärung:

1. POST Request mit Client Credentials an HIN (IDP): Der ACS (Drittsoftware) sendet einen POST Request mit seinen Client Credentials an HIN (IDP), um ein Access Token zu erhalten. Hinweis: Im Client Credentials Flow entfällt der Schritt der Auth Code-Anforderung.
2. Access Token von HIN (IDP): HIN (IDP) validiert die Client Credentials und antwortet mit einem Access Token, das an den ACS (Drittsoftware) gesendet wird.
3. Zugriff auf geschützte Ressourcen mit Access Token: Der ACS (Drittsoftware) verwendet das Access Token, um einen GET Request an den ACS (Eine andere Drittsoftware) zu senden und auf die geschützten Ressourcen zuzugreifen.
4. Datenübertragung zwischen ACS (Eine andere Drittsoftware) und ACS (Drittsoftware): Der ACS (Eine andere Drittsoftware) validiert das Access Token und ermöglicht den Zugriff auf die angeforderten Daten, die anschliessend an den ACS (Drittsoftware) übertragen werden.

3.0 Anforderungen für OAuth 2.0 mit HIN e-ID

Dieses Kapitel beschreibt die Anforderungen, die für eine erfolgreiche Implementierung von OAuth 2.0 mit HIN e-ID erforderlich sind. Hier finden Sie Informationen zu den technischen, sicherheitsrelevanten und funktionalen Anforderungen, die erfüllt werden müssen, um OAuth 2.0 mit HIN e-ID zu implementieren.

In den folgenden Abschnitten werden die verschiedenen Anforderungen im Detail erläutert.

3.1 Voraussetzungen

3.2 Zwei OAuth2 Flows - Vorteile / Nachteile

Client Credentials Flow

Authorization Code Flow

4.0 Der Auth Code

Der Authorization Code Flow ist ein wichtiger Bestandteil der OAuth 2.0-Implementierung mit HIN e-ID. Dieser Flow ermöglicht es Drittapplikationen, im Namen einer HIN-Identität auf geschützte Ressourcen zuzugreifen. In den folgenden Abschnitten wird der Authorization Code Flow im Detail erläutert, einschliesslich des Ablaufs, des Bezugs von Auth-Codes und Access-Tokens sowie der relevanten Status-Codes.

4.1 Ablauf

1. Eine Drittapplikation möchte im Namen einer HIN-Identität auf eine HIN-geschützte Ressource (ACS-Applikation) zugreifen.

2. Wenn in der Drittapplikation kein Token für die entsprechende HIN-Identität vorhanden ist, muss der Browser an apps.hin.ch weitergeleitet werden. Der zugreifende Anwender muss sich beim Zugriff auf apps.hin.ch mittels Zwei-Faktor-Authentisierung (bspw. HIN-Client) anmelden. Dem Anwender wird in der Webapplikation ein Auth-Code dargestellt.

3. Der Auth-Code wird vom Anwender in die Drittapplikation übertragen. Dazu werden verschiedene Mechanismen verwendet (siehe Kapitel «Bezug und Verwendung Auth Code»):

   • Copy/Paste des Auth-Codes oder Fotografieren eines QR-Codes
   • direkte Übermittlung über https oder Protocol Handler

4. Mit dem Auth-Code kann die Drittapplikation das Access-Token beziehen.

5. Mit dem Access-Token ist der Zugriff auf die geschützte Ressource im Namen der HIN-Identität des Anwenders möglich.

4.2 Bezug von Auth-Codes

Der Auth-Code ist ein OTP (One-Time-Password), das für den Bezug des Access-Tokens verwendet wird und zehn Minuten gültig ist. Der Bezug kann über zwei Varianten erfolgen:

4.2.1 Variante a): Anzeigen des Auth-Codes in der Webapplikation

Auf apps.hin.ch können Auth-Codes für den Bezug des Access-Tokens generiert werden. Für den OAuth-Service wird ein separates Register bereitgestellt.

Beim Zugriff auf apps.hin.ch wird standardmässig das erste Register («HIN-Mail») angezeigt. Um das Ganze für den Anwender zu vereinfachen, können die Auth-Codes über einen Direktlink bezogen werden: http://apps.hin.ch/#app=HinCredMgrOAuth;tokenGroup=<TokenGruppe>

Der Wert nach tokenGroup= ist je nach Ziel-Applikation unterschiedlich und kann bei HIN angefragt werden.

4.2.2 Variante b): Übermittlung über Query-Parameter

Bei dieser Variante wird der Auth-Code an eine definierte Redirect-URI übermittelt. Die anwendende Person bestätigt dies durch den Klick auf «Ja, Zugriff erlauben». Die Redirect-URI wird über die aufgerufene URL mitgegeben:

http://apps.hin.ch/REST/v1/OAuth/GetAuthCode/<TokenGruppe>?response_type=code&client_id=<client_id>&redirect_uri=<Redirect_URI>&state=<state>

Beispiel-Request für die Applikation «ACS-Applikation»: https://www.hin.ch/?state=teststate&code=qdoWMwRNHnn9wDNynbMxytwahEGNXBqtipQhZXLF

5.0 Bezug von Access-Tokens

Einleitung

Der Bezug von Access-Tokens ist ein wichtiger Schritt im OAuth 2.0-Flow. Mit dem erhaltenen Auth-Code kann die Drittapplikation ein Access-Token beziehen, das für den effektiven Zugriff auf die Applikation verwendet wird.

Beispiel:

curl --location 'https://oauth2.covercard.hin.ch/covercard/servlet/ch.ofac.ca.covercard.CaValidationHorizontale?type=XML&langue=3&carte=<krankenkassen_karten_nr>&ReturnType=42a' --header 'Authorization: Bearer <covercard_Access Token>'

5.1 Request Access-Token

Mit dem erhaltenen Auth-Code kann das Access-Token bezogen werden. Der Bezug erfolgt mittels eines POST auf oauth2.hin.ch/REST/v1/OAuth/GetAccessToken, dabei werden die Parameter als form-data übermittelt (Content-Type: application/x-www-form-urlencoded):

POST https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken

• grant_type=authorization_code&
• code=AUTH_CODE&
• redirect_uri=REDIRECT_URI&
• client_id=CLIENT_ID&
• client_secret=CLIENT_SECRET

Die Redirect-URI muss übereinstimmen mit derjenigen, die beim Bezug des Auth-Codes verwendet wurde. Bitte beachten Sie, dass der Parameter client_secret je nach Konfiguration nicht notwendig ist.

Bezug eines Access-Tokens mit Curl (Auth-Code apps.hin.ch):

curl -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept:application/json' --data 'grant_type=authorization_code&redirect_uri=&code=<CODE>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>' https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken

Bezug eines Access-Tokens mit Curl (Auth-Code mit Redirect-URI):

curl -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept:application/json' --data 'grant_type=authorization_code&redirect_uri=<REDIRECT_URI>&code=<CODE>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>' https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken

Parameter

5.2 Response Access-Token

Das Access-Token wird in Form von einem JSON zurückgeliefert:

{ 
"access_token":"TOKEN", 
"expires_in":3600, 
"hin_id": "example", 
"token_type": "Bearer" 
}

"Expires_in" definiert in Sekunden, wann das Token ausläuft. Bitte beachten Sie, dass ein Token jederzeit durch den Identitätsbesitzer gelöscht werden kann. Somit kann ein Token auch vor Ablauf der "expires_in"-Frist ungültig werden.

Wird ein Access-Token mit einem ungültigen Auth-Code angefragt, wird ein Fehler zurückgegeben:

{ "error":"invalid_request" }

Hat die Drittapplikation das Token erhalten, ist der Zugriff auf den Ressource-Server möglich. Dazu wird das Token als Basic-Auth-Header mitgegeben. Der Basic-Auth-Header wird gemäss OAuth-Standard "Bearer" angefügt.

Status-Codes

6.0 Client Credentials Flow

Einleitung

Der Client Credentials Flow ist ein OAuth 2.0-Flow, der es Applikationsanbietern ermöglicht, auf geschützte Ressourcen zuzugreifen, ohne dass eine Benutzerinteraktion erforderlich ist. Dieser Flow ist insbesondere geeignet für Machine-to-Machine-Kommunikation.

Status-Codes

6.1 Ablauf

1. Applikationsanbieter, die den Client Credentials Flow nutzen möchten, melden sich beim HIN-Support (support@hin.ch).
2. Der HIN-Support erstellt eine HIN-ID vom Typ «Device» für den Applikationsanbieter.
3. Der Applikationsanbieter erhält die Credentials zur HIN-ID und nimmt diese in Betrieb (https://servicecenter.hin.ch/id-activation).
4. Um die client_id und das client_secret zu erhalten, meldet sich der Applikationsanbieter mit der HIN-ID bei https://apps.hin.ch/#app=ClientCredentials an. Im gleichen Zug muss eine Notification-E-Mail-Adresse für den Ablauf der Credentials definiert werden.
5. Anschliessend kann der Applikationsanbieter über die Calls, die im Kapitel Calls definiert sind, ein Access-Token beziehen.

6.1.2 Bezug Client Credentials

Der Applikationsanbieter meldet sich mit seiner HIN-ID (siehe Ablauf Schritt 2) bei https://apps.hin.ch/#app=ClientCredentials an.

Funktionen der Webapplikation

6.2 Bezug von Access-Tokens

Beim Bezug des Access-Tokens muss definiert werden, für welche Token-Gruppe das Token gültig sein soll. Die zu verwendende client_id wurde bei Schritt 3 im Ablauf definiert. Das client_secret wurde in Schritt 4 bezogen. Die bezogenen Access-Tokens sind immer für die HIN-ID gültig, welche unter Schritt 2 im Ablauf generiert wurde.

6.3 Request Access-Token

Bezug eines Access-Tokens mit Curl:

curl -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode "grant_type=client_credentials" --data-urlencode "client_id=<CLIENT ID>" --data-urlencode "client_secret=<SECRET>" https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken/ACS-Applikation

POST https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken/ACS-Applikation

• grant_type=client_credentials&
• client_id=CLIENT_ID&
• client_secret=CLIENT_SECRET

6.4 Response Access-Token

Das Access-Token wird in Form von einem JSON zurückgeliefert:

{ 
"access_token": "<ACCESS TOKEN>", 
"expires_in": 2592000, 
"hin_id": "hinid", 
"refresh_token": "<REFRESH TOKEN>", 
"token_type": "Bearer" 
}

7.0 Refresh Token

Einleitung

HIN kann auf Basis der Client-ID die Verfügbarkeit von "Refresh Token" steuern. Ein Refresh-Token wird verwendet, um ohne Benutzer-Interaktion ein neues Access-Token zu beziehen.

7.1 Verwendung von Refresh Token

Ist das Refresh-Token für eine Client-ID aktiviert, sieht die Antwort auf den initialen Bezug des Access-Tokens folgendermassen aus:

{
  "access_token":"ACCESSTOKEN",
  "expires_in":3600,
  "hin_id": "clientid",
  "refresh_token": "REFRESHTOKEN",
  "token_type": "Bearer"
}

Beispiel-Code für die Verwendung von Refresh Token in Python

import requests
import time

def get_new_access_token(refresh_token, client_id, client_secret):
    url = "https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken"
    
    payload = f'grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}'
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
    }

    response = requests.post(url, headers=headers, data=payload)

    if response.status_code == 200:
        token_data = response.json()
        new_access_token = token_data['access_token']
        new_refresh_token = token_data.get('refresh_token', refresh_token)
        return new_access_token, new_refresh_token
    else:
        return None, refresh_token

def main():
    refresh_token = '<REFRESH_TOKEN>'  # Dein initiales Refresh Token
    client_id = '<CLIENT_ID>'  # Deine Client-ID
    client_secret = '<CLIENT_SECRET>'  # Dein Client-Secret

    while True:
        new_access_token, refresh_token = get_new_access_token(refresh_token, client_id, client_secret)
        
        if new_access_token:
            # Hier kannst du den Zugriff mit dem neuen Access Token fortsetzen
        else:
            # Fehler beim Erneuern des Tokens. Bitte überprüfen Sie die Anmeldedaten.
            break
        
        time.sleep(3600)  # z.B. 1 Stunde warten, bevor das Token wieder erneuert wird

if __name__ == "__main__":
    main()

7.2 Request Refresh Token

Nach Ablauf des Access-Tokens kann das Refresh-Token noch 7 Tage für die Erneuerung verwendet werden. Anschliessend verfällt es und es muss ein neues Access-Token durch den Anwender generiert werden.

POST https://oauth2.hin.ch/REST/v1/OAuth/GetAccessToken

• grant_type=refresh_token&
• refresh_token=REFRESH_TOKEN&
• client_id=CLIENT_ID&
• client_secret=CLIENT_SECRET

Parameter

7.3 Response Refresh Token

Neben dem neuen Access-Token erhält man wiederum ein Refresh-Token, welches wieder für die Erneuerung verwendet werden kann.

Beispiel-Response:

{
  "access_token": "<ACCESS TOKEN>",
  "expires_in": 3600,
  "hin_id": "hinid",
  "refresh_token": "<REFRESH TOKEN>",
  "token_type": "Bearer"
}

8.0 Token Check

Einleitung

Mit diesem Call kann die Gültigkeit des OAuth 2.0-Tokens verifiziert werden.

Status-Codes

• 200 OK: Token ist gültig
• Andere Status-Codes: Token ist ungültig oder ein Fehler ist aufgetreten

Hinweis

Ein Token kann jederzeit durch Aktionen seitens des Users oder der HIN invalidiert werden. Die Informationen sind genau im Zeitpunkt der Abfrage gültig.

8.1 Request Token Check

POST https://oauth2.hin.ch/REST/v1/OAuth/GetTokenInfo

Header

• X-HIN-ORIGIN-IP: IP-Adresse des Aufrufers
• Content-Type: application/json

Body

{
  "AccessToken": "{zu_pruefendes_Token}",
  "client_id": "{client_id der Organisation}"
}

8.2 Response Token Check

Wurde das Token in der Datenbank gefunden, wird angezeigt, ob es gültig ist, wie lange die gesamte Gültigkeitsdauer ist, wie lange es noch lebt und wann die Gültigkeit voraussichtlich ausläuft.

Beispiel-Response

{
  "active": 1,
  "description": "Applikation E-Rezept Service",
  "expiration": 1751723481,
  "expires_in": 1392610,
  "expires_on": "2025-07-05T13:51:21Z",
  "name": "HIN"
}

8.3 Beispiel-Code

curl --location 'https://oauth2.hin.ch/REST/v1/OAuth/GetTokenInfo' \
--header 'X-HIN-ORIGIN-IP: {IP_Adress_of_caller}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "AccessToken": "{zu_pruefendes_Token}",
    "client_id": "{client_id der Organisation}"
}'