Use custom organization policies for service accounts and service account keys

Google Cloud Organization Policy gives you centralized, programmaticcontrol over your organization's resources. As theorganization policy administrator, you can define an organization policy,which is a set of restrictions called constraints that apply toGoogle Cloud resources and descendants of those resources in theGoogle Cloud resource hierarchy. You can enforce organization policies atthe organization, folder, or project level.

Organization Policy providespredefined constraints for variousGoogle Cloud services. However, if you want more granular, customizablecontrol over the specific fields that are restricted in your organizationpolicies, you can also create custom organization policies.

Benefits

You can use custom organization policies to allow or deny specific operations onservice accounts and service account keys. For example, you can set a policy todeny the creation of a key with a certain origin, causing any requests to create a keywith that origin to fail and return an error to the user.

Policy inheritance

By default, organization policies are inherited by the descendants of theresources on which you enforce the policy. For example, if you enforce a policyon a folder, Google Cloud enforces the policy on all projects in thefolder. To learn more about this behavior and how to change it, refer toHierarchy evaluation rules.

Before you begin

Ensure that you know yourorganization ID.
If you want to test out custom organization policies that reference IAM resources, create a new project. Testing these organization policies in an existing project could disrupt security workflows.
1. In the Google Cloud console, go to the project selector page.
  Go to project selector
2. Select or create a Google Cloud project.
  Roles required to select or create a project
  - Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
  - Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
  Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Required roles

To get the permissions that you need to manage organization policies, ask your administrator to grant you the Organization policy administrator (roles/orgpolicy.policyAdmin) IAM role on the organization. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to manage organization policies. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to manage organization policies:

orgpolicy.constraints.list
orgpolicy.policies.create
orgpolicy.policies.delete
orgpolicy.policies.list
orgpolicy.policies.update
orgpolicy.policy.get
orgpolicy.policy.set

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Create a custom constraint

A custom constraint is defined in a YAML file by the resources, methods,conditions, and actions that are supported by the service on which you areenforcing the organization policy. Conditions for your custom constraints aredefined usingCommon Expression Language (CEL). For more information about how to buildconditions in custom constraints using CEL, see the CEL section ofCreating and managing custom constraints.

To create a YAML file for a custom constraint:

name:organizations/ORGANIZATION_ID/customConstraints/CONSTRAINT_NAMEresourceTypes:-iam.googleapis.com/RESOURCE_TYPEmethodTypes:-CREATE-UPDATEcondition:"CONDITION"actionType:ACTIONdisplayName:DISPLAY_NAMEdescription:DESCRIPTION

Replace the following:

ORGANIZATION_ID: your organization ID, such as123456789.
CONSTRAINT_NAME: the name you want for your newcustom constraint. A custom constraint must start withcustom., and canonly include uppercase letters, lowercase letters, or numbers, forexample, custom.denyServiceAccountCreation. The maximum length of this field is 70characters, not counting the prefix, for example,organizations/123456789/customConstraints/custom.
RESOURCE_TYPE: the name (not the URI) of theIdentity and Access Management API REST resource containing the object and fieldyou want to restrict. For example, ServiceAccount.
CONDITION: aCEL condition that is written againsta representation of a supported service resource. Thisfield has a maximum length of 1000 characters. SeeSupported resources for more information about theresources available to write conditions against. For example,"resource.description.contains('INVALID_DESCRIPTION')".
ACTION: the action to take if thecondition ismet. This can be eitherALLOW orDENY.
DISPLAY_NAME: a human-friendly name for theconstraint. This field has a maximum length of 200 characters.
DESCRIPTION: a human-friendly description of theconstraint to display as an error message when the policy is violated. Thisfield has a maximum length of 2000 characters.

For more information about how to create a custom constraint, seeDefining custom constraints.

Set up a custom constraint

After you have created the YAML file for a new custom constraint, you must set it up to makeit available for organization policies in your organization. To set up a custom constraint, usethegcloud org-policies set-custom-constraint command:

gcloudorg-policiesset-custom-constraintCONSTRAINT_PATH

ReplaceCONSTRAINT_PATH with the full path to yourcustom constraint file. For example,/home/user/customconstraint.yaml.Once completed, your custom constraints are available as organization policiesin your list of Google Cloud organization policies.To verify that the custom constraint exists, use thegcloud org-policies list-custom-constraints command:

gcloudorg-policieslist-custom-constraints--organization=ORGANIZATION_ID

ReplaceORGANIZATION_ID with the ID of your organization resource.For more information, seeViewing organization policies.

Enforce a custom organization policy

You can enforce a constraint by creating an organization policy that references it, and thenapplying that organization policy to a Google Cloud resource.

Console

In the Google Cloud console, go to theOrganization policies page.
Go to Organization policies
From the project picker, select the project for which you want to set the organization policy.
From the list on theOrganization policies page, select your constraint to view thePolicy details page for that constraint.
To configure the organization policy for this resource, clickManage policy.
On theEdit policy page, selectOverride parent's policy.
ClickAdd a rule.
In theEnforcement section, select whether enforcement of this organization policy is on or off.
Optional: To make the organization policy conditional on a tag, clickAdd condition. Note that if you add a conditional rule to an organization policy, you must add at least one unconditional rule or the policy cannot be saved. For more information, seeSetting an organization policy with tags.
ClickTest changes to simulate the effect of the organization policy. Policy simulation isn't available for legacy managed constraints. For more information, see Test organization policy changes with Policy Simulator.
To finish and apply the organization policy, clickSet policy. The policy requires up to 15 minutes to take effect.

gcloud

To create an organization policy with boolean rules, create a policy YAML file that references the constraint:

name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-enforce:true

Replace the following:

PROJECT_ID: the project on which you want to enforce your constraint.
CONSTRAINT_NAME: the name you defined for your custom constraint. For example,custom.denyServiceAccountCreation.

To enforce the organization policy containing the constraint, run the following command:

gcloudorg-policiesset-policyPOLICY_PATH

ReplacePOLICY_PATH with the full path to your organization policy YAML file. The policy requires up to 15 minutes to take effect.

Test the custom organization policy

Optionally, you can test the organization policy by setting the policy and thentrying to take an action that the policy should prevent.

This section describes how to test the following organization policy constraint:

name:organizations/ORG_ID/customConstraints/custom.denyServiceAccountCreationresourceTypes:iam.googleapis.com/ServiceAccountmethodTypes:-CREATE-UPDATEcondition:"resource.description.contains('INVALID_DESCRIPTION')"actionType:DENYdisplayName:Do not allow service account withINVALID_DESCRIPTION to be created.

If you want to test this custom constraint, do the following:

Copy the constraint into a YAML file and replace the following values:
- ORG_ID: the numeric ID of yourGoogle Cloud organization.
- INVALID_DESCRIPTION: the description that you want to use to test the custom constraint. While theconstraint is active, service accounts with a description containing this string won't be created on theproject that you enforce the constraint for.
Set up the custom constraint andenforce it for the project that you createdto test the custom organization policy constraint.
Ensure that you have theCreate Service Accounts role(roles/iam.serviceAccountCreator).
Try to create a service account with the description you included in the custom constraint. Before running the command, replace thefollowing values:
- SERVICE_ACCOUNT_NAME: The name of the service account
- INVALID_DESCRIPTION: The invalid string that will be checked for in the description of the service account
- DISPLAY_NAME: The service account name to display in the Google Cloud console

gcloudiamservice-accountscreateSERVICE_ACCOUNT_NAME\--description="INVALID_DESCRIPTION"--display-name="DISPLAY_NAME"

The output is the following:

Operation denied by custom org policy: ["customConstraints/custom.denyServiceAccountCreation": "Do not allow service account withINVALID_DESCRIPTION to be created."]

Identity and Access Management supported resources and operations

The following service account and service account key custom constraint fields are available to use when you create or update an account or key.

Service accounts
- resource.description
- resource.displayName
- resource.name
  - Format:projects/PROJECT_ID/serviceAccounts/UNIQUE_ID
Service account keys
- resource.keyOrigin
- resource.keyType
- resource.name
  - Format:projects/PROJECT_ID/serviceAccounts/UNIQUE_ID/keys/KEY_ID

Example custom organization policies for common use cases

The following table provides the syntax of some custom constraints for common use cases:

For more information about CEL macros available for use in custom constraint conditions, seeCommon Expression Language.

Description	Constraint syntax
Disable service account creation.	name:organizations/`ORGANIZATION_ID`/customConstraints/custom.disableServiceAccountCreationresourceTypes:-iam.googleapis.com/ServiceAccountmethodTypes:-CREATEcondition:"True"actionType:DENYdisplayName:Deny all service account creation.
Disable service account key creation.	name:organizations/`ORGANIZATION_ID`/customConstraints/custom.disableServiceAccountKeyCreationresourceTypes:-iam.googleapis.com/ServiceAccountKeymethodTypes:-CREATEcondition:"resource.keyType==USER_MANAGED&&resource.keyOrigin==GOOGLE_PROVIDED"actionType:DENYdisplayName:Deny all service account key creation.
Disable service account key upload.	name:organizations/`ORGANIZATION_ID`/customConstraints/custom.disableServiceAccountKeyUploadresourceTypes:-iam.googleapis.com/ServiceAccountKeymethodTypes:-CREATEcondition:"resource.keyType==USER_MANAGED&&resource.keyOrigin==USER_PROVIDED"actionType:DENYdisplayName:Deny all service account key uploads.

Description

Constraint syntax

Disable service account creation.

name:organizations/ORGANIZATION_ID/customConstraints/custom.disableServiceAccountCreationresourceTypes:-iam.googleapis.com/ServiceAccountmethodTypes:-CREATEcondition:"True"actionType:DENYdisplayName:Deny all service account creation.

Disable service account key creation.

name:organizations/ORGANIZATION_ID/customConstraints/custom.disableServiceAccountKeyCreationresourceTypes:-iam.googleapis.com/ServiceAccountKeymethodTypes:-CREATEcondition:"resource.keyType==USER_MANAGED&&resource.keyOrigin==GOOGLE_PROVIDED"actionType:DENYdisplayName:Deny all service account key creation.

Disable service account key upload.

name:organizations/ORGANIZATION_ID/customConstraints/custom.disableServiceAccountKeyUploadresourceTypes:-iam.googleapis.com/ServiceAccountKeymethodTypes:-CREATEcondition:"resource.keyType==USER_MANAGED&&resource.keyOrigin==USER_PROVIDED"actionType:DENYdisplayName:Deny all service account key uploads.

What's next

SeeIntroduction to the Organization Policy Service to learn more about organization policies.
Learn more about how tocreate and manage organization policies.
See the full list of predefinedorganization policy constraints.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-27 UTC.

Movatterモバイル変換

Use custom organization policies for service accounts and service account keys Stay organized with collections Save and categorize content based on your preferences.