To invoke the Service Control API for a managed service, the caller must have the following Identity and Access Management (IAM) permissions on the service:
services.check
requires permissionservicemanagement.services.check
.services.report
requires permissionservicemanagement.services.report
.services.allocateQuota
requires permissionservicemanagement.services.quota
.
The IAM roles roles/servicemanagement.serviceController
,
roles/owner
and roles/editor
include these permissions and can each be used
to grant them. We recommend using the IAM role
roles/servicemanagement.serviceController
to run your managed services. While
roles/owner
and roles/editor
also grant these permissions, the narrower role
is better for security reasons.
Resource model
IAM applies IAM policies on resources to control who can perform what actions on the resources. The Service Control API uses the following resources to provide its functionality:
- Service producer project: A service producer project may own zero or more managed services. The service producer project is the parent of services in this hierarchy.
- Managed service: A managed service may have zero or more service consumers.
- Service consumer: A service consumer refers to a Google Cloud project that has enabled the service.
The IAM access control is applied to the resource model. If a role is granted at the service producer project level, it affects all managed services owned by the producer project. If a role is granted at the managed service level, it affects all service consumers of the managed service.
It is highly recommended that you only create one managed service per service producer project for security and isolation reasons. Otherwise, for example, if the service producer project runs out of quota for sending requests to the Service Control API, multiple managed services will be impacted.
If you have a multi-tenant service, you should grant the role
roles/servicemanagement.serviceController
at the managed service
level. If you have a single-tenant service, in other words, a service where
each service consumer gets its own instance of your managed service, you should
grant the role at the service consumer level. For background data processing
that affects all service consumers, you should grant the role at the managed
service level.
Grant roles
To call the Service Control API, you must grant the necessary roles to the callers. You can grant the roles via one of the following three approaches. You need to be an owner of the service producer project so that you can grant the necessary roles.
Grant a role at the service producer project level
You can grant the necessary roles on the project that a managed service belongs to, following the instructions in Granting, changing, and revoking access to resources, or use the Google Cloud CLI add-iam-policy-binding command to grant the roles.
For example, you can grant the roles to a service account, such as
foo@developer.gserviceaccount.com
:
gcloud projects add-iam-policy-binding PRODUCER_PROJECT_ID --member serviceAccount:SERVICE_ACCOUNT --role roles/servicemanagement.serviceController
Similarly, you can grant the roles to a user account, such as bar@gmail.com
:
gcloud projects add-iam-policy-binding PRODUCER_PROJECT_ID --member user:USER_ACCOUNT --role roles/servicemanagement.serviceController
Grant a role at the service level
You can grant the role roles/servicemanagement.serviceController
at the
service level using curl
. The following example uses the gcurl
alias
defined in the
Test with curl
section of the Getting started guide:
gcurl -d "{ 'policy': { 'bindings': [ { role: 'roles/servicemanagement.serviceController', members: 'serviceAccount:SERVICE_ACCOUNT' } ] } }" https://servicemanagement.googleapis.com/v1/services/YOUR_SERVICE_NAME:setIamPolicy
Please note the above example will replace all existing service level IAM policies. To grant the new role incrementally, you need to include all IAM policies in the request body.
Grant a role at the service consumer level
You can grant the role roles/servicemanagement.serviceController
at the
service consumer level. Service consumer level permissions require that the
request to the Service Control API must contain at least one valid
service consumer project ID. The following example uses the gcurl
alias
defined in the
Test with curl
section of the Getting started guide:
gcurl -d "{ 'policy': { 'bindings': [ { role: 'roles/servicemanagement.serviceController', members: 'serviceAccount:SERVICE_ACCOUNT' } ] } }" https://servicemanagement.googleapis.com/v1/services/YOUR_SERVICE_NAME/consumers/CONSUMER_PROJECT_NUMBER:setIamPolicy
Please note the above example will replace all existing consumer project level IAM policies. To grant the new role incrementally, you need to include all IAM policies in the request body.
For more information, see Cloud Auth Guide.