Contrôle d'admission

Présentation

Cette page explique comment utiliser l'API Service Control v2 pour le contrôle d'admission des services gérés intégrés à Service Infrastructure. Il est destiné aux producteurs de services qui souhaitent exploiter Service Infrastructure pour leurs services.

Service Infrastructure est une plate-forme permettant aux développeurs de produire, gérer, sécuriser et utiliser des API et des services. Elle est basée sur un modèle d'utilisation de service simple et générique : un client utilise un service géré par un producteur. Toutes les API Google et les API Google Cloud utilisent ce modèle, car elles reposent également sur Service Infrastructure.

Lorsqu'un client accède à un service, toutes les entités impliquées dans l'accès nécessitent généralement une vérification de l'état et des règles, y compris le consommateur, le service, le producteur, l'utilisateur, l'application, le réseau et les ressources. Avec Service Infrastructure, ce processus est appelé "contrôle des admissions", qui inclut l'authentification, l'autorisation, l'audit, la limitation du débit, etc.

API Service Control v2

L'API Service Control v2 offre une méthode services.check simple qui fournit le contrôle d'admission à tous les services intégrés à Service Infrastructure. Cette méthode vous permet d'effectuer les opérations suivantes en un seul appel de méthode :

  • Vérification de l'état
    • État d'utilisation abusive
    • État de facturation
    • État du client
    • État du service
    • Activation des services
  • Authentification
    • Jeton d'accès Google OAuth
    • JWT signé avec un compte de service Google
  • Autorisation
  • Audits

Lorsqu'un service appelle l'API Service Control, le producteur est également client de l'API Service Control. Par conséquent, la méthode services.check effectue également le contrôle d'admission sur l'appel à l'API Service Control.

Pour qu'un service puisse appeler l'API Service Control, vous devez activer l'API Service Control sur le projet producteur et disposer des autorisations appropriées sur le service. Pour plus d'informations, consultez les pages Premiers pas des API Cloud et Contrôle des accès de Service Control.

Attributs de requête

Lorsqu'un client accède à un service, le service doit extraire l'accès en une ou plusieurs requêtes API pouvant être vérifiées avec le contrôle des admissions. Dans la plupart des cas, ces accès sont des requêtes API réelles. Dans d'autres cas, l'accès peut être des tâches d'importation de données complexes ou des requêtes SQL, et le service doit modéliser l'accès en fonction d'un ensemble de requêtes d'API virtuelles et effectuer un contrôle d'admission sur chaque requête.

Pour effectuer un contrôle d'admission à l'aide de l'API Service Control, le service doit appeler la méthode services.check avec les attributs de requête requis. Le tableau suivant répertorie les attributs nécessaires au contrôle d'admission. Pour obtenir la spécification complète, consultez la page AttributeContext.

Attribut Description Exemple
origin.ip Adresse IP de l'appelant "1.2.3.4"
api.service Nom du service API "endpointsapis.appspot.com"
api.operation Nom de la méthode API "google.example.hello.v1.HelloService.GetHello"
api.version Chaîne de version de l'API "v1"
api.protocol Nom du protocole API "https"
request.id ID de requête unique "123e4567-e89b-12d3-a456-426655440000"
request.time Heure de la requête "2019-07-31T05:20:00Z"
request.method Nom de la méthode HTTP "POST"
request.scheme Schéma d'URL "https"
request.host En-tête de l'hôte HTTP "endpointsapis.appspot.com"
request.path Chemin de l'URL "/v1/hello"
request.headers En-têtes de requête HTTP. Les en-têtes requis sont "authorization", "user-agent", "origin", "referer".

Attributs de ressource

Lorsqu'un client accède à un service, l'accès peut impliquer une ou plusieurs ressources au sein du service, telles que la lecture d'un objet ou la création d'une instance de VM. Le service peut utiliser le contrôle d'admission de Service Infrastructure pour le contrôle des accès aux ressources, compatible avec IAM et les journaux d'audit Cloud. Si votre service ne nécessite pas de contrôle d'accès, vous pouvez ignorer cette section.

Pour le contrôle des accès, un service doit transmettre des attributs de ressource à la méthode services.check avec les attributs de requête. Le tableau suivant montre les attributs de ressources requis pour le contrôle des accès.

Attribut Description Exemple
name Nom de la ressource "projects/123/locations/global/instances/instance-1"
type Type de la ressource au format "{service}/{Kind}" "endpointsapis.appspot.com/Instance"
permission Autorisation de la ressource au format "{service}/{kinds}.{verb}" "endpointsapis.appspot.com/instances.get"

Pour des performances et une efficacité optimales, la méthode services.check vous permet de vérifier plusieurs autorisations sur une seule ressource en un seul appel.

Effectuer un contrôle d'admission

Une fois que vous avez déployé votre configuration de service sur l'API Service Management et que votre service est prêt à répondre aux requêtes des clients, vous pouvez commencer à appeler services.check pour votre service déployé. Vous devez appeler services.check pour effectuer le contrôle d'admission chaque fois que votre service reçoit une requête.

Pour tester le contrôle d'admission rapidement, vous pouvez utiliser la commande gcurl afin d'appeler la méthode services.check. Consultez la page Premiers pas avec l'API Service Control pour connaître la procédure de configuration initiale.

L'exemple suivant montre comment utiliser la commande gcurl pour appeler services.check via HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "attributes": {
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.hello.v1.HelloService.GetHello",
      "version": "v1",
      "protocol": "https"
    }
  },
  "request": {
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "time": "2019-07-31T05:20:00Z",
    "scheme": "https",
    "host": "endpointsapis.appspot.com"
    "headers": {
      "authorization": "Bearer xxx",
      "user-agent": "curl/1.0"
    }
  },
  "resources": [
  ]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}

La réponse de la méthode services.check indique si le contrôle d'admission est passé. S'il est passé, la réponse doit être vide. En cas d'échec, l'élément status de la réponse contient des informations d'erreur que le service doit renvoyer au client. Le service doit souvent traduire les informations d'erreur dans son propre format. Le service peut également utiliser ces informations à des fins de journalisation et de surveillance.

Pour les services de production, vous devez utiliser l'une des bibliothèques clientes fournies par Google pour appeler l'API Service Control. Ces bibliothèques offrent une grande facilité d'utilisation et gèrent automatiquement les fonctionnalités courantes, telles que l'authentification. Pour en savoir plus, consultez la section Présentation des bibliothèques clientes.