If you use OS Login to manage access to your instances, you can set configurations at the organization level for your Cloud Identity account. For example, you can control who can directly use the OS Login API, enable OS Login for all VM instances in an organization, and grant access to external users.
This topic covers the following tasks:
- Enabling OS Login for an organization using an organization policy: Use an organization policy to ensure that all new VM instances in your organization have OS Login enabled.
- Granting instance access to users outside of your organization: Allow user accounts outside of your organization to use SSH to connect to your instances.
- Controlling access to the OS Login API: Allow or deny users access to use the OS Login API.
- Auditing OS Login events: Track OS Login-related events and activities such as adding, deleting, or updating an SSH key, or deleting POSIX information.
- Modifying user accounts using the Directory API: Update user properties, such as username and POSIX account information, by using the Directory API.
Before you begin
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
Enabling OS Login using an organization policy
You can set up an OS Login constraint in your organization to ensure that all new projects, and the VM instances created in these new projects, have OS Login enabled.
When this constraint is set up, the following conditions are applied:
enable-oslogin
is set totrue
in the project metadata for all new projects.- Update requests to set
enable-oslogin
tofalse
in instance or project metadata are rejected.
Limitations
- You cannot apply this constraint retroactively. OS Login is not automatically enabled on instances and projects that are created before the constraint is applied.
- Instances running in Google Kubernetes Engine do not support OS Login. Enabling the OS Login constraint prevents Google Kubernetes Engine clusters from creating new instances in projects where the constraint applies.
To enable the OS Login policy, you can set the OS Login constraint on
specific projects and folders by using the gcloud
command-line tool. You can also
set the OS Login constraint on the entire organization by using either
the Google Cloud Console or the gcloud
command-line tool.
Console
To set the OS Login organization policy from the console, complete the following steps:
- In the Google Cloud Console, go to the Organization policies page.
- In the policies list, click Require OS Login to view the OS Login constraints.
- Click Edit to edit your existing OS Login constraints.
- On the Edit page, select Customize.
- To enable enforcement of this constraint, select On.
- Click Save to apply the constraint settings.
gcloud
To set the OS Login organization policy, use the
gcloud beta resource-manager org-policies enable-enforce
command.
Find your organization ID.
gcloud organizations list
Set the constraint in your organization. Replace
organization-id
with your your organization ID.gcloud beta resource-manager org-policies enable-enforce compute.requireOsLogin \ --organization=organization-id
You can also apply the OS Login organization policy to a folder or a project
with the --folder
or the --project
flags, and the folder ID and project
ID, respectively.
For folders, run the following command:
gcloud beta resource-manager org-policies enable-enforce compute.requireOsLogin \ --folder=folder-id
For projects, run the following command:
gcloud beta resource-manager org-policies enable-enforce compute.requireOsLogin \ --project=project-id
Replace the following:
folder-id
: Your folder ID.project-id
: Your project ID.
Granting instance access to users outside of your organization
By default, users outside of your organization can't
set SSH keys for instances in your organization or be
granted access to instances in your organization. In
some situations, you might need to grant instance
access to users who are part of a different organization
or who have a consumer Google gmail.com
account.
The roles/compute.osLoginExternalUser
IAM role allows external Google Accounts to interact with the other
OS Login roles by allowing them to configure POSIX
account information.
To grant roles/compute.osLoginExternalUser
and other
necessary OS Login instance access roles to users outside
of your organization, complete the following steps:
- In the Google Cloud Console, go to the go to the project and organization selection page.
- In the Organization drop down menu, select your organization.
- Click All, to view all of your organizations.
- Click the name of the organization.
- Click Add to add a new role to a user.
- Specify the user name for the user for whom you want to configure instance access.
- Click Select a role to specify which roles you want to grant to the users.
- In the Compute Engine roles list, select the Compute OS Login External User role.
- Click Add to confirm that you want to grant the selected role to the user.
- If you have not already done so, grant the other OS Login instance access roles to the user at the project or organization level.
The user can now connect to instances in your project that have OS Login enabled.
Controlling access to the OS Login API
Members in your organization can use the OS Login API to modify their accounts. At an organization level, you can restrict access to the OS Login API by setting G Suite admin controls. To configure G Suite admin controls or view configuration options, see Control who uses Google Cloud in your organization.
Auditing OS Login events
As a G Suite Admin, you can use the G Suite Admin SDK to audit actions performed with the OS Login API. By reviewing these events, you can track when a user adds, deletes, or updates an SSH key, or deletes POSIX account information.
You can retrieve OS Login API audit activity events, from the G Suite Admin SDK,
by calling Activities.list()
with applicationName=gcp
. For more information,
see the
Cloud OS Login activity events section
in the G Suite Admin SDK Reports documentation.
Modifying user accounts using the Directory API
OS Login uses either your Cloud Identity or G Suite user settings when connecting to an instance. If you are an organization admin, you can use the Directory API to complete the following tasks for your G Suite or Cloud Identity user accounts:
- Modify instance login settings.
- Make a user an administrator
- Modify user properties such as account name and email
- Add and remove SSH keys for a user
- Modify POSIX account information
- Change the username that the users connect to on the instance.
For more information about the account properties that you can edit, see the Directory API reference.
For example, create a PUT
request to the
directory.users.update
method
and specify one or more properties to change on the user account:
PUT https://www.googleapis.com/admin/directory/v1/users/user-id-key { "posixAccounts": [ { "username": "user-name", "uid": "uid", "gid": "gid", "homeDirectory": "user-home-path", "shell": "shell-path" } ], }
Replace the following:
user-id-key
: An immutable ID for the user.user-name
: The username that Compute Engine adds to the instance for the user. This value must be unique within your organization.uid
: The user ID on the instance for this user. This property must be a value between1001
and60000
, or a value between65535
and2147483647
. To access a container-optimized OS, theUID
must have value between65536
and214748646
. TheUID
must be unique within your organization.gid
: The group ID on the instance that this user belongs to.user-home-path
: The home directory on the instance for this user. For example,/home/example_username
.shell-path
: The path to the default shell for the user after they connect to the instance. For example,/bin/bash
or/bin/sh
.
What's next
- Learn how to set up OS Login.
- Learn how to set up OS Login with two-factor authentication.
- Read an overview of the OS Login feature.