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.
# Contrôle de l’accès aux API HTTP avec des mécanismes d’autorisation JWT dans API Gateway
Vous pouvez utiliser JSON Web Tokens (JWT) dans le cadre des frameworks [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) et [OAuth 2.0](https://oauth.net/2/) pour restreindre l’accès client à vos API.
Si vous configurez un mécanisme d’autorisation JWT pour une route de votre API, API Gateway valide les JWT que les clients soumettent avec des demandes d’API. API Gateway autorise ou refuse les demandes basées sur la validation de jeton, et éventuellement, les étendues dans le jeton. Si vous configurez des étendues pour un routage, le jeton doit inclure au moins une des étendues du routage.
Vous pouvez configurer des autorisations distinctes pour chaque route d’une API ou utiliser le même mécanisme d’autorisation pour plusieurs routes.
**Note**
Il n’y a pas de mécanisme standard pour différencier les jetons d’accès JWT des autres types de JWT tels que les jetons OpenID Connect ID. À moins que vous n’ayez besoin de jetons d’ID pour l’autorisation de l’API, nous vous recommandons de configurer vos routes pour qu’elles requièrent des étendues d’autorisation. Vous pouvez également configurer vos mécanismes d’autorisation JWT pour exiger des émetteurs ou des audiences que votre fournisseur d’identité utilise uniquement lors de l’émission de jetons d’accès JWT.
## Autorisation des demandes d’API avec un mécanisme d’autorisation JWT
API Gateway utilise le workflow général suivant pour autoriser les demandes de routes configurées pour utiliser un mécanisme d’autorisation JWT.
1. Vérifiez [`identitySource`](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource) pour un jeton. `identitySource` peut inclure uniquement le jeton, ou le jeton préfixé avec `Bearer`.
1. Décodez le jeton.
1. Vérifiez l’algorithme et la signature du jeton en utilisant la clé publique récupérée auprès du `jwks_uri` de l’émetteur. Actuellement, seuls les RSA-based algorithmes sont pris en charge. API Gateway met en cache la clé publique pendant deux heures au maximum, dans la mesure du possible. En cas de panne de cache, API Gateway extrait la clé publique auprès de l'émetteur via le réseau, ce qui ajoute de la latence à la demande qui la déclenche. Les API dont le taux de demandes est faible ou intermittent sont plus susceptibles de subir ces récupérations. Comme une clé publique peut rester en cache jusqu'à deux heures, prévoyez un délai de grâce lors de la rotation des clés, pendant lequel l'ancienne et la nouvelle clé sont valides.
1. Validez les demandes. API Gateway évalue les demandes de jeton suivantes :
+ [`kid`](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5) : le jeton doit avoir une demande d’en-tête qui correspond à la clé du `jwks_uri` ayant signé le jeton.
+ [`iss`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) : doit correspondre à l’[`issuer`](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configuré pour le mécanisme d’autorisation.
+ [`aud`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) ou `client_id` : doit correspondre à l’une des entrées [`audience`](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurées pour le mécanisme d’autorisation. API Gateway ne valide `client_id` que si `aud` n’est pas présent. Si `aud` et `client_id` sont présents, API Gateway évalue `aud`.
+ [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – doit être postérieure à l’heure actuelle (UTC).
+ [`nbf`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – doit être antérieure à l'heure actuelle(UTC).
+ [`iat`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – doit être antérieure à l'heure actuelle(UTC).
+ [`scope`](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) ou `scp` : le jeton doit inclure au moins une des portées dans les [`authorizationScopes`](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) de la route.
Si l’une de ces étapes échoue, API Gateway refuse la demande d’API.
Après avoir validé le JWT, API Gateway transmet les revendications du jeton à l’intégration de la route d’API. Les ressources backend, telles que les fonctions Lambda, peuvent accéder aux revendications JWT. Par exemple, si le JWT inclut une revendication d’identité `emailID`, elle est disponible pour une intégration Lambda dans `$event.requestContext.authorizer.jwt.claims.emailID`. Pour plus d’informations sur la charge utile qu’API Gateway envoie aux intégrations Lambda, consultez [Création d'intégrations de AWS Lambda proxy pour HTTP APIs dans API Gateway](http-api-develop-integrations-lambda.md).
## Créer un mécanisme d’autorisation JWT
Avant de créer un mécanisme d’autorisation JWT, vous devez enregistrer une application cliente auprès d’un fournisseur d’identité. Vous devez également avoir créé une API HTTP. Pour obtenir des exemples de création d'une API HTTP, veuillez consulter [Création d’une API HTTP](http-api-develop.md#http-api-examples).
### Création d’un mécanisme d’autorisation JWT à l’aide de la console
La procédure suivante montre comment créer un mécanisme d’autorisation JWT à l’aide de la console.
**Pour créer un mécanisme d’autorisation JWT à l’aide de la console**
1. Connectez-vous à la console API Gateway à l'adresse [ https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez une API HTTP.
1. Dans le panneau de navigation principal, choisissez **Autorisation**.
1. Choisissez l’onglet **Gérer les mécanismes d’autorisation**.
1. Cliquez sur **Créer**.
1. Pour **Type du mécanisme d’autorisation**, choisissez **JWT**.
1. Configurez votre mécanisme d’autorisation JWT et spécifiez une **source d’identité** qui définit la source du jeton.
1. Cliquez sur **Créer**.
#### Créez un autorisateur JWT à l'aide du AWS CLI
La commande [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) suivante crée un mécanisme d’autorisation JWT. Pour `jwt-configuration`, spécifiez les paramètres `Audience` et `Issuer` pour votre fournisseur d’identité. Si vous utilisez Amazon Cognito comme fournisseur d’identité, `IssuerUrl` est `https://cognito-idp.{{us-east-2}}.amazonaws.com/{{userPoolID}}`.
```
aws apigatewayv2 create-authorizer \
--name {{authorizer-name}} \
--api-id {{api-id}} \
--authorizer-type JWT \
--identity-source '{{$request.header.Authorization}}' \
--jwt-configuration Audience={{audience}},Issuer={{IssuerUrl}}
```
##### Créez un autorisateur JWT à l'aide de AWS CloudFormation
Le CloudFormation modèle suivant crée une API HTTP avec un autorisateur JWT qui utilise Amazon Cognito comme fournisseur d'identité.
Le résultat du CloudFormation modèle est une URL pour une interface utilisateur hébergée par Amazon Cognito où les clients peuvent s'inscrire et se connecter pour recevoir un JWT. Une fois qu’un client s’est connecté, il est redirigé vers votre API HTTP avec un jeton d’accès dans l’URL. Pour invoquer l’API avec le jeton d’accès, remplacez le symbole `#` de l’URL par un `?` pour utiliser le jeton comme paramètre de chaîne de requête.
##### Exemple CloudFormation modèle
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## Mise à jour d’une route pour utiliser un mécanisme d’autorisation JWT
Vous pouvez utiliser la console AWS CLI, le SDK ou un AWS SDK pour mettre à jour un itinéraire afin d'utiliser un autorisateur JWT.
### Mise à jour d’une route pour utiliser un mécanisme d’autorisation JWT à l’aide de la console
La procédure suivante montre comment mettre à jour un mécanisme d’autorisation JWT à l’aide de la console.
**Pour créer un mécanisme d’autorisation JWT à l’aide de la console**
1. Connectez-vous à la console API Gateway à l'adresse [ https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez une API HTTP.
1. Dans le panneau de navigation principal, choisissez **Autorisation**.
1. Choisissez une méthode, puis sélectionnez votre mécanisme d’autorisation dans le menu déroulant, puis choisissez **Attacher le mécanisme d’autorisation**.
#### Mettez à jour un itinéraire pour utiliser un autorisateur JWT à l'aide du AWS CLI
La commande [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) suivante met à jour une route de manière à ce qu’elle utilise un mécanisme d’autorisation JWT :
```
aws apigatewayv2 update-route \
--api-id {{api-id}} \
--route-id {{route-id}} \
--authorization-type JWT \
--authorizer-id {{authorizer-id}} \
--authorization-scopes {{user.email}}
```