Controle de admissão

Introdução

Nesta página, você verá como usar a API Service Control v2 para controle de admissão para serviços gerenciados integrados à infraestrutura de serviços. Ela é destinada a produtores de serviços que querem integrar profundamente os próprios serviços ao Google Cloud.

A infraestrutura de serviços é uma plataforma fundamental para os desenvolvedores produzirem, gerenciarem, protegerem e consumirem APIs e serviços. Ela usa um modelo de uso de serviço simples e genérico: um consumidor consome um serviço gerenciado por um produtor. Todas as APIs do Google e as APIs do Google Cloud usam esse modelo, pois também são construídas sobre a Service Control.

Quando um cliente acessa um serviço, todas as entidades envolvidas no acesso normalmente exigem uma verificação de status e política, incluindo consumidor, serviço, produtor, usuário, aplicativo, rede e recursos. Com a infraestrutura de serviços, esse processo é chamado de controle de admissão, que inclui autenticação, autorização, auditoria, limitação de taxa e muito mais.

Observação :para ver a terminologia usada nesta página, consulte o Glossário da API.

API Service Control v2

A API Service Control v2 fornece um método services.check simples que fornece controle de admissão a todos os serviços integrados à infraestrutura de serviço. Este método permite fazer o seguinte em uma única chamada de método:

• Verificação de status
  • Status de abuso
  • Status do faturamento
  • Status do consumidor
  • Status do serviço
  • Ativação do serviço
• Autenticação
  • Token de acesso Google OAuth
  • Conta de serviço do Google assinada com JWT
• Autorização
  • Gerenciamento de identidade e acesso (IAM)
• Auditoria
  • Cloud Audit Logs O registro de auditoria está associado ao serviço "externalaudit.googleapis.com".

Quando um serviço chama a API Service Control, o produtor também é um consumidor API Service Control. Portanto, o método services.check também executa o controle de admissão na chamada à API Service Control.

Para que um serviço chame a API Service Control, você precisa habilitar a API Service Control no projeto de produtor e ter permissões apropriadas no serviço. Para obter mais informações, consulte Introdução às APIs do Cloud e Controle de acesso da Service Control.

Atributos de solicitação

Quando um cliente acessa um serviço, o serviço precisa abstrair o acesso em uma ou mais solicitações de API que podem ser verificadas com controle de admissão. Na maioria dos casos, esses acessos são solicitações de API reais. Em outros casos, o acesso pode ser jobs complicados de importação de dados ou consultas SQL, e o serviço precisa modelar o acesso em termos de um conjunto de solicitações de API virtuais e executar o controle de admissão em cada solicitação.

Para executar o controle de admissão usando a API Service Control, o serviço precisa chamar o método services.check com os atributos de solicitação necessários. A tabela a seguir lista os atributos necessários para o controle de admissão. Para a especificação completa, consulte AttributeContext.

Atributo	Descrição	Exemplo
origin.ip	O endereço IP do autor da chamada.	"1.2.3.4"
api.service	O nome do serviço da API.	"endpointsapis.appspot.com"
api.operation	O nome do método da API.	"google.example.hello.v1.HelloService.GetHello"
api.version	A string da versão da API.	"v1"
api.protocol	O nome do protocolo da API.	"https"
request.id	Um ID de solicitação exclusivo.	"123e4567-e89b-12d3-a456-426655440000"
request.time	A hora da solicitação.	"2019-07-31T05:20:00Z"
request.method	O nome do método HTTP.	"POST"
request.scheme	O esquema de URL.	"https"
request.host	O cabeçalho do host HTTP.	"endpointsapis.appspot.com"
request.path	O caminho da URL.	"/v1/hello"
request.headers	Os cabeçalhos de solicitação HTTP. Os cabeçalhos necessários são "autorização", "agente de usuário", "origem", "referenciador".
resource.name	O nome do recurso de destino.	"projects/123/topics/news-feed"

Atributos de recurso

Quando um cliente acessa um serviço, o acesso pode envolver um ou mais recursos dentro do serviço, como ler um objeto ou criar uma instância de VM. O serviço pode usar o controle de admissão da Service Infrastructure para controle de acesso aos recursos, suportado por IAM e Cloud Audit Logging. Se você não precisar de controle de acesso no serviço, pule esta seção.

Para controle de acesso, um serviço precisa transmitir atributos de recurso ao método services.check junto com os atributos de solicitação. A tabela a seguir mostra os atributos de recurso necessários para o controle de acesso.

Atributo	Descrição	Exemplo
name	O nome do recurso.	"projects/123/locations/global/instances/instance-1"
type	O tipo de recurso. O formato é "{service}/{Kind}".	"endpointsapis.appspot.com/Instance"
permission	A permissão do recurso. O formato é "{service}/{types}.{Verb}".	"endpointsapis.appspot.com/instances.get"

Para desempenho e eficiência, o método services.check permite verificar várias permissões em um único recurso em uma chamada.

Como executar o controle de admissão

Depois de implantar a configuração de serviço na API Service Infrastructure e o serviço estiver pronto para atender solicitações de clientes, você poderá começar a chamar services.check para o serviço implantado. Chame services.check para executar o controle de admissão sempre que seu serviço receber uma solicitação.

Para experimentar rapidamente o controle de admissão, você pode usar o comando gcurl para chamar o método services.check. Consulte Primeiros passos com a API Service Control para conhecer as etapas de configuração inicial.

O exemplo a seguir mostra como usar o comando gcurl para chamar services.check sobre 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
{
}

A resposta do método services.check indica se o controle de admissão foi transmitido. Se for transmitido, a resposta precisa estar vazia. Se falhar, o status na resposta conterá informações de erro que o serviço deve retornar ao cliente. O serviço geralmente precisa converter as informações de erro em seu próprio formato. O serviço também pode usar as informações para fins de geração de registros e monitoramento.

Para serviços de produção, use uma das bibliotecas de clientes fornecidas pelo Google para chamar a API Service Control. Essas bibliotecas oferecem excelente usabilidade e lidam com funcionalidades comuns automaticamente, como autenticação. Para mais informações, veja as Explicações sobre bibliotecas de clientes.