Portées OAuth 2.0 et autorisation d'API avec des serveurs de ressources

Une fois que vous avez configuré un domaine pour votre groupe d'utilisateurs, Amazon Cognito provisionne automatiquement un serveur d'autorisation OAuth 2.0 et une interface utilisateur Web hébergée avec des pages d’inscription et de connexion que votre application présentera à vos utilisateurs. Pour de plus amples informations, veuillez consulter Ajout d'un client d'application et configuration de l'interface utilisateur hébergée. Vous pouvez choisir les portées que vous souhaitez que le serveur d'autorisation ajoute aux jetons d'accès. Les portées autorisent l'accès aux serveurs de ressources et aux données utilisateur.

Un serveur de ressources est un serveur d'API OAuth 2.0. Pour sécuriser les ressources à accès protégé, il vérifie que les jetons d'accès de votre groupe d'utilisateurs contiennent les portées autorisant la méthode et le chemin demandés dans l'API qu'il protège. Il vérifie l'émetteur en fonction de la signature du jeton, la validité en fonction de l'heure d'expiration du jeton et le niveau d'accès en fonction des portées des enregistrements du jeton. Les groupes d'utilisateurs présentent des portées dans la portée du jeton d'accès claim. Pour plus d'informations sur les enregistrements relatifs aux jetons d'accès Amazon Cognito, consultez Utilisation du jeton d'accès.

Que vos utilisateurs soient locaux ou tiers, et qu'ils s'authentifient via l'interface utilisateur hébergée ou via l'API des groupes d'utilisateurs Amazon Cognito, votre profil utilisateur peut générer des jetons d'accès dont les portées autorisent votre application à utiliser les attributs utilisateur.

À propos des portées

Une portée est un niveau d'accès qu'une application peut demander à une ressource. Dans un jeton d'accès Amazon Cognito, la portée est renforcée par la confiance que vous avez établie avec votre groupe d'utilisateurs : un émetteur fiable de jetons d'accès doté d'une signature numérique connue. Les groupes d'utilisateurs peuvent générer des jetons d'accès dont les portées prouvent que votre client est autorisé à gérer tout ou partie de son propre profil utilisateur, ou à récupérer des données depuis une API principale. Les groupes d'utilisateurs Amazon Cognito émettent des jetons d'accès avec la portée d'API réservée aux groupes d'utilisateurs, des portées personnalisées et des portées standard.

Champ d'application de l'API réservé aux groupes d'utilisateurs

La portée aws.cognito.signin.user.admin autorise l'API des groupes d'utilisateurs Amazon Cognito. Ce code autorise le porteur d'un jeton d'accès à interroger et à mettre à jour toutes les informations concernant un utilisateur d'un groupe d'utilisateurs avec, par exemple, les opérations d'API GetUser et UpdateUserAttributes. Lorsque vous authentifiez votre utilisateur avec l'API des groupes d'utilisateurs Amazon Cognito, il s'agit de la seule portée que vous recevez dans le jeton d'accès. C'est également la seule portée dont vous avez besoin pour lire et écrire les attributs utilisateur pour lesquels vous avez donné des droits de lecture et d'écriture à votre client d'application. Vous pouvez également demander cette portée dans les demandes adressées à votre Point de terminaison d’autorisation. La portée seule ne suffit pas à demander les attributs utilisateur au Point de terminaison UserInfo. Pour les jetons d'accès qui autorisent à la fois l'API des groupes d'utilisateurs et les demandes userInfo pour vos utilisateurs, vous devez demander à la fois les portées openid et aws.cognito.signin.user.admin dans une demande /oauth2/authorize.

Portées personnalisées

Les portées personnalisées autorisent les demandes adressées aux API externes protégées par les serveurs de ressources. Vous pouvez demander des portées personnalisées avec d'autres types de portées. Vous trouverez plus d'informations sur les portées personnalisées sur cette page.

Portées standard

Lorsque vous authentifiez des utilisateurs auprès du serveur d'autorisation OAuth 2.0 de votre groupe d'utilisateurs, y compris avec l'interface utilisateur hébergée, vous devez demander des portées. Vous pouvez authentifier les utilisateurs locaux du groupe d'utilisateurs et les utilisateurs fédérés tiers sur votre serveur d'autorisation Amazon Cognito. Les portées OAuth 2.0 standard autorisent votre application à lire les informations utilisateur du Point de terminaison UserInfo de votre groupe d'utilisateurs. Le modèle OAuth, dans lequel vous interrogez les attributs utilisateur depuis le point de terminaison userInfo, permet d'optimiser votre application pour un volume élevé de demandes d'attributs utilisateur. Le point de terminaison userInfo renvoie des attributs à un niveau d'autorisation déterminé par les portées du jeton d'accès. Vous pouvez autoriser votre client d'application à émettre des jetons d'accès avec les portées OAuth 2.0 standard suivantes.

openid

Portée minimale pour les requêtes OpenID Connect (OIDC). Autorise le jeton d'identification, l'enregistrement d'identifiant unique sub et la possibilité de demander d'autres portées.

Note

Lorsque vous demandez la portée openid et aucune autre, votre jeton d'identification de groupe d'utilisateurs et votre réponse userInfo incluent les demandes de tous les attributs utilisateur que votre client d'application peut lire. Lorsque vous demandez openid et d'autres portées standard telles que profile, email etphone, le contenu du jeton d'identification et de la réponse userInfo est limité aux contraintes des portées supplémentaires.

Par exemple, une requête adressée au Point de terminaison d’autorisation avec le paramètre scope=openid+email renvoie un jeton d'identification avec sub, email etemail_verified. Le jeton d'accès issu de cette demande renvoie les mêmes attributs depuisPoint de terminaison UserInfo. Une demande avec le paramètre scope=openid renvoie tous les attributs lisibles par le client dans le jeton d'identification et depuis userInfo.

profile

Autorise tous les attributs utilisateur que le client d'application peut lire.

e-mail

Autorise les attributs utilisateur email et email_verified. Amazon Cognito renvoie une valeur email_verified si une valeur a été définie de manière explicite.

phone

Autorise les attributs utilisateur phone_number et phone_number_verified.

À propos des serveurs de ressources

Une API de serveur de ressources peut autoriser l'accès aux informations d'une base de données ou contrôler vos ressources informatiques. Un jeton d'accès Amazon Cognito peut autoriser l'accès aux API qui prennent en charge le protocole OAuth 2.0. Les API REST Amazon API Gateway disposent d'une prise en charge intégrée des autorisations avec jetons d'accès Amazon Cognito. Votre application transmet le jeton d'accès dans l'appel d'API au serveur de ressources. Le serveur de ressources inspecte le jeton d'accès pour déterminer si l'accès doit être accordé.

Amazon Cognito pourrait apporter de futures mises à jour au schéma des jetons d'accès du groupe d'utilisateurs. Si votre application analyse le contenu du jeton d'accès avant de le transmettre à une API, vous devez concevoir votre code pour accepter les mises à jour du schéma.

Vous définissez les portées personnalisées, qui étendent les capacités d'autorisation d'un groupe d'utilisateurs pour inclure des objectifs non liés à l'interrogation et à la modification des utilisateurs et de leurs attributs. Par exemple, si vous disposez d'un serveur de ressources pour les photos, il peut définir deux portées : photos.read pour lire l'accès aux photos et photos.write pour écrire/supprimer l'accès. Vous pouvez configurer une API pour accepter des jetons d'accès à des fins d'autorisation et accorder des demandes d'accès à des jetons HTTP GET avec photos.read dans la revendication scope, et des demandes HTTP POST adressées à des jetons avec photos.write. Il s'agit de portées personnalisées.

Note

Votre serveur de ressources doit vérifier la signature et la date d'expiration du jeton d'accès avant de traiter toute réclamation à l'intérieur du jeton. Pour plus d'informations sur la vérification des jetons, consultez Vérification d'un jeton web JSON. Pour plus d'informations sur la vérification et l'utilisation des jetons de groupe d'utilisateurs dans Amazon API Gateway, consultez le blog Intégration des groupes d'utilisateurs Amazon Cognito avec API Gateway. API Gateway est une bonne option pour inspecter les jetons d'accès et protéger vos ressources. Pour plus d'informations sur les mécanismes d'autorisation Lambda API Gateway, consultez Utilisation des mécanismes d'autorisation Lambda API Gateway.

Présentation

Amazon Cognito vous permet de créer des Serveurs de ressources OAuth 2.0 et d'y associer des Portées personnalisées. Les portées personnalisées d'un jeton d'accès autorisent des actions spécifiques dans votre API. Vous pouvez autoriser n'importe quel client d'application de votre groupe d'utilisateurs à émettre des portées personnalisées à partir de n'importe lequel de vos serveurs de ressources. Associez vos portées personnalisées à un client d'application et demandez ces portées dans le cadre des octrois de code d'autorisation OAuth 2.0, des octrois implicites et des octrois d'informations d'identification client à partir du Point de terminaison de jeton. Amazon Cognito ajoute des portées personnalisées à la revendication scope d'un jeton d'accès. Un client peut utiliser le jeton d'accès sur son serveur de ressources, ce qui base la décision d'autorisation sur les périmètres présents dans le jeton. Pour plus d'informations sur la portée du jeton d'accès, consultez Utilisation de jetons avec des groupes d'utilisateurs.

Pour obtenir un jeton d'accès avec des portées personnalisées, votre application doit adresser une demande au Point de terminaison de jeton pour utiliser un code d'autorisation ou pour demander un octroi d'informations d'identification client. Dans l'interface utilisateur hébergée, vous pouvez également demander des portées personnalisées dans un jeton d'accès à partir d'une autorisation implicite.

Note

Les requêtes InitiateAuth et AdminInitiateAuth étant conçues pour une authentification interactive avec le groupe d'utilisateurs en tant qu'IdP, elles ne produisent qu'une revendication scope dans le jeton d'accès avec une valeur unique aws.cognito.signin.user.admin.

Gestion du serveur de ressources et des périmètres personnalisés

Lors de la création d'un serveur de ressources, vous devez fournir un nom et un identifiant de serveur de ressources. Pour chaque portée que vous créez dans le serveur de ressources, vous devez fournir le nom et la description de la portée.

• Nom du serveur de ressources : nom convivial du serveur de ressources, tel que Solar system object tracker ou Photo API.

• Identifiant du serveur de ressources : identifiant unique du serveur de ressources. L'identifiant est un nom que vous pouvez associer à votre API, par exemple, solar-system-data. Vous pouvez configurer des identifiants plus longs, comme https://solar-system-data-api.example.com, en référence plus directe aux chemins d'URI des API, mais des chaînes plus longues augmentent la taille des jetons d'accès.

• Nom de la portée : valeur que vous souhaitez voir figurer dans vos revendications scope. Par exemple, sunproximity.read.

• Description : description conviviale de la portée. Par exemple, Check current proximity to sun.

Amazon Cognito peut inclure des portées personnalisées dans les jetons d'accès pour tous les utilisateurs, qu'ils soient locaux dans votre groupe d'utilisateurs ou fédérés avec un fournisseur d'identité tiers. Vous pouvez choisir les portées des jetons d'accès de vos utilisateurs lors des flux d'authentification avec le serveur d'autorisation OAuth 2.0 qui inclut l'interface utilisateur hébergée. L'authentification de votre utilisateur doit commencer au Point de terminaison d’autorisation avec scope en tant que l'un des paramètres de la demande. Le format suivant est recommandé pour les serveurs de ressources. Pour un identifiant, utilisez un nom d'API convivial. Pour une portée personnalisée, utilisez l'action autorisée.

resourceServerIdentifier/scopeName

Par exemple, vous avez découvert un nouvel astéroïde dans la ceinture de Kuiper et vous souhaitez l'enregistrer via votre API solar-system-data. La portée qui autorise les opérations d'écriture dans la base de données des astéroïdes est asteroids.add. Lorsque vous demandez le jeton d'accès qui vous autorisera à enregistrer votre découverte, indiquez le paramètre de votre demande HTTPS scope sous la forme scope=solar-system-data/asteroids.add.

La suppression d'une portée d'un serveur de ressources n'a pas pour effet de supprimer son association avec tous les clients. Au lieu de cela, la portée est marquée comme inactive. Amazon Cognito n'ajoute pas de portées inactives aux jetons d'accès, mais procède normalement si votre application en fait la demande. Si vous ajoutez à nouveau la portée à votre serveur de ressources ultérieurement, Amazon Cognito l'écrit à nouveau dans le jeton d'accès. Si vous demandez une portée que vous n'avez pas associée à votre client d'application, que vous l'ayez supprimée ou non du serveur de ressources de votre groupe d'utilisateurs, l'authentification échoue.

Vous pouvez utiliser la AWS Management Console, l'API et la CLI pour définir les serveurs de ressources et les périmètres de votre groupe d'utilisateurs.

Définition d'un serveur de ressources pour votre groupe d'utilisateurs (AWS Management Console)

Vous pouvez utiliser la AWS Management Console pour définir un serveur de ressources pour votre groupe d'utilisateurs.

Pour définir un serveur de ressources

1. Connectez-vous à la console Amazon Cognito.

2. Dans le volet de navigation, choisissez Groupes d'utilisateurs, puis le groupe d'utilisateurs à modifier.

3. Choisissez l'onglet App integration (Intégration d'applications) et localisez Resource servers (Serveurs de ressources).

4. Choisissez Créer un serveur de ressources.

5. Saisissez un nom du serveur de ressources. Par exemple, Photo Server.

6. Saisissez un Identifiant de serveur de ressources. Par exemple, com.example.photos.

7. Saisissez les noms des périmètres personnalisés de vos ressources comme read et write.

8. Pour chacun des noms de portée, saisissez une description, telles que view your photos et update your photos.

9. Choisissez Créer.

Vos périmètres personnalisés peuvent être examinés dans l'onglet App integration (Intégration d'applications) sous Resource servers (Serveurs de ressources) dans Custom scopes (Périmètres personnalisés). Les périmètres personnalisés peuvent être activés pour les clients d'application à partir de l'onglet App integration (Intégration d'applications) sous App clients (Clients d'application). Sélectionnez un client d'application, recherchez Paramètres d'interface utilisateur hébergée et choisissez Modifier. Ajoutez des périmètres personnalisés et choisissez Save changes (Enregistrez les modifications).

Définition d'un serveur de ressources pour votre groupe d'utilisateurs (AWS CLI et API AWS)

Utilisez les commandes suivantes pour spécifier les paramètres de serveur de ressources pour votre groupe d'utilisateurs.

Pour créer un serveur de ressources

• AWS CLI: aws cognito-idp create-resource-server

• API AWS : CreateResourceServer

Pour obtenir des informations sur les paramètres de votre serveur de ressources

• AWS CLI: aws cognito-idp describe-resource-server

• API AWS : DescribeResourceServer

Pour répertorier des informations sur tous les serveurs de ressources pour votre groupe d'utilisateurs

• AWS CLI: aws cognito-idp list-resource-servers

• API AWS : ListResourceServers

Pour supprimer un serveur de ressources

• AWS CLI: aws cognito-idp delete-resource-server

• API AWS : DeleteResourceServer

Pour mettre à jour les paramètres d'un serveur de ressources

• AWS CLI: aws cognito-idp update-resource-server

• API AWS : UpdateResourceServer