Ressources API
Les ressources API, également appelées Indicateurs de Ressource, indiquent les services ou ressources cibles à demander, généralement une variable au format URI représentant l'identité de la ressource. C'est un concept clé dans le système d'autorisation de Logto, car il définit le point de terminaison que la politique d'autorisation est conçue pour protéger.
Indicateur de ressource
- Une valeur de ressource indique le service ou la ressource cible auquel l'accès est demandé.
- Sa valeur DOIT être un URI absolu.
- L'URI NE DOIT PAS inclure un composant fragment.
- Il NE DEVRAIT PAS inclure un composant de requête.
- Vous DEVRIEZ fournir l'URI le plus spécifique possible pour l'API complète ou l'ensemble de ressources qu'il entend accéder.
En pratique, un client peut connaître un URI de base ou l'application ou la ressource avec laquelle interagir. Il serait approprié de l'utiliser comme valeur du paramètre de ressource.
Par exemple, l'URI de base de la Logto Management API.
https://tenantId.logto.app/api
Par défaut, cette ressource API est préenregistrée dans votre service Logto. Toutes les Management API sous cet URI sont protégées par Logto.
Schéma de ressource API Logto
| Nom de la propriété | Description de la propriété | Requis |
|---|---|---|
| Nom de l'API | Un nom convivial qui peut vous aider à identifier la ressource API. | true |
| Identifiant de l'API | La valeur unique de l'Indicateur de Ressource de l'API, avec les restrictions listées ci-dessus. | |
| Logto l'utilisera pour identifier la ressource API demandée et accorder les jetons d’autorisation en conséquence. | true | |
| Temps d'expiration du jeton (en secondes) | Le temps d'expiration défini pour le jeton d’accès. La valeur d'expiration par défaut est 3600. | false |
| API par défaut | Une seule API par défaut peut être définie par locataire. | |
| Lorsqu'une API par défaut est désignée, le paramètre de ressource peut être omis dans la requête d'authentification. Les échanges de jetons ultérieurs utiliseront cette API comme audience par défaut, entraînant l'émission de JWTs. | false |
Les requêtes avec un jeton d’accès expiré doivent être restreintes. Cela est mis en œuvre pour protéger votre API d'un jeton abusé. Plus la valeur est grande, plus un jeton d’accès émis survivra longtemps, et plus votre API sera vulnérable.
API par défaut
Cette fonctionnalité est principalement destinée aux applications qui ne prennent PAS en charge les indicateurs de ressource OIDC, par exemple, les plugins ChatGPT.
Logto utilise RFC 8707 : Indicateurs de Ressource pour OAuth 2.0 pour mettre en œuvre le contrôle d’accès basé sur les rôles (RBAC). Bien que ce soit l'une des fonctionnalités d'OAuth 2.0, elle n'est pas encore largement prise en charge.
Dans l'implémentation de Logto, chaque permission (portée) définie par l'utilisateur doit être associée à une Ressource API. Sinon, elle sera traitée comme une permission OpenID Connect (ou OAuth). En général, cela n'affecte pas votre processus d'autorisation. Cependant, lors de l'intégration avec des applications tierces qui ne prennent pas en charge RFC 8707 (par exemple, les plugins ChatGPT), cela peut poser des défis puisque la requête d'autorisation initiale peut ne pas inclure un paramètre resource. Par conséquent, Logto émettra toujours des Jetons d’Accès Opaques.
Pour résoudre ce problème, vous pouvez désigner une Ressource API comme ressource par défaut au niveau du locataire. Une fois cela fait :
- Logto utilisera la Ressource API par défaut lorsqu'aucun paramètre
resourcen'est présent dans la Requête d’authentification. - Si la portée
openidest incluse, un Jeton d’Accès Opaque pour le Point de terminaison Userinfo sera émis lorsqu'aucun paramètreresourcen'est présent dans les Requêtes de jeton ultérieures. - Si la portée
openidn'est pas incluse, un Jeton d’Accès JWT pour la Ressource API par défaut sera émis lorsqu'aucun paramètreresourcen'est présent dans les Requêtes de jeton ultérieures.
En désignant une Ressource API par défaut, vous pouvez assurer une intégration fluide avec les applications ne prenant pas en charge RFC 8707 tout en maintenant les contrôles d'accès appropriés.
Enregistrer les ressources API dans Logto
Pour obtenir un jeton d’accès restreint par audience de Logto, enregistrez d'abord vos API backend pour activer les jetons d’accès restreints par audience de Logto. Lorsqu'une requête d'autorisation est reçue, Logto identifiera les ressources API enregistrées et accordera l'accès en conséquence.
Pour enregistrer vos API, accédez à Console > Ressources API. Vous verrez une ressource intégrée avec l'identifiant de l'API affiché comme https://[your-tenant-id].logto.app/api. Cette ressource englobe toutes les Management APIs de Logto et garantit qu'elles sont protégées et accessibles uniquement aux utilisateurs autorisés de Logto.
Cliquez sur le bouton Créer une ressource API et suivez le formulaire interactif pour créer vos propres ressources API :
- Un nom d'API lisible par l'homme qui peut mieux vous aider à identifier cette entité.
- Un identifiant d'API unique au format URI. Il représente l'identité de la ressource API.
La nouvelle API apparaîtra dans la liste une fois créée. Vous pouvez la gérer ou la supprimer sur la page des détails de l'API en cliquant sur l'entité.