Éscopes, M2M et APIs avec serveurs de ressources - Amazon Cognito

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Éscopes, M2M et APIs avec serveurs de ressources

Après avoir configuré un domaine pour votre groupe d'utilisateurs, Amazon Cognito fournit 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 peut présenter à vos utilisateurs. Pour plus d'informations, voir Ajouter un client d'application avec 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 API serveur OAuth 2.0. Pour sécuriser les ressources dont l'accès est protégé, il vérifie que les jetons d'accès de votre groupe d'utilisateurs contiennent les étendues autorisant la méthode et le chemin demandés dans le API champ 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 étendues du groupe d'utilisateurs figurent dans la scope réclamation du jeton d'accès. Pour plus d'informations sur les enregistrements relatifs aux jetons d'accès Amazon Cognito, consultez Comprendre le jeton d'accès.

Avec Amazon Cognito, les étendues des jetons d'accès peuvent autoriser l'accès à des attributs externes APIs ou à des attributs utilisateur. Vous pouvez émettre des jetons d'accès à des utilisateurs locaux, à des utilisateurs fédérés ou à des identités de machine.

APIautorisation

Voici quelques-unes des manières dont vous pouvez autoriser les demandes à l'APIsaide de jetons Amazon Cognito :

Jeton d’accès

Lorsque vous ajoutez un autorisateur Amazon Cognito à la configuration d'une demande de REST API méthode, ajoutez des étendues d'autorisation à la configuration de l'autorisateur. Avec cette configuration, vous acceptez API les jetons d'accès dans l'Authorizationen-tête et les examinez pour déterminer les étendues acceptées.

Jeton d’identification

Lorsque vous transmettez un jeton d'identification valide à un autorisateur Amazon Cognito de votre ordinateur RESTAPI, API Gateway accepte la demande et transmet le contenu du jeton d'identification au backend. API

Amazon Verified Permissions

Dans Autorisations vérifiées, vous avez la possibilité de créer un magasin de politiques API lié. Verified Permissions crée et attribue un autorisateur Lambda qui traite les identifiants ou les jetons d'accès provenant de l'en-tête de votre demande. Authorization Cet autorisateur Lambda transmet votre jeton à votre magasin de politiques, où Verified Permissions le compare aux politiques et renvoie une décision d'autorisation ou de refus à l'autorisateur.

Machine-to-machine Autorisation (M2M)

Amazon Cognito prend en charge les applications qui accèdent aux API données avec des identités de machine. Les identités des machines dans les groupes d'utilisateurs sont des clients confidentiels qui s'exécutent sur des serveurs d'applications et se connectent à distanceAPIs. Leur fonctionnement s'effectue sans interaction de l'utilisateur : tâches planifiées, flux de données ou mises à jour des actifs. Lorsque ces clients autorisent leurs demandes à l'aide d'un jeton d'accès, ils effectuent une autorisation machine à machine, ou M2M. Dans l'autorisation M2M, un secret partagé remplace les informations d'identification de l'utilisateur dans le contrôle d'accès.

Une application qui accède à un compte API avec une autorisation M2M doit disposer d'un identifiant client et d'un secret client. Dans votre groupe d'utilisateurs, vous devez créer un client d'application qui prend en charge les autorisations d'identification des clients. Pour prendre en charge les informations d'identification des clients, le client de votre application doit disposer d'un secret client et vous devez disposer d'un domaine de groupe d'utilisateurs. Dans ce flux, l'identité de votre machine demande un jeton d'accès directement auprès duPoint de terminaison de jeton. Vous ne pouvez autoriser que des étendues personnalisées provenant de serveurs de ressources dans des jetons d'accès pour les autorisations d'identification des clients. Pour plus d'informations sur la configuration des clients d'applications, consultezParamètres spécifiques à l'application avec les clients d'applications.

Le jeton d'accès provenant d'une autorisation d'identification client est une déclaration vérifiable des opérations que vous souhaitez autoriser l'identité de votre machine à demander à unAPI. Pour en savoir plus sur la façon dont les jetons d'accès autorisent API les demandes, poursuivez votre lecture. Pour un exemple d'application, consultez Amazon Cognito et l'utilisation de l'autorisation machine à machine basée sur Amazon API Gateway. AWS CDK

L'autorisation M2M repose sur un modèle de facturation différent de la façon dont les utilisateurs actifs mensuels (MAUs) sont facturés. Lorsque l'authentification des utilisateurs entraîne un coût par utilisateur actif, la facturation M2M reflète les informations d'identification des clients actifs, les clients des applications et le volume total de demandes de jetons. Pour plus d’informations, consultez Tarification d’Amazon Cognito. Pour contrôler les coûts d'autorisation M2M, optimisez la durée des jetons d'accès et le nombre de demandes de jetons effectuées par vos applications. Découvrez comment utiliser la mise en cache de API Gateway Gestion de l'expiration et de la mise en cache des jetons du pool d'utilisateurs pour réduire les demandes de nouveaux jetons dans le cadre de l'autorisation M2M.

Pour plus d'informations sur l'optimisation des opérations Amazon Cognito qui ajoutent des coûts à votre AWS facture, consultez. Gestion des coûts

À 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 l'étendue prouve que votre client est autorisé à gérer tout ou partie de son propre profil utilisateur, ou à récupérer des données depuis un back-endAPI. Les groupes d'utilisateurs Amazon Cognito émettent des jetons d'accès avec l'APIétendue réservée des groupes d'utilisateurs, des étendues personnalisées et des étendues OpenID Connect (). OIDC

Champ d'APIapplication réservé du pool d'utilisateurs

Le aws.cognito.signin.user.admin champ d'application autorise les opérations en libre-service pour l'utilisateur actuel dans les groupes d'utilisateurs Amazon Cognito. API Il autorise le porteur d'un jeton d'accès à interroger et à mettre à jour toutes les informations le concernant avec, par exemple, les GetUseropérations et. UpdateUserAttributesAPI Lorsque vous authentifiez votre utilisateur auprès des API groupes d'utilisateurs Amazon Cognito, il s'agit de la seule étendue 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 userInfo point final. Pour les jetons d'accès qui autorisent à la fois des groupes d'utilisateurs API et des userInfo demandes pour vos utilisateurs, vous devez demander à la fois les étendues openid et aws.cognito.signin.user.admin dans une /oauth2/authorize demande.

Portées personnalisées

Les étendues personnalisées autorisent les demandes adressées à l'extérieur APIs que les serveurs de ressources protègent. 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.

Champs d'application OpenID Connect () OIDC

Lorsque vous authentifiez des utilisateurs avec le serveur d'autorisation de votre groupe d'utilisateurs, y compris avec l'interface utilisateur hébergée, vous devez demander des étendues. 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. OIDCles scopes autorisent votre application à lire les informations utilisateur userInfo point final de votre groupe d'utilisateurs. Le OAuth modèle, dans lequel vous interrogez les attributs utilisateur depuis le userInfo point de terminaison, 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 le client de votre application à émettre des jetons d'accès dans les OIDC domaines suivants.

openid

La 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 que d'OIDCautres champs d'application tels que profileemail, etphone, le contenu du jeton d'identification et de la userInforéponse est limité aux contraintes des champs d'application 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 depuisuserInfo point final. 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

Un serveur de ressources API 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 à APIs ce support OAuth 2.0. Amazon API Gateway intègre REST APIs un support d'autorisation avec les jetons d'accès Amazon Cognito. Votre application transmet le jeton d'accès au serveur de ressources lors de l'APIappel. 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 à unAPI, 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 un API pour accepter les jetons d'accès à des fins d'autorisation, et accorder les HTTP GET demandes d'accès aux jetons photos.read figurant dans la scope réclamation, et les HTTP POST demandes aux jetons avecphotos.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 JSON Web. Pour plus d'informations sur la vérification et l'utilisation des jetons du groupe d'utilisateurs dans Amazon API Gateway, consultez le blog Integrating Amazon Cognito User Pools with API Gateway. APILa passerelle est une bonne option pour inspecter les jetons d'accès et protéger vos ressources. Pour en savoir plus sur les autorisateurs API Gateway Lambda, voir Utiliser les autorisateurs Gateway API Lambda.

Présentation

Avec Amazon Cognito, vous pouvez créer des serveurs de ressources OAuth 2.0 et leur associer des étendues personnalisées. Les étendues personnalisées d'un jeton d'accès autorisent des actions spécifiques dans votreAPI. 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 étendues personnalisées à un client d'application et demandez ces étendues dans les autorisations de code d'autorisation OAuth 2.0, les autorisations implicites et les autorisations d'identification client auprès 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.

Vue d'ensemble du flux d'un serveur de ressources. Le client demande une subvention avec une portée personnalisée, le groupe d'utilisateurs renvoie un jeton d'accès avec l'étendue personnalisée, et le client présente le jeton d'accès à unAPI.

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

Parce qu'elles sont conçues pour une authentification interactive avec le groupe d'utilisateurs comme IdP InitiateAuth, AdminInitiateAuthet que les demandes ne produisent qu'scopeune réclamation 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 souhaitez associer à votreAPI, par exemplesolar-system-data. Vous pouvez configurer des identifiants plus longs, https://solar-system-data-api.example.com comme une référence plus directe aux API URI chemins, 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 étendues 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 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. solar-system-data API 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, formatez le paramètre de votre scope HTTPS demande sous la formescope=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 le AWS Management Console API, ou CLI pour définir des serveurs de ressources et des étendues pour votre groupe d'utilisateurs.

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

Vous pouvez utiliser le 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 AWS API)

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
Pour obtenir des informations sur les paramètres de votre serveur de ressources
Pour répertorier des informations sur tous les serveurs de ressources pour votre groupe d'utilisateurs
Pour supprimer un serveur de ressources
Pour mettre à jour les paramètres d'un serveur de ressources