GoogleDriveManagement/wiki/Cloud-Identity-Policies.md

# Cloud Identity Policies
- [API documentation](#api-documentation)
- [Notes](#notes)
- [Python Regular Expressions](Python-Regular-Expressions) Match function
- [Definitions](#definitions)
- [Policies](#policies)
- [Display Cloud Identity Policies](#display-cloud-identity-policies)
- [Create and Update Cloud Identity Policies](#create-and-update-cloud-identity-policies)
- [Delete Cloud Identity Policies](#delete-cloud-identity-policies)

## API documentation
* [Policy API](https://cloud.google.com/identity/docs/reference/rest/v1/policies)
* [Policy Settings](https://cloud.google.com/identity/docs/concepts/supported-policy-api-settings)

## Notes
To use these commands you must update your client access authentication.
You'll enter 23 or 23r to turn on the Cloud Identity Policy scope; then continue
with authentication.
```
gam oauth delete
gam oauth create
...
[R] 23)  Cloud Identity - Policy (supports readonly)
```
You must enable access to policies in the GCP cloud console.

* Login at console.cloud.google.com
* In the upper left click the three lines to the left of Google Cloud and select IAM & Admin
* Under IAM & Admin select IAM
* Click in the box to the right of Google Cloud
* Click the three dots at the right and select IAM/Permissions
* Now you should be at "Permissions for organization ..."
* Click on Grant Access
* Enter the GAM project creator address in Principals
* Click in the Select a role box
* Type orgpolicy.policyAdmin in the Filter box
* Click Organization Policy Administrator
* Click Save

The commands to create, update and delete Cloud Identity policies for data loss prevention (DLP) rules and detectors
were added in version `7.46.00`.

## Definitions
```
<CIPolicyName> ::= policies/<String>|settings/<String>|<String>
<CIPolicyNameList> ::= "<CIPolicyName>(,<CIPolicyName>)*"
<CIPolicyNameEntity> ::=
        <CIPolicyNameList> | <FileSelector> | <CSVFileSelector>

<RegularExpression> ::= <String>
        See: https://docs.python.org/3/library/re.html
<REMatchPattern> ::= <RegularExpression>
<RESearchPattern> ::= <RegularExpression>
<RESubstitution> ::= <String>>
```

## Policies
These are the supported policies GAM can show today.

See: https://cloud.google.com/identity/docs/concepts/supported-policy-api-settings

## Display Cloud Identity Policies
Display selected policies.
```
gam info policies <CIPolicyEntity>
        [nowarnings] [noappnames] [noidmappimg]
        [formatjson]
```

Select policies::
* `polices/<String>` - A policy name, `policies/ahv4hg7qc24kvaghb7zihwf4riid4`
* `settings/<String>` - A policy setting type, `settings/workspace_marketplace.apps_allowlist`
* `<String>` - A policy setting type, `workspace_marketplace.apps_allowlist`

By default, policy warnings are displayed, use the `nowarnings` option to suppress their display.

By default, additional API calls are made for `settings/workspace_marketplace.apps_allowlist`
to get the application name for the application ID. Use option `noappnames` to suppress these calls.

By default, additional API calls are made to add the `policyQuery/groupEmail` and `policyQuery/orgUnitPath` fields
that are mapped from the `policyQuery/group` and `policyQuery/orgUnit` fields. Use option `noidmapping'
to suppress these calls and not add the additional fields.

By default, Gam displays the information as an indented list of keys and values.
* `formatjson` - Display the fields in JSON format.

Display all or filtered policies.
```
gam show policies
        [filter <String>] [nowarnings] [noappnames] [noidmappimg]
        [group <REMatchPattern>] [ou|org|orgunit <REMatchPattern>]
        [formatjson]
```
By default, all policies are displayed.
* `filter <String>` - Display filtered policies, See https://cloud.google.com/identity/docs/reference/rest/v1/policies/list
* `group <REMatchPattern>` - Only display policies whose group email address matches the `<REMatchPattern>`
* `ou|org|orgunit <REMatchPattern>` - Only display policies whose OU path matches the `<REMatchPattern>`

By default, policy warnings are displayed, use the `nowarnings` option to suppress their display.

By default,  additional API calls are made for `settings/workspace_marketplace.apps_allowlist`
to get the application name for the application ID. Use option `noappnames` to suppress these calls.

By default, additional API calls are made to add the `policyQuery/groupEmail` and `policyQuery/orgUnitPath` fields
that are mapped from the `policyQuery/group` and `policyQuery/orgUnit` fields. Use option `noidmapping'
to suppress these calls and not add the additional fields.

By default, Gam displays the information as an indented list of keys and values.
* `formatjson` - Display the fields in JSON format.

```
gam print policies [todrive <ToDriveAttribute>*]
        [filter <String>] [nowarnings] [noappnames] [noidmappimg]
        [group <REMatchPattern>] [ou|org|orgunit <REMatchPattern>]
        [formatjson [quotechar <Character>]]
```
By default, all policies are displayed:
* `filter <String>` - Display filtered policies, See https://cloud.google.com/identity/docs/reference/rest/v1/policies/list
* `group <REMatchPattern>` - Only display policies whose group email address matches the `<REMatchPattern>`
* `ou|org|orgunit <REMatchPattern>` - Only display policies whose OU path matches the `<REMatchPattern>`

By default, policy warnings are displayed, use the `nowarnings` option to suppress their display.

By default, additional API calls are made to add the `policyQuery/groupEmail` and `policyQuery/orgUnitPath` fields
that are mapped from the `policyQuery/group` and `policyQuery/orgUnit` fields. Use option `noidmapping'
to suppress these calls and not add the additional fields.

By default,  additional API calls are made for `settings/workspace_marketplace.apps_allowlist`
to get the application name for the application ID. Use option `noappnames` to suppress these calls.

By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,
* `formatjson` - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output.
The `quotechar <Character>` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
`quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used.

### Examples
Print all service status policies.
```
gam redirect csv ./ServiceStatusPolicies.csv print policies filter "setting.type.matches('.*service_status')"
```

Print Drive external sharing policies.
```
gam redirect csv ./DriveExternalSharingPolicies.csv print policies filter "setting.type.matches('settings/drive_and_docs.external_sharing')"
```

Print all polices that apply directly to the OU "/Staff".
```
gam redirect csv ./StaffPolicies.csv print policies ou "^/Staff$"
```

Print all polices that apply to the OU "/Staff" and its sub-OUs.
```
gam redirect csv ./StaffPolicies.csv print policies ou "^/Staff"
```

## Create and Update Cloud Identity Policies
Policies can be complex objects, it is probably easiest to create template policies in the Admin console (under Rules),
output the JSON format data for those policies to be used in subsequent create and update commands.

```
gam create policy
        json <JSONData>
        [(ou|orgunit <OrgUnitItem>)|(group <GroupItem>)|(query <String>)]
gam update policy
        json <JSONData>
        [(ou|orgunit <OrgUnitItem>)|(group <GroupItem>)|(query <String>)]
```
```
gam redirect stdout ./policy.json info policies policies/akajj264aoclblvncu
Make changes to policy.json and update the policy.
gam update policy json file policy.json

Update the policy to reference a different group.
gam update policy json file policy.json group <EmailAddress>

Make changes to policy.json and create a new policy in a different OU.
gam create policy json file policy.json ou <OrgUnitPath>
```

## Delete Cloud Identity Policies
```
gam delete policies <CIPolicyNameEntity>
```