Azure AD
Configuration d'Azure AD afin de permettre l'authentification depuis une application AppScho
Ce document décrit la procédure à suivre pour un établissement scolaire afin de créer et de fournir à AppScho les accès nécessaire pour utiliser les comptes Office 365 de l'établissement comme source d'authentification pour ses étudiants.
Si votre implémentation est une instance d'AD FS (Active Directory Federation Services), veuillez plutôt vous référer au document spécifique ci-dessous.
Le concept de cette procédure est de créer une application OAuth2 correspondant à AppScho sur votre portail Azure.
Rendez-vous sur votre portail Azure avec un compte administrateur du domaine
Cliquez sur la section Azure Active Directory, puis sur App registrations
Créez une nouvelle application en cliquant sur New application registration
Remplissez le formulaire de la sorte
Name : AppScho
Application type : Web app / API
Sign-on URL : <votre site institutionnel>
Sur la page de détails de votre application, notez la valeur de votre Application ID (par exemple, c28cfd46-698a-406b-9b6a-62f61e3a55fd)
Cliquez sur Reply URLs dans le panneaux de droite, et ajoutez l'URL fournie par AppScho
Cliquez sur Keys et remplissez une ligne vide du tableau avec les valeurs suivantes :
Name : AppScho
Expires : Never (voir note ci-dessous)
Cliquez sur Save et notez la valeur du secret qui ne s'affichera qu'une seule fois.
Il semblerait que Microsoft ait, la semaine du 4 avril 2021, déprécié la possibilité de définir une clé secrète sans date d'expiration explicite.
Si c'est le cas, dans votre console Azure, vous pouvez définir l'expiration maximale proposée (2 ans, par exemple), ce qui sera fonctionnellement équivalent.
Vous devrez, en revanche, établir un processus interne pour regénérer une nouvelle clé avant l'expiration de la précédente, et la transmettre à AppScho, afin de garantir la continuité de service. Nous conseiller d'effectuer cette opération tous les ans à date anniversaire de la création de la clé. En cas d'oubli, l'authentification ne sera plus fonctionnelle dans votre application AppScho.
Une fois l'application créée, sur sa page de configuration, rendez-vous dans l'onglet API permissions afin d'accorder certaines permissions aux utilisateurs connectés à travers AppScho, notamment :
Nom de la permission | Description de l'usage |
User.Read | Permet à AppScho de récupérer les informations basiques du profil de l'utilisateur |
Group.Read.All | Permet à AppScho de récupérer la liste des groupes auxquels l'utilisateur appartient, utile pour effectuer du profilage et pour segmenter les audiences Messaging |
Les permissions à sélectionner ici sont les version déléguées (Delegated permissions), afin d'être valides pour des sessions utilisateurs.
Une fois les permissions accordées, pensez à cliquer sur le bouton Grand admin consent for [...] au dessus de la liste des permissions afin de les accorder globalement à l'application.
Il vous suffit alors de fournir la valeur notée pour votre Application ID et la Key créée à AppScho pour permettre l'implémentation de votre authentification Office 365.
Création d'un compte de service
Il peut être nécessaire, pour AppScho, d'accéder aux API Microsoft Graph, non pas en tant qu'un utilisateur, mais en tant que service, totalement décorellé d'une quelconque session utilisateur. Afin d'autoriser ces requêtes, l'établissement doit fournir à AppScho un compte de service possédant les permissions appropriées.
C'est par exemple le cas lors de la synchronisation quotidienne de la liste des groupes existants dans le but les lister aux administrateurs de votre établissement dans votre plateforme My AppScho.
La procédure est similaire à celle exposée dans la section ci-dessus, à deux exceptions :
Aucune Reply URL ne doit être paramétrée : en effet, le workflow utilisé sera client_credentials, pas code.
Les permissions à paramétrer doivent être des permissions applicatives (Application permissions), et plus des permissions déléguées.
Vous devrez nous fournir l'Application ID et la Key associée afin de nous permettre l'utilisation de ces API.
Les permissions requises sont exposées dans le tableau suivant :
Nom de la permission | Description de l'usage |
Group.Read.All | Lister l'intégralité des groupes existants afin de les afficher dans votre plateforme d'administration |
Vérification d'un token Office 365
A travers l'API Microsoft Graph
Le jeton d'authentification qui peut être fourni aux services de votre établissement peut être utilisé pour accéder à l 'API Microsoft Graph en tant que l'utilisateur connecté. De ce fait, il est possible d'effectuer un appel HTTP à cette API en y adjoignant le jeton afin de vérifier son authenticité.
Notamment, un appel au point d'API https://graph.microsoft.com/v1.0/me permet à la fois de vérifier la validité du jeton et d'obtenir des informations basiques sur l'utilisateur connecté. Voici la forme de cette requête :
Obtenir des informations sur un utilisateur
GET https://graph.microsoft.com/v1.0/me
Headers
| Name | Type | Description |
|---|---|---|
Authorization | string | Jeton utilisateur formatté comme un bearer token ("Bearer lejeton") |
A travers une signature cryptographique
La procédure d'authentification à travers Microsoft fournit un token de type JWT au téléphone. Ce token sera transféré aux Web Services fourni par votre établissement afin d'authentifier l'utilisateur.
Cette méthode n'est plus valide avec les jetons d'authentification obtenus pour l'audience https://graph.microsoft.com, nécessaire pour accéder à l'API Microsoft Graph en tant que l'utilisateur (pour, par exemple, obtenir des informations sur l'utilisateur ou ses groupes d'appartenance.
En effet, Microsoft effectue un traitement propriétaire sur le jeton avant de pouvoir vérifier la signature cryptographique.
Sans explicitement exprimé, veuillez plutôt vous référer à la seconde méthode.
Pour rappel, un JWT est un JSON encodé en base 64 contenant des informations globales sur le token, des informations identitaires sur l'utilisateur, et une signature cryptographique permettant de vérifier que celui-ci a bien été émis par Microsoft et qu'il n'a pas été modifié depuis.
Un JWT est composé de trois partie distinctes, un en-tête fournissant des métadonnées sur le token, un payload contenant les informations sur le token lui-même, et la signature. Une fois décodé, les deux premières parties d'un JWT peuvent avoir la forme suivante (seuls les attributs les plus importants sont retranscrits ici) :
Le payload contient des informations sur l'utilisateur connecté (upn ou unique_name), la date d'expiration du token (exp contient une epoch UNIX) et l'identité de l'entité emmétrice du token (ici Microsoft, via https://sts.windows.net/xxx/).
L'en-tête, quant à lui, précise notamment la méthode de signature utilisée (ici RS256, signature via clés RSA), et un identifiant permettant de déterminer quelles clés a été utilisé pour signer ce token (kid, pour key ID).
A travers le standard JWK, Microsoft publie les clés publiques grâce auxquelles ses tokens sont signés, à l'URL suivante : https://login.microsoftonline.net/common/discovery/v2.0/keys.
Dans ce document, Microsoft lie un kid avec la clé publique (x5x) utilisée pour signer ses tokens.
En rapprochant le kid listé dans un token, et la clé publique correspondante ici, il est possible de vérifier la signature d'un token et de s'assurer qu'il provient bien de Microsoft.
Last updated