Introduction
This page describes how to use the Service Control API v2 for admission control for managed services that are integrated with Service Infrastructure. It is intended for service producers who want to deeply integrate their services with Google Cloud.
Service Infrastructure is a foundational platform for developers to produce, manage, secure and consume APIs and services. It uses a simple, generic service usage model: a consumer consumes a service managed by a producer. All Google APIs and Google Cloud APIs use this model, since they are also built on top of Service Infrastructure.
When a client accesses a service, all the entities involved in the access typically require a status and policy check, including the consumer, service, producer, user, application, network, and resources. With Service Infrastructure, this process is called admission control, which includes authentication, authorization, auditing, rate limiting, and more.
Service Control API v2
The Service Control API v2 provides a simple
services.check
method that
provides admission control to all services integrated with Service Infrastructure.
This method lets you do the following in a single method call:
- Status checking
- Abuse status
- Billing status
- Consumer status
- Service status
- Service enablement
- Authentication
- Google OAuth access token
- Google service account signed JWT
- Authorization
- Auditing
- Cloud Audit Logs. The audit log is associated with service "externalaudit.googleapis.com".
When a service calls the Service Control API, the producer is also a
consumer of the Service Control API. Therefore, the services.check
method also performs admission control on the call to the Service Control API.
In order for a service to call the Service Control API, you must enable the Service Control API on the producer project and have proper permissions on the service. For more information, see Cloud APIs Getting Started and Service Control Access Control.
Request attributes
When a client accesses a service, the service needs to abstract the access into one or more API requests that can be checked with admission control. In most cases, such accesses are indeed real API requests. In other cases, the access can be complicated data import jobs or SQL queries, and the service needs to model the access in terms of a set of virtual API requests and perform admission control on each request.
To perform admission control using the Service Control API, the service needs
to call the
services.check
method with required request attributes. The
following table lists the attributes needed for admission control.
For the complete specification, see
AttributeContext
.
Attibute | Description | Example |
---|---|---|
origin.ip |
The IP address of the caller. | "1.2.3.4" |
api.service |
The API service name. | "endpointsapis.appspot.com" |
api.operation |
The API method name. | "google.example.hello.v1.HelloService.GetHello" |
api.version |
The API version string. | "v1" |
api.protocol |
The API protocol name. | "https" |
request.id |
A unique request id. | "123e4567-e89b-12d3-a456-426655440000" |
request.time |
The time of the request. | "2019-07-31T05:20:00Z" |
request.method |
The HTTP method name. | "POST" |
request.scheme |
The URL scheme. | "https" |
request.host |
The HTTP host header. | "endpointsapis.appspot.com" |
request.path |
The URL path. | "/v1/hello" |
request.headers |
The HTTP request headers. The required headers are "authorization", "user-agent", "origin", "referer". | |
resource.name |
The target resource name. | "projects/123/topics/news-feed" |
Resource attributes
When a client accesses a service, the access may involve one or more resources inside the service, such as reading an object or creating a VM instance. The service can use Service Infrastructure admission control for access control on resources, supported by IAM and Cloud Audit Logs. If your service doesn't need access control, you can skip this section.
For access control, a service needs to pass resource attributes to the
services.check
method along with the request attributes.
The following table shows the resource attributes required for access control.
Attibute | Description | Example |
---|---|---|
name |
The resource name. | "projects/123/locations/global/instances/instance-1" |
type |
The resource type. The format is "{service}/{Kind}". | "endpointsapis.appspot.com/Instance" |
permission |
The resource permission. The format is "{service}/{kinds}.{verb}". | "endpointsapis.appspot.com/instances.get" |
For performance and efficiency, the services.check
method allows you to
check multiple permissions on a single resource in one call.
Performing admission control
Once you have deployed your service configuration to the Service Management
API and your service is ready to serve requests from clients, you can
begin calling services.check
for your deployed service. You should
call services.check
to perform admission control whenever your
service receives a request.
To quickly experiment with the admission control, you can use the gcurl
command to call the services.check
method. See
Getting Started with the Service Control API
for the initial setup steps.
The following example shows you how to use gcurl
command to call
services.check
over 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 { }
The response from the services.check
method indicates whether the admission
control has passed. If it passes, the response should be empty. If it fails,
the status
in the response contains error information that the service
should return to the client. The service often needs to translate the error
information to its own format. The service can also use the information
for logging and monitoring purposes.
For production services, you should use one of Google-provided client libraries to call the Service Control API. Such libraries provide great usability and handle common functionality automatically, such as authentication. For more information, see Client Libraries Explained.