Introduction

Objectif du document

OAuth2 est un système qui aide les applications à accéder de manière sécurisée aux données d'un utilisateur sans que celui-ci n'ait à partager directement son mot de passe. Il existe deux flux importants pour le système HIN : le flux d'autorisation (Grant Flow) et le flux d'identification (Credential Flow).

Le flux d'autorisation est utilisé lorsqu'un utilisateur se connecte à une application et autorise cette dernière à accéder à ses données. Un exemple est la connexion à une application via un compte Google, où l'application est autorisée à accéder aux e-mails de l'utilisateur. L'application reçoit un code d'autorisation qu'elle échange ensuite contre un jeton d'accès (Access Token). Ce jeton accorde à l'application l'autorisation d'accéder aux données de l'utilisateur. Dans notre cas, "Filebox" est un exemple d'application adaptée au flux d'autorisation. Ici, il est important de savoir quel utilisateur fait la demande, car le contenu de Filebox varie selon l'utilisateur.

Le flux d'identification fonctionne différemment, car il n'y a pas d'utilisateur qui doit donner son accord. L'application demande simplement un jeton d'accès pour accéder à une API ou à d'autres données. Cela se produit généralement lorsque deux applications/machines doivent communiquer directement entre elles sans qu'un utilisateur ne soit impliqué dans le processus. Par exemple, le service Covercard serait approprié pour le flux d'identification, car l'identité de l'utilisateur n'a pas d'importance.

Spécifications

Téléchargements OAuth2

Postman Collection

Informations complémentaires

Vous trouverez des réponses supplémentaires sur https://support.hin.ch/.

2.1 Grant Flow

2.1 Credential Flow

3.1 Prérequis

3.2 Deux flux OAuth2 - Avantages / Inconvénients

Flux d'identification client (Client Credentials Flow)

Flux de code d'autorisation (Authorization Code Flow)

Remarque : Les avantages et les inconvénients sont présentés séparément pour chaque flux OAuth2 pour clarifier leurs caractéristiques respectives.

4.1 Le jeton d'authentification (Auth Token)

Introduction

Avant d'accéder à des données ou à des fonctions protégées, il est nécessaire dans les deux cas - aussi bien dans le flux d'identification client (CC Flow) que dans le flux de code d'autorisation (Grant Flow) - d'obtenir d'abord un jeton d'authentification (Auth Token). Le processus est similaire dans les deux cas : le jeton d'authentification sert de preuve que l'utilisateur ou l'application est autorisé à accéder aux ressources demandées.

Dans le flux d'identification client (CC Flow, uniquement variante A), il n'y a qu'une seule possibilité d'obtenir le jeton d'authentification, contrairement au flux de code d'autorisation (Grant Flow, variantes A ou B), où il existe deux variantes. Une fois que le jeton d'authentification est obtenu, il peut être utilisé pour exécuter les requêtes API nécessaires et obtenir le jeton d'accès (Access Token). La principale différence entre les deux flux réside dans la manière dont le jeton est obtenu, mais dans les deux cas, le jeton doit être valide avant l'accès aux données.

4.2 L'obtention du jeton d'authentification (Auth Token)

Dans le flux de code d'autorisation (Grant Flow), il existe deux possibilités pour obtenir le jeton d'authentification. Pour le flux d'identification client (Credential Flow), seule la variante A est applicable.

Dans la durée de validité, le jeton doit être utilisé dans une requête POST pour obtenir les données demandées. Pour l'utilisateur, cela signifie généralement saisir le jeton dans un champ prévu à cet effet, fourni par les développeurs. Cependant, avec la variante B, cela peut également être automatisé.

4.3 Variante A

Procédure :

1. L'utilisateur se connecte à son compte (HIN e-ID) et navigue ensuite vers apps.hin.ch.
2. Là, il sélectionne l'option pour la délégation d'identité et choisit le jeton approprié.
3. Le jeton est copié et affiché. Ce jeton est une longue chaîne de caractères.
4. Dans cette variante, l'utilisateur ou le technicien doit récupérer le jeton d'authentification via le navigateur Web. Le jeton n'est valide que pendant 10 minutes, de la même manière qu'un mot de passe à usage unique (OTP).

Lien : http://apps.hin.ch/#app=HinCredMgrOAuth;tokenGroup=

4.4 Variante B

Procédure

1. Construire le lien : en utilisant les paramètres HIN.
2. Authentification de l'utilisateur : l'utilisateur s'authentifie via e-ID et reçoit une fenêtre contextuelle avec des options Oui et Non.
3. Authentification et redirection : après une connexion réussie, l'utilisateur est redirigé vers une URL (qui doit être communiquée à HIN) qui contient le jeton d'authentification en tant que paramètre d'URL. Par exemple : https://example.com/callback?Code=iwdjoijwiw90dj9j2odij2oijwoidwd
4. Extraction du jeton dans le backend : le serveur reçoit la requête et extrait le jeton d'authentification de l'URL. Le jeton se trouve dans le paramètre "Code" (par exemple, Code=iwdjoijwiw90dj9j2odij2oijwoidwd).
5. Obtention du jeton d'accès HIN.

Lien à construire : http://apps.hin.ch/REST/v1/OAuth/GetAuthCode/?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<CREDIRECT_URI_ENCODED>&state=

Lorsque l'on ouvre le lien dans le navigateur

Dans cette variante, le jeton d'authentification est fourni directement via une redirection. Après une connexion réussie (Oui), il y a une redirection automatique vers une autre page, que nous devons enregistrer dans notre backend, où le jeton d'authentification est passé en tant que paramètre dans l'URL. Le jeton pourrait ressembler à ceci : Code=iwdjoijwiw90dj9j2odij2oijwoidwd.

Traitement dans le backend

Le serveur reçoit cette URL et extrait le jeton du paramètre d'URL. Dans ce cas, il s'agit du paramètre Code, qui contient le jeton iwdjoijwiw90dj9j2odij2oijwoidwd.

Exemple avec Flask

from flask import request

@app.route('/callback')
def callback():
    # Extraction du paramètre 'code' de l'URL
    auth_token = request.args.get('code')

    # Traitement ultérieur du jeton...

5.1 La requête POST

Dans le contexte d'OAuth 2.0, la requête POST désigne la requête HTTP qu'un client envoie au serveur d'autorisation pour obtenir un jeton d'accès. Après que l'utilisateur a autorisé l'accès à ses données, le client reçoit un code d'autorisation qu'il envoie dans une requête POST, accompagné d'autres informations requises (telles que l'ID client, le secret client et l'URI de redirection), au point de terminaison de jeton du serveur. En réponse, le client reçoit un jeton d'accès qui lui permet d'accéder aux ressources protégées de l'utilisateur.

Exemple de requête POST

[
  {"key": "grant_type", "value": "authorization_code", "type": "text"},
  {"key": "code", "value": "AUTHCODE", "type": "text"},
  {"key": "redirect_uri", "value": "http://localhost", "type": "text"},
  {"key": "client_id", "value": "ch.YourID", "type": "text"},
  {"key": "client_secret", "value": "YourSecret", "type": "text"}
]

Requête POST

POST https://oauth2.hin.ch/REST/v1/getoAuthToken
  grant_type=authorization_code&
  code=AUTH_CODE&
  redirect_uri=REDIRECT_URI&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET

6.1 Introduction à l'obtention du jeton d'accès

Un jeton d'accès est nécessaire pour accéder à des données ou à des fonctions protégées d'une application. Pour obtenir ce jeton, il faut d'abord envoyer le jeton d'authentification (Auth Token) au serveur via une requête POST. Le jeton d'authentification sert de preuve d'authentification que l'utilisateur ou l'application est autorisé à obtenir un jeton d'accès. Après l'envoi de la requête POST, le serveur répond avec une réponse contenant le jeton d'accès.

Avec ce jeton d'accès, il est possible d'envoyer une requête GET à l'application ou à l'API souhaitée. Dans cette requête, le jeton d'accès est transmis en tant que preuve d'accès aux ressources protégées. L'application vérifie le jeton d'accès et, si celui-ci est valide, elle répond avec les données ou les informations demandées. Le jeton d'accès est donc une clé qui permet un accès sécurisé et autorisé aux ressources d'une application.

Il est important de noter que les jetons d'accès ne sont généralement valides que pour une période limitée, ce qui nécessite des renouvellements réguliers pour continuer à accéder aux données protégées.

6.2 Obtention du client_secret pour la requête Curl - CC

Lors de l'obtention du jeton d'accès, il est nécessaire de définir pour quelle groupe de jetons le jeton sera valide. Le client_secret doit être récupéré sur apps.hin.ch, contrairement au flux de code d'autorisation (Grant Flow) qui doit être défini par HIN. Le jeton d'authentification est récupéré de la même manière que pour la variante A sur apps.hin.ch. L'onglet n'apparaît qu'après l'envoi initial d'une requête incorrecte, c'est-à-dire avec un secret incorrect.

Obtention de jetons d'accès à l'aide de Curl

La requête Curl suivante peut être utilisée pour obtenir un jeton d'accès :

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-Applikatio

Réponse

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

6.3 Obtention du client_secret pour la requête Curl - GF

Obtention d'un jeton d'accès avec Curl sans redirection (AuthCode apps.hin.ch)

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

Obtention d'un jeton d'accès avec Curl (AuthCode avec URI de redirection)

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

Réponse

{
  "access_token": "RsT5OjbzRn430zqMLgV3Ia",
  "expires_in": 3600,
  "hin_id": "cmuster",
  "token_type": "Bearer"
}

7.1 Accès aux applications HIN protégées avec un jeton d'accès

Introduction

Avec un jeton d'accès, il est possible d'envoyer une requête GET à une application ou à une API pour accéder à des données protégées. Le jeton d'accès est transmis dans la requête pour garantir que la demande provient d'une source autorisée. Une fois que l'application a vérifié le jeton, elle fournit les données demandées si le jeton est valide. Le jeton d'accès garantit ainsi que seuls les utilisateurs ou les applications autorisés ont accès aux informations protégées.

7.2 Utilisation

Accès avec un jeton d'accès via Curl

Les paramètres exacts doivent être spécifiés par le fournisseur de l'application. Voici des indications générales :

curl --header 'Authorization: Bearer <Access Token>' https://<oauth2.application.hin.ch>

Exemple avec Covercard

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>'

Jeton de rafraîchissement : Maintien de l'accès aux applications et services

Introduction

Un jeton de rafraîchissement est utilisé pour maintenir l'accès à une application ou à un service sans que l'utilisateur ait besoin de se reconnecter à chaque fois. Après l'expiration d'un jeton d'accès, le jeton de rafraîchissement peut être utilisé pour obtenir un nouveau jeton d'accès sans que l'utilisateur n'ait à saisir à nouveau ses informations de connexion. Cela permet de maintenir une connexion sécurisée et conviviale à l'application sans nécessiter de nouveaux processus de connexion constants.

Processus

Après que l'utilisateur s'est connecté avec succès à l'application, le client reçoit un jeton d'accès et un jeton de rafraîchissement. Le jeton d'accès a une durée de validité limitée, tandis que le jeton de rafraîchissement reste valide plus longtemps. Lorsque le jeton d'accès expire, le client envoie une requête POST au point de terminaison de jeton du serveur d'autorisation. Dans cette requête, le client transmet le jeton de rafraîchissement ainsi que l'ID client et le secret client. Le serveur vérifie la validité du jeton de rafraîchissement et, si tout est correct, il émet un nouveau jeton d'accès. Ce nouveau jeton peut ensuite être utilisé pour continuer à accéder aux ressources protégées sans que l'utilisateur ait besoin de se reconnecter.

Exemple de code pour un jeton de rafraîchissement en Python

import requests
import time

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

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

    print(response.text)

    if response.status_code == 200:
        token_data = response.json()
        new_access_token = token_data['access_token']
        # Optionnel : Renvoyer un nouveau jeton de rafraîchissement s'il est présent
        new_refresh_token = token_data.get('refresh_token', refresh_token)
        return new_access_token, new_refresh_token
    else:
        print(f"Erreur lors de la récupération du jeton : {response.status_code} - {response.text}")
        return None, refresh_token

# Exemple de boucle qui renouvelle régulièrement le jeton d'accès
def main():
    refresh_token = 'rteqr4'  # Votre jeton de rafraîchissement initial
    client_secret = 'votre_client_secret'  # Votre secret client

    while True:
        # Ici viendrait le code pour utiliser le jeton d'accès
        print("Utilisation du jeton d'accès pour accéder aux ressources...")
        
        # Obtenir un nouveau jeton d'accès
        new_access_token, refresh_token = get_new_access_token(refresh_token, client_secret)
        
        if new_access_token:
            print(f"Nouveau jeton d'accès obtenu : {new_access_token}")
            # Ici, vous pouvez continuer à utiliser le nouveau jeton d'accès
        else:
            print("Erreur lors du renouvellement du jeton. Veuillez vérifier les informations de connexion.")
            break  # Arrêter la boucle si le jeton n'a pas pu être renouvelé
        
        # Délai d'attente pour renouveler régulièrement le jeton d'accès
        time.sleep(3600)  # Par exemple, attendre 1 heure avant de renouveler à nouveau le jeton

if __name__ == "__main__":
    main()