Cette page explique comment utiliser les limites d'accès aux identifiants pour créer un jeton d'accès OAuth 2.0 avec des autorisations Cloud Storage réduites.
Le processus de création d'un jeton avec des autorisations limitées comprend les étapes suivantes :
- Attribuez les rôles IAM appropriés à un utilisateur ou à un compte de service.
- Définissez une limite d'accès aux identifiants qui fixe une limite supérieure aux autorisations disponibles pour l'utilisateur ou le compte de service.
- Créez un jeton d'accès OAuth 2.0 pour l'utilisateur ou le compte de service.
- Échangez le jeton d'accès OAuth 2.0 contre un nouveau jeton respectant la limite d'accès aux identifiants.
Vous pouvez ensuite utiliser le nouveau jeton d'accès OAuth 2.0 à champ d'application réduit pour authentifier les requêtes auprès de Cloud Storage.
Avant de commencer
Avant d'utiliser les limites d'accès aux identifiants, assurez-vous de remplir les conditions suivantes :
Vous ne devez réduire les autorisations que pour Cloud Storage, et non pour les autres servicesGoogle Cloud .
Si vous devez réduire les autorisations pour d'autres services Google Cloud, vous pouvez créer plusieurs comptes de service et accorder un ensemble de rôles différent à chaque compte de service.
Vous pouvez utiliser les jetons d'accès OAuth 2.0 pour l'authentification. Les autres types d'identifiants de courte durée ne sont pas compatibles avec les limites d'accès aux identifiants.
En outre, vous devez activer les API nécessaires :
-
Activez les API IAM et Security Token Service, si elles ne sont pas déjà activées.
Rôles requis pour activer les API
Pour activer des API, vous devez disposer de l'autorisation
serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.
Attribuer des rôles IAM
Une limite d'accès aux identifiants définit la limite supérieure des autorisations disponibles pour une ressource. Elle peut soustraire des autorisations d'un compte principal, mais elle ne peut pas ajouter d'autorisations que le compte principal ne possède pas déjà.
Par conséquent, vous devez attribuer au compte principal des rôles qui fournissent les autorisations nécessaires dans un bucket Cloud Storage ou sur une ressource de niveau supérieur, comme le projet.
Supposons, par exemple, que vous ayez besoin de créer des identifiants éphémères à champ d'application limité, permettant à un compte de service de créer des objets dans un bucket :
- Vous devez au moins octroyer au compte de service un rôle comprenant l'autorisation
storage.objects.create, par exemple le rôle Créateur d'objets Storage (roles/storage.objectCreator). La limite d'accès aux identifiants doit également inclure cette autorisation. - Vous pouvez également attribuer un rôle comprenant davantage d'autorisations, tel que le rôle Administrateur d'objets Storage (
roles/storage.objectAdmin). Le compte de service ne peut utiliser que les autorisations qui apparaissent à la fois dans le rôle attribué et dans la limite d'accès aux identifiants.
Pour en savoir plus sur les rôles prédéfinis pour Cloud Storage, consultez la page Rôles Cloud Storage.
Définir la limite d'accès aux identifiants
Une limite d'accès aux identifiants est un objet qui contient une liste de règles de limite d'accès. Les règles sont composées de paramètres qui spécifient la limite supérieure des autorisations disponibles pour l'utilisateur ou le compte de service. Pour définir une limite d'accès aux identifiants, créez un objet JSON qui liste les règles de limite d'accès et leurs paramètres.
Voici un exemple de limite d'accès aux identifiants :
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:ROLE_ID"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME",
"availabilityCondition": {
"expression" : "CONDITION"
}
}
]
}
}
Remplacez les éléments suivants :
ROLE_ID: ID d'un rôle prédéfini ou personnalisé qui définit la limite supérieure des autorisations disponibles pour la ressource. Exemple :roles/storage.objectViewerPour spécifier plusieurs rôles, ajoutez une nouvelle ligne avec un préfixeinRole:suivi de l'ID du rôle. Seules les autorisations des rôles spécifiés seront disponibles.BUCKET_NAME: nom du bucket Cloud Storage auquel la règle s'applique.CONDITION: facultatif. Expression de condition qui spécifie les objets Cloud Storage pour lesquels des autorisations sont disponibles. Par exemple, la condition suivante rend les autorisations disponibles pour les objets dont le nom commence parcustomer-a:resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')
Pour en savoir plus sur la création et la personnalisation des limites d'accès des identifiants, consultez Composants d'une limite d'accès des identifiants.
Pour obtenir des exemples de cas d'utilisation potentiels des limites d'accès aux identifiants, consultez Exemples de limites d'accès aux identifiants.
Créer un jeton d'accès OAuth 2.0
Avant de créer un identifiant éphémère à champ d'application limité, vous devez créer un jeton d'accès OAuth 2.0 standard. Vous pouvez ensuite échanger l'identifiant standard contre un identifiant à champ d'application limité. Lorsque vous créez le jeton d'accès, utilisez le champ d'application OAuth 2.0 https://www.googleapis.com/auth/cloud-platform.
Pour créer un jeton d'accès pour un compte de service, vous pouvez mettre en œuvre le flux OAuth 2.0 de serveur à serveur ou utiliser l'API Service Account Credentials pour générer un jeton d'accès OAuth 2.0.
Pour créer un jeton d'accès pour un utilisateur, consultez la page Obtenir des jetons d'accès OAuth 2.0. Vous pouvez également utiliser OAuth 2.0 Playground pour créer un jeton d'accès pour votre propre compte Google.
Échanger le jeton d'accès OAuth 2.0
Une fois le jeton d'accès OAuth 2.0 créé, vous pouvez l'échanger contre un nouveau jeton à champ d'application limité respectant la limite d'accès aux identifiants. Ce processus implique généralement un agent de service de jetons et un consommateur de jetons:
L'agent de service de jetons est chargé de définir les limites d'accès aux identifiants et d'échanger un jeton d'accès contre un jeton à champ d'application limité.
L'agent de service de jetons peut utiliser une bibliothèque d'authentification compatible pour échanger automatiquement des jetons d'accès, ou appeler Security Token Service pour échanger manuellement des jetons.
Le consommateur de jetons demande un jeton d'accès à champ d'application limité à l'agent de service de jetons, puis utilise ce jeton pour effectuer une autre action.
Le consommateur de jetons peut utiliser une bibliothèque d'authentification compatible pour actualiser automatiquement les jetons d'accès avant leur expiration. Il peut également actualiser les jetons manuellement ou laisser les jetons expirer sans les actualiser.
Il existe deux façons d'échanger le jeton d'accès contre un jeton d'accès limité :
Échange de jetons côté client (recommandé) : les clients obtiennent des éléments cryptographiques auprès du serveur d'API Security Token Service. Les éléments cryptographiques permettent aux clients de générer des jetons à champ d'application réduit avec différentes règles de limite d'accès aux identifiants, indépendamment du côté client, pour une durée définie (par exemple, une heure). Cette approche réduit la latence et améliore l'efficacité, en particulier pour les clients qui ont besoin de mises à jour fréquentes des règles de limite d'accès aux identifiants. Elle est également plus efficace pour les applications qui doivent générer de nombreux jetons uniques à champ d'application restreint. Il s'agit de l'approche recommandée, car elle offre de meilleures performances, une meilleure évolutivité et une compatibilité avec les fonctionnalités futures.
Échange de jetons côté serveur : les clients demandent un nouveau jeton à champ d'application restreint au serveur de l'API Security Token Service chaque fois qu'une règle de limite d'accès aux identifiants change. Cette approche est simple, mais nécessite un aller-retour vers le serveur d'API Security Token Service pour chaque requête de jeton à champ d'application réduit. Cette approche n'est recommandée que pour les clients qui ont besoin d'une bibliothèque cliente n'acceptant pas l'échange de jetons côté client, en raison de l'aller-retour vers l'API Security Token Service pour chaque requête de jeton à champ d'application réduit.
Échange de jetons côté client
Si vous créez l'agent de service de jetons et le consommateur de jetons dans le langage suivant, vous pouvez utiliser la bibliothèque d'authentification de Google pour échanger et actualiser automatiquement les jetons via l'approche côté client.
Java
Pour Java, vous pouvez échanger et actualiser automatiquement des jetons avec la version 1.32.1 ou une version ultérieure de l'artefact com.google.auth:google-auth-library-cab-token-generator.
Pour vérifier la version de votre artefact, exécutez la commande Maven suivante dans le répertoire de votre application :
mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator
L'exemple suivant montre comment un agent de service de jetons peut générer des jetons à champ d'application limité :
L'exemple suivant montre comment un consommateur de jetons peut utiliser un gestionnaire d'actualisation pour obtenir et actualiser automatiquement les jetons à champ d'application limité :
Échange de jetons côté serveur
Cette section décrit les méthodes suivantes que vous pouvez utiliser pour échanger des jetons via l'approche côté service :
- Échanger et actualiser automatiquement le jeton d'accès
- Échanger et actualiser manuellement le jeton d'accès
Échanger et actualiser automatiquement le jeton d'accès à l'aide de l'approche côté serveur
Si vous créez l'agent de service de jetons et le consommateur de jetons dans l'un des langages suivants, vous pouvez utiliser la bibliothèque d'authentification de Google pour échanger et actualiser automatiquement les jetons à l'aide de l'approche de génération de jetons côté serveur :
Go
Pour Go, vous pouvez échanger et actualiser automatiquement des jetons avec la version v0.0.0-20210819190943-2bc19b11175f ou une version ultérieure du package golang.org/x/oauth2.
Pour vérifier la version de votre package, exécutez la commande suivante dans le répertoire de votre application :
go list -m golang.org/x/oauth2
L'exemple suivant montre comment un agent de service de jetons peut générer des jetons à champ d'application limité :
L'exemple suivant montre comment un consommateur de jetons peut utiliser un gestionnaire d'actualisation pour obtenir et actualiser automatiquement les jetons à champ d'application limité :
Java
Pour Java, vous pouvez échanger et actualiser automatiquement des jetons avec la version 1.1.0 ou une version ultérieure de l'artefact com.google.auth:google-auth-library-oauth2-http.
Pour vérifier la version de votre artefact, exécutez la commande Maven suivante dans le répertoire de votre application :
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
L'exemple suivant montre comment un agent de service de jetons peut générer des jetons à champ d'application limité :
L'exemple suivant montre comment un consommateur de jetons peut utiliser un gestionnaire d'actualisation pour obtenir et actualiser automatiquement les jetons à champ d'application limité :
Node.js
Pour Node.js, vous pouvez échanger et actualiser automatiquement des jetons avec la version 7.9.0 ou une version ultérieure du package google-auth-library.
Pour vérifier la version de votre package, exécutez la commande suivante dans le répertoire de votre application :
npm list google-auth-library
L'exemple suivant montre comment un agent de service de jetons peut générer des jetons à champ d'application limité :
L'exemple suivant montre comment un consommateur de jetons peut fournir un gestionnaire d'actualisation qui obtient et actualise automatiquement les jetons à champ d'application limité :
Python
Pour Python, vous pouvez échanger et actualiser automatiquement des jetons avec la version 2.0.0 ou une version ultérieure du package google-auth.
Pour vérifier la version de votre package, exécutez la commande suivante dans l'environnement où le package est installé :
pip show google-auth
L'exemple suivant montre comment un agent de service de jetons peut générer des jetons à champ d'application limité :
L'exemple suivant montre comment un consommateur de jetons peut fournir un gestionnaire d'actualisation qui obtient et actualise automatiquement les jetons à champ d'application limité :
Échanger et actualiser manuellement le jeton d'accès
Un agent de jetons peut appeler la méthode sts.token de l'API Security Token Service (POST https://sts.googleapis.com/v1/token) pour échanger un jeton d'accès OAuth 2.0 contre un jeton d'accès à champ d'application restreint, puis fournir le jeton à champ d'application restreint à un consommateur de jetons.
La commande curl suivante échange un jeton d'accès à l'aide d'un fichier de limite d'accès aux identifiants au format JSON :
curl https://sts.googleapis.com/v1/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--request POST \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "subject_token=ORIGINAL_TOKEN" \
--data-urlencode "options=$(cat ACCESS_BOUNDARY_FILE)"
Remplacez les éléments suivants :
ORIGINAL_TOKEN: jeton d'accès OAuth 2.0 que vous souhaitez échanger.ACCESS_BOUNDARY_FILE: chemin d'accès au fichier contenant la limite d'accès aux identifiants au format JSON, par exemple./access-boundary.json.
Pour en savoir plus sur les paramètres de requête et les champs de réponse, consultez la documentation de référence de l'API REST sts.token.
Le résultat ressemble à ce qui suit :
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
Le champ expires_in n'apparaît que lorsque le jeton d'accès d'origine représente un compte de service. Lorsque le jeton d'accès d'origine représente un compte utilisateur, la réponse omet expires_in et le jeton d'accès limité expire en même temps que le jeton d'accès d'origine.
Lorsqu'un consommateur de jetons demande un jeton d'accès limité, l'agent de jetons répond en fournissant à la fois le jeton d'accès limité et le nombre de secondes avant son expiration. Si le jeton a expiré, le serveur rejette la requête. Pour actualiser le jeton à champ d'application restreint, le consommateur peut demander un jeton à champ d'application restreint à l'agent avant l'expiration du jeton existant.
Étapes suivantes
- Apprenez-en plus sur le contrôle des accès pour Cloud Storage.
- Créez un identifiant de compte de service éphémère.
- Créez un jeton d'accès OAuth 2.0 pour un compte de service à l'aide de l'une des méthodes suivantes :
- Créez un jeton d'accès OAuth 2.0 pour un utilisateur.
- Consultez les autorisations de chaque rôle prédéfini.
- Apprenez-en plus sur les rôles personnalisés.