- JSON representation
- Binding
- Expr
- AuditConfig
- AuditLogConfig
- LogType
- Rule
- Action
- Condition
- Attr
- Attr
- Operator
- LogConfig
- CounterOptions
- CustomField
- DataAccessOptions
- LogMode
- CloudAuditOptions
- LogName
- AuthorizationLoggingOptions
- PermissionType
- PermissionType
An Identity and Access Management (IAM) policy, which specifies access controls for Google Cloud resources.
A Policy
is a collection of bindings
. A binding
binds one or more members
, or principals, to a single role
. Principals can be user accounts, service accounts, Google groups, and domains (such as G Suite). A role
is a named list of permissions; each role
can be an IAM predefined role or a user-created custom role.
For some types of Google Cloud resources, a binding
can also specify a condition
, which is a logical expression that allows access to a resource only if the expression evaluates to true
. A condition can add constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the IAM documentation.
JSON example:
{
"bindings": [
{
"role": "roles/resourcemanager.organizationAdmin",
"members": [
"user:mike@example.com",
"group:admins@example.com",
"domain:google.com",
"serviceAccount:my-project-id@appspot.gserviceaccount.com"
]
},
{
"role": "roles/resourcemanager.organizationViewer",
"members": [
"user:eve@example.com"
],
"condition": {
"title": "expirable access",
"description": "Does not grant access after Sep 2020",
"expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
}
}
],
"etag": "BwWWja0YfJA=",
"version": 3
}
YAML example:
bindings:
- members:
- user:mike@example.com
- group:admins@example.com
- domain:google.com
- serviceAccount:my-project-id@appspot.gserviceaccount.com
role: roles/resourcemanager.organizationAdmin
- members:
- user:eve@example.com
role: roles/resourcemanager.organizationViewer
condition:
title: expirable access
description: Does not grant access after Sep 2020
expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
etag: BwWWja0YfJA=
version: 3
For a description of IAM and its features, see the IAM documentation.
JSON representation |
---|
{ "version": integer, "bindings": [ { object ( |
Fields | |
---|---|
version |
Specifies the format of the policy. Valid values are Any operation that affects conditional role bindings must specify version
Important: If you use IAM Conditions, you must include the If a policy does not include any conditions, operations on that policy may specify any valid version or leave the field unset. To learn which resources support conditions in their IAM policies, see the IAM documentation. |
bindings[] |
Associates a list of The |
auditConfigs[] |
Specifies cloud audit logging configuration for this policy. |
rules[] |
If more than one rule is specified, the rules are applied in the following manner: - All matching LOG rules are always applied. - If any DENY/DENY_WITH_LOG rule matches, permission is denied. Logging will be applied if one or more matching rule requires logging. - Otherwise, if any ALLOW/ALLOW_WITH_LOG rule matches, permission is granted. Logging will be applied if one or more matching rule requires logging. - Otherwise, if no rule applies, permission is denied. |
etag |
Important: If you use IAM Conditions, you must include the A base64-encoded string. |
Binding
Associates members
, or principals, with a role
.
JSON representation |
---|
{
"role": string,
"members": [
string
],
"condition": {
object ( |
Fields | |
---|---|
role |
Role that is assigned to the list of For an overview of the IAM roles and permissions, see the IAM documentation. For a list of the available pre-defined roles, see here. |
members[] |
Specifies the principals requesting access for a Google Cloud resource.
|
condition |
The condition that is associated with this binding. If the condition evaluates to If the condition evaluates to To learn which resources support conditions in their IAM policies, see the IAM documentation. |
bindingId |
|
Expr
Represents a textual expression in the Common Expression Language (CEL) syntax. CEL is a C-like expression language. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec.
Example (Comparison):
title: "Summary size limit"
description: "Determines if a summary is less than 100 chars"
expression: "document.summary.size() < 100"
Example (Equality):
title: "Requestor is owner"
description: "Determines if requestor is the document owner"
expression: "document.owner == request.auth.claims.email"
Example (Logic):
title: "Public documents"
description: "Determine whether the document should be publicly visible"
expression: "document.type != 'private' && document.type != 'internal'"
Example (Data Manipulation):
title: "Notification string"
description: "Create a notification string with a timestamp."
expression: "'New message received at ' + string(document.create_time)"
The exact variables and functions that may be referenced within an expression are determined by the service that evaluates it. See the service documentation for additional information.
JSON representation |
---|
{ "expression": string, "title": string, "description": string, "location": string } |
Fields | |
---|---|
expression |
Textual representation of an expression in Common Expression Language syntax. |
title |
Optional. Title for the expression, i.e. a short string describing its purpose. This can be used e.g. in UIs which allow to enter the expression. |
description |
Optional. Description of the expression. This is a longer text which describes the expression, e.g. when hovered over it in a UI. |
location |
Optional. String indicating the location of the expression for error reporting, e.g. a file name and a position in the file. |
AuditConfig
Specifies the audit configuration for a service. The configuration determines which permission types are logged, and what identities, if any, are exempted from logging. An AuditConfig must have one or more AuditLogConfigs.
If there are AuditConfigs for both allServices
and a specific service, the union of the two AuditConfigs is used for that service: the log_types specified in each AuditConfig are enabled, and the exemptedMembers in each AuditLogConfig are exempted.
Example Policy with multiple AuditConfigs:
{
"auditConfigs": [
{
"service": "allServices",
"auditLogConfigs": [
{
"logType": "DATA_READ",
"exemptedMembers": [
"user:jose@example.com"
]
},
{
"logType": "DATA_WRITE"
},
{
"logType": "ADMIN_READ"
}
]
},
{
"service": "sampleservice.googleapis.com",
"auditLogConfigs": [
{
"logType": "DATA_READ"
},
{
"logType": "DATA_WRITE",
"exemptedMembers": [
"user:aliya@example.com"
]
}
]
}
]
}
For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ logging. It also exempts jose@example.com
from DATA_READ logging, and aliya@example.com
from DATA_WRITE logging.
JSON representation |
---|
{
"service": string,
"auditLogConfigs": [
{
object ( |
Fields | |
---|---|
service |
Specifies a service that will be enabled for audit logging. For example, |
auditLogConfigs[] |
The configuration for logging of each type of permission. |
AuditLogConfig
Provides the configuration for logging a type of permissions. Example:
{
"auditLogConfigs": [
{
"logType": "DATA_READ",
"exemptedMembers": [
"user:jose@example.com"
]
},
{
"logType": "DATA_WRITE"
}
]
}
This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting jose@example.com from DATA_READ logging.
JSON representation |
---|
{
"logType": enum ( |
Fields | |
---|---|
logType |
The log type that this config enables. |
exemptedMembers[] |
Specifies the identities that do not cause logging for this type of permission. Follows the same format of |
ignoreChildExemptions |
|
LogType
The list of valid permission types for which logging can be configured. Admin writes are always logged, and are not configurable.
Enums | |
---|---|
LOG_TYPE_UNSPECIFIED |
Default case. Should never be this. |
ADMIN_READ |
Admin reads. Example: CloudIAM getIamPolicy |
DATA_WRITE |
Data writes. Example: CloudSQL Users create |
DATA_READ |
Data reads. Example: CloudSQL Users list |
Rule
A rule to be applied in a Policy.
JSON representation |
---|
{ "description": string, "permissions": [ string ], "action": enum ( |
Fields | |
---|---|
description |
Human-readable description of the rule. |
permissions[] |
A permission is a string of form ' |
action |
Required |
in[] |
If one or more 'in' clauses are specified, the rule matches if the PRINCIPAL/AUTHORITY_SELECTOR is in at least one of these entries. |
notIn[] |
If one or more 'notIn' clauses are specified, the rule matches if the PRINCIPAL/AUTHORITY_SELECTOR is in none of the entries. |
conditions[] |
Additional restrictions that must be met. All conditions must pass for the rule to match. |
logConfig[] |
The config returned to callers of CheckPolicy for any entries that match the LOG action. |
Action
Rule action types.
Enums | |
---|---|
NO_ACTION |
Default no action. |
ALLOW |
Matching 'Entries' grant access. |
ALLOW_WITH_LOG |
Matching 'Entries' grant access and the caller promises to log the request per the returned log_configs. |
DENY |
Matching 'Entries' deny access. |
DENY_WITH_LOG |
Matching 'Entries' deny access and the caller promises to log the request per the returned log_configs. |
LOG |
Matching 'Entries' tell IAM.Check callers to generate logs. |
Condition
A condition to be met.
JSON representation |
---|
{ "op": enum ( |
Fields | |
---|---|
op |
An operator to apply the subject with. |
values[] |
The objects of the condition. |
Union field Subject . Condition subject. Subject can be only one of the following: |
|
iam |
Trusted attributes supplied by the IAM system. |
sys |
Trusted attributes supplied by any service that owns resources and uses the IAM system for access control. |
svc |
Trusted attributes discharged by the service. |
Attr
Attribute types.
Enums | |
---|---|
NO_ATTR |
Default non-attribute. |
AUTHORITY |
Either principal or (if present) authority selector. |
ATTRIBUTION |
The principal (even if an authority selector is present), which must only be used for attribution, not authorization. |
SECURITY_REALM |
Any of the security realms in the IAMContext (go/security-realms). When used with IN, the condition indicates "any of the request's realms match one of the given values; with NOT_IN, "none of the realms match any of the given values". Note that a value can be: - 'self:campus' (i.e., clients that are in the same campus) - 'self:metro' (i.e., clients that are in the same metro) - 'self:cloud-region' (i.e., allow connections from clients that are in the same cloud region) - 'self:prod-region' (i.e., allow connections from clients that are in the same prod region) - 'guardians' (i.e., allow connections from its guardian realms. See go/security-realms-glossary#guardian for more information.) - 'self' [DEPRECATED] (i.e., allow connections from clients that are in the same security realm, which is currently but not guaranteed to be campus-sized) - a realm (e.g., 'campus-abc') - a realm group (e.g., 'realms-for-borg-cell-xx', see: go/realm-groups) A match is determined by a realm group membership check performed by a RealmAclRep object (go/realm-acl-howto). It is not permitted to grant access based on the absence of a realm, so realm conditions can only be used in a "positive" context (e.g., ALLOW/IN or DENY/NOT_IN). |
APPROVER |
An approver (distinct from the requester) that has authorized this request. When used with IN, the condition indicates that one of the approvers associated with the request matches the specified principal, or is a member of the specified group. Approvers can only grant additional access, and are thus only used in a strictly positive context (e.g. ALLOW/IN or DENY/NOT_IN). |
JUSTIFICATION_TYPE |
What types of justifications have been supplied with this request. String values should match enum names from security.credentials.JustificationType, e.g. "MANUAL_STRING". It is not permitted to grant access based on the absence of a justification, so justification conditions can only be used in a "positive" context (e.g., ALLOW/IN or DENY/NOT_IN). Multiple justifications, e.g., a Buganizer ID and a manually-entered reason, are normal and supported. |
CREDENTIALS_TYPE |
What type of credentials have been supplied with this request. String values should match enum names from security_loas_l2.CredentialsType - currently, only CREDS_TYPE_EMERGENCY is supported. It is not permitted to grant access based on the absence of a credentials type, so the conditions can only be used in a "positive" context (e.g., ALLOW/IN or DENY/NOT_IN). |
CREDS_ASSERTION |
EXPERIMENTAL -- DO NOT USE. The conditions can only be used in a "positive" context (e.g., ALLOW/IN or DENY/NOT_IN). |
Attr
Attribute types.
Enums | |
---|---|
NO_ATTR |
Default non-attribute type |
REGION |
Region of the resource |
SERVICE |
Service name |
NAME |
Resource name |
IP |
IP address of the caller |
Operator
Condition operator types.
Enums | |
---|---|
NO_OP |
Default no-op. |
EQUALS |
DEPRECATED. Use IN instead. |
NOT_EQUALS |
DEPRECATED. Use NOT_IN instead. |
IN |
The condition is true if the subject (or any element of it if it is a set) matches any of the supplied values. |
NOT_IN |
The condition is true if the subject (or every element of it if it is a set) matches none of the supplied values. |
DISCHARGED |
Subject is discharged |
LogConfig
Specifies what kind of log the caller must write
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field type . Must be set type can be only one of the following: |
|
counter |
Counter options. |
dataAccess |
Data access options. |
cloudAudit |
Cloud audit options. |
CounterOptions
Increment a streamz counter with the specified metric and field names.
Metric names should start with a '/', generally be lowercase-only, and end in "_count". Field names should not contain an initial slash. The actual exported metric names will have "/iam/policy" prepended.
Field names correspond to IAM request parameters and field values are their respective values.
Supported field names: - "authority", which is "[token]" if IAMContext.token is present, otherwise the value of IAMContext.authority_selector if present, and otherwise a representation of IAMContext.principal; or - "iamPrincipal", a representation of IAMContext.principal even if a token or authority selector is present; or - "" (empty string), resulting in a counter with no fields.
Examples: counter { metric: "/debug_access_count" field: "iamPrincipal" } ==> increment counter /iam/policy/debug_access_count {iamPrincipal=[value of IAMContext.principal]}
JSON representation |
---|
{
"metric": string,
"field": string,
"customFields": [
{
object ( |
Fields | |
---|---|
metric |
The metric to update. |
field |
The field value to attribute. |
customFields[] |
Custom fields. |
CustomField
Custom fields. These can be used to create a counter with arbitrary field/value pairs. See: go/rpcsp-custom-fields.
JSON representation |
---|
{ "name": string, "value": string } |
Fields | |
---|---|
name |
Name is the field name. |
value |
Value is the field value. It is important that in contrast to the CounterOptions.field, the value here is a constant that is not derived from the IAMContext. |
DataAccessOptions
Write a Data Access (Gin) log
JSON representation |
---|
{
"logMode": enum ( |
Fields | |
---|---|
logMode |
|
isDirectAuth |
Indicates that access was granted by a regular grant policy |
LogMode
Specifies client behavior wrt Gin logging.
Enums | |
---|---|
LOG_MODE_UNSPECIFIED |
Client is not required to write a partial Gin log immediately after the authorization check. If client chooses to write one and it fails, client may either fail open (allow the operation to continue) or fail closed (handle as a DENY outcome). |
LOG_FAIL_CLOSED |
The application's operation in the context of which this authorization check is being made may only be performed if it is successfully logged to Gin. For instance, the authorization library may satisfy this obligation by emitting a partial log entry at authorization check time and only returning ALLOW to the application if it succeeds. If a matching Rule has this directive, but the client has not indicated that it will honor such requirements, then the IAM check will result in authorization failure by setting CheckPolicyResponse.success=false. |
CloudAuditOptions
Write a Cloud Audit log
JSON representation |
---|
{ "logName": enum ( |
Fields | |
---|---|
logName |
The logName to populate in the Cloud Audit Record. |
authorizationLoggingOptions |
Information used by the Cloud Audit Logging pipeline. Will be deprecated once the migration to PermissionType is complete (b/201806118). |
permissionType |
The type associated with the permission. |
LogName
Enum of log names.
Enums | |
---|---|
UNSPECIFIED_LOG_NAME |
Default. Should not be used. |
ADMIN_ACTIVITY |
Corresponds to "cloudaudit.googleapis.com/activity" |
DATA_ACCESS |
Corresponds to "cloudaudit.googleapis.com/dataAccess" |
AuthorizationLoggingOptions
Authorization-related information used by Cloud Audit Logging.
JSON representation |
---|
{
"permissionType": enum ( |
Fields | |
---|---|
permissionType |
The type of the permission that was checked. |
PermissionType
The list of valid permission types that can be checked.
Enums | |
---|---|
PERMISSION_TYPE_UNSPECIFIED |
Default. Should not be used. |
ADMIN_READ |
A read of admin (meta) data. |
ADMIN_WRITE |
A write of admin (meta) data. |
DATA_READ |
A read of standard data. |
DATA_WRITE |
A write of standard data. |
PermissionType
The list of valid permission types that can be checked.
Enums | |
---|---|
PERMISSION_TYPE_UNSPECIFIED |
Default. Should not be used. |
ADMIN_READ |
Permissions that gate reading resource configuration or metadata. |
ADMIN_WRITE |
Permissions that gate modification of resource configuration or metadata. |
DATA_READ |
Permissions that gate reading user-provided data. |
DATA_WRITE |
Permissions that gate writing user-provided data. |