Creating User Accounts

Create user accounts for your Linux virtual machine instances so users can connect to instances using a unique username and be given a personal home directory to perform necessary tasks.

A user account can be assigned to anyone who has read access to your project. In particular, user accounts are useful for granting project viewers SSH access to your instances, without giving them additional permissions as an editor or owner. If you have project viewers who need to connect to virtual machine instances using SSH, create a user account for them.

You can manage user accounts programmatically through gcloud or the API, or through the Google Cloud Platform Console.

Before you begin

Specifications

Restrictions

User accounts are available only on the following operating system images:

  • Debian 8
  • Ubuntu 14.04
  • Ubuntu 14.10
  • Ubuntu 15.04

Read the Setup section for installation instructions.

You cannot connect to an instance using SSH from a Browser with a user account. SSH from a browser will automatically use SSH credentials from the metadata server and ignore user accounts.

Roles

This document describes two different account roles:

Google Cloud Platform Console Owner or Editor—A Cloud Platform Console project owner or editor creates and deletes new user accounts. However, unless the project owner or editor is also the account owner, they cannot add or remove SSH keys for a user account.

For information on projects and roles, see Managing projects in the Cloud Platform Console.

Account Owner—An account owner can upload or delete SSH keys for an account and use the account to connect to virtual machine instances. Any project member, including project viewers, can be made an account owner during account creation. Being the owner of an account does not grant permission to delete the account or create other user accounts; you must be a project owner or editor to delete or create accounts.

Root access

All Linux user accounts in your project are granted root access to your instances. By default, new Linux user accounts are added to the following user groups upon account creation:

  • gce-sudoers - Gives root access
  • gce-users - General users group

The gce-sudoers group is automatically maintained by the Cloud User Accounts service and contains every Linux user account in your project. If you wanted to restrict root access to certain accounts, remove the default policy at:

/etc/sudoers.d/gcua

Next, create your own group and add a configuration similar to the gcua file in the sudoers.d folder.

Quotas

User accounts are subject to the following quotas:

  • 500 user accounts per project
  • 50 public keys per user account
  • 50 groups per project

Setup

This feature assumes you have enabled Compute Engine. To setup user accounts:

  1. If you do not already have access to the User Accounts feature, request to be whitelisted.

  2. Install the gcloud beta component. Follow the instructions for downloading and installing gcloud. Next, enable the beta component by running:

    gcloud components update beta
    
  3. User accounts are recognized only on instances that have been enabled to use user accounts. To create an instance that recognizes user accounts, enable the cloud.useraccounts.readonly API scope as well as the other default API scopes. Additionally, you must run a startup script that enables user accounts. The startup script is located in the following Cloud Storage bucket:

    gs://gcua-beta/startup.sh
    

    When you create the instance, specify the startup script using the --metadata flag with empty ssh-keys and sshKeys values. Additionally, specify the cloud.useraccounts.readonly scope in addition to the default scopes with the --scopes flag. For example:

    gcloud compute instances create example-instance --image debian-8 \
    --metadata startup-script-url=gs://gcua-beta/startup.sh,ssh-keys="",sshKeys="" \
    --scopes https://www.googleapis.com/auth/cloud.useraccounts.readonly,\
    https://www.googleapis.com/auth/devstorage.read_only,\
    https://www.googleapis.com/auth/logging.write,\
    https://www.googleapis.com/auth/monitoring.write,\
    https://www.googleapis.com/auth/service.management,\
    https://www.googleapis.com/auth/servicecontrol
    

Create a new user account

A Cloud Platform Console owner or editor can create a user account through the User Accounts API, or gcloud compute.

When you create a user account, choose an account username and assign an account owner. The account username must be unique within the project and is used to log into instances. The account owner is a Google account that is responsible for the user account. An account owner can upload a public key to the account and start using it.

Console


  1. Go to the User Accounts page.
  2. Click Create user account.
  3. Enter the owner email, the username of the account under Account login whether to add the user to any existing groups.

gcloud


In gcloud, create an account using the users create subcommand. For example, to create a new user, run the following, replacing USERNAME with your desired username and user@example.com with an email address associated with a Google account.

gcloud beta compute users create [USERNAME --owner user@example.com]

If you leave out a username and an account, gcloud derives a user and owner based on the email account authenticated with gcloud:

gcloud beta compute users create

NAME  OWNER            DESCRIPTION
user  user@example.com

API


In the API, make a POST request and replace USERNAME with the username of your choice and user@example.com with the owner's email address in the body of the request:

POST https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users

{"owner": "user@example.com", "name": "USERNAME"}

After you create the user account, grant access to service accounts, if necessary, and get the account owner to add a public key before they attempt to use the account.

Grant access to service accounts

By default, most virtual machine instances are created with a default service account. A service account authenticates applications running on your instances to other Google Cloud Platform services. Using service account credentials, your application can authenticate seamlessly to other APIs without embedding any secret keys or credentials in your instance, image, or application code.

Because service accounts can be used to authenticate to other services, users who can connect to an instance can effectively act as the service account and gain access to other Google APIs. As such, a project owner must explicitly grant the account owner permission to an instance's service account using Google's Identity and Access Management tools or the account owner will not be able to connect to the instance.

There are two exceptions to this requirement:

  • The account owner is also a project editor or owner, in which case they already have read-write access to all service accounts in the project.
  • The instance does not have any service accounts enabled and therefore has no ability to use service account credentials.

If an account owner is a project viewer and if the account owner must connect to instances with service accounts enabled, a project editor or owner must grant the account owner permission to the service account.

Understanding the serviceAccountActor role

You must grant access to service accounts using Google's IAM service and the iam.serviceAccountActor role. The iam.serviceAccountActor role gives users the ability to act as a service account and can be granted either on the project-level or on specific service accounts. Granting the role at a project level gives a user permission to act as all service accounts in the project, including future service accounts that are created. Granting the role on a specific service account gives a user permission to act as that service account only. We strongly recommend granting the role on specific service accounts as needed.

You can learn more about IAM on the IAM documentation or learn more about service accounts on the Service Account documentation.

Grant the serviceAccountActor role

  1. List the service accounts available to your project.

  2. If you have never created a service account, you likely need to grant access only to the "Compute Engine Default Service Account".

    If you have created custom service accounts and enabled them for your instances, determine which service account applies to your instance by performing a compute.instances.get() request and looking at the serviceAccounts field. For example, the following is a snippet of an instance's service account list:

    serviceAccounts:
    - email: 835469197146-compute@developer.gserviceaccount.com
      scopes:
      - https://www.googleapis.com/auth/cloud.useraccounts.readonly
      - https://www.googleapis.com/auth/devstorage.read_only
      - https://www.googleapis.com/auth/logging.write
      - https://www.googleapis.com/auth/monitoring.write

  3. Lastly, grant the account owner access to the service account.

Add a public key

After an account is created, the account owner can add a public key and connect to an instance. If the account owner uses gcloud, the tool automatically generates a public/private key pair for the account and connects you to the instance:

gcloud beta compute ssh [USERNAME@]INSTANCE

A username is recommended but not required, and if not provided, gcloud assumes that the user is the email account authenticated with gcloud.

Note that this is a different SSH command than gcloud compute ssh. The gcloud beta compute ssh command will use user accounts to log into the instance, while the current gcloud compute ssh command will use metadata SSH keys, ignoring any user accounts.

Manually add a key

The account owner can also generate a public/private key pair manually and add it to the user account. For example, you can use the ssh-keygen utility to generate your keys, replacing DESIRED_LOCAL_KEY_FILE with a path and filename of the key files to create:

$ ssh-keygen -t rsa -f DESIRED_LOCAL_KEY_FILE

Next, add the public key manually to the account.

Console


  1. Go to the User Accounts page.
  2. Click the account you want to add a key for.
  3. Under SSH Keys section on the next page, click Add key.
  4. Add your key up uploading a public key file or manually pasting the key.

A valid ssh-rsa key has the following format:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC9KIHrp0pi0bHPeS9Us+2zEokZ6tgx/M8
FgLSCovj3SLWXqb0qZqUPlgyrLiRhJ8yLfWEeRnhnKstR3mWNc2lBVqT49XbepmC7X30DCn
Vp6mHZq/VONSLlrM2gzUEyeI7O9CcLu+QM6IDd3alIQY4AOSWZWIxJlxK+QEwSGf+aXMx1F
CdK4KLpsMNp5zVjWaioFdozg9XQHsfURy/d3EgzqcCfb7SZMYnnkEFqndictkTwi9MCtN0T
SGICavbj+GN/bG7nMWJ61dhYtAj17M4bWzIMRpjdfZ6DojYPMvXCHLF0mq4jXYj8zkRTH+S
KAaaSHL6DTdREqjaavgR4biKR user@example.com

gcloud


In gcloud:

gcloud beta compute users add-keys [USERNAME] \
    --public-key-files DESIRED_LOCAL_KEY_FILE.pub

You can set a public key to expire after a certain duration by providing the --expire property. This prevents access to the account once the key has expired. The value of your --expire property can be any duration followed by one of s for seconds, m for minutes, h for hours, or d for days. For example, to set a key to expire after 5 hours, supply the value 5h:

gcloud beta compute users add-keys [USERNAME] \
    --public-key-files DESIRED_LOCAL_KEY_FILE.pub --expire 5h

A username is recommended but not required, and if not provided, gcloud assumes that the user is the email account authenticated with gcloud.

API


In the API, add a public key by providing a POST request to the addPublicKey() method with the public key inlined in the request body, and an optional duration given in RFC3339 format:

POST https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME/addPublicKey

{"expirationTimestamp": "2015-04-08T17:07:47Z",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC9KIHrp0pi0bHPeS9Us+2zEokZ
6tgx/M8FgLSCovj3SLWXqb0qZqUPlgyrLiRhJ8yLfWEeRnhnKstR3mWNc2lBVqT49XbepmC
7X30DCnVp6mHZq/VONSLlrM2gzUEyeI7O9CcLu+QM6IDd3alIQY4AOSWZWIxJlxK+QEwSGf
+aXMx1FCdK4KLpsMNp5zVjWaioFdozg9XQHsfURy/d3EgzqcCfb7SZMYnnkEFqndictkTwi9
MCtN0TSGICavbj+GN/bG7nMWJ61dhYtAj17M4bWzIMRpjdfZ6DojYPMvXCHLF0mq4jXYj8z
kRTH+SKAaaSHL6DTdREqjaavgR4biKR user@example.com"}

Log in with a user account

You can connect to an instance with a user account if the instance has been enabled to recognize user accounts. As mentioned in the Setup steps, instances must run a specialized startup script and have access to the necessary API scopes in order to recognize user account information. The startup script is located in the following Cloud Storage bucket:

gs://gcua-beta/startup.sh

When starting the instance, run the startup script using the --metadata flag with empty ssh-keys and sshKeys specifications. Additionally, specify the cloud.useraccounts.readonly scope with the --scopes flag in addition to the default scopes. For example:

gcloud compute instances create example-instance --image debian-8 \
--metadata startup-script-url=gs://gcua-beta/startup.sh,ssh-keys="",sshKeys="" \
--scopes https://www.googleapis.com/auth/cloud.useraccounts.readonly,\
https://www.googleapis.com/auth/devstorage.read_only,\
https://www.googleapis.com/auth/logging.write,\
https://www.googleapis.com/auth/monitoring.write,\
https://www.googleapis.com/auth/service.management,\
https://www.googleapis.com/auth/servicecontrol

After you have an instance that is enabled for user accounts, the account owner can connect to the instance using one of the following methods:

  • gcloud beta compute ssh
  • Standard SSH

It is not possible to connect with a user account with the gcloud compute ssh command or SSH from a browser because both tools will use SSH keys provided in the metadata server, ignoring user account credentials.

gcloud


To connect to an with gcloud, the account owner should run the following command, replacing INSTANCE with the instance name and USERNAME with the account username.

gcloud beta compute ssh [USERNAME@]INSTANCE

A username is recommended but not required, and if not provided, gcloud assumes that the user is the email account authenticated with gcloud.

Standard SSH


To connect to an instance using standard SSH with a user account:

<pre class="lang-sh prettyprint">
<span class="no-select">$ </span>ssh -i LOCAL_KEY_FILE USER@IP_ADDRESS
</pre>

Identify a public key

All public keys have a unique fingerprint that identifies the key. You need this fingerprint to edit keys through gcloud or the API. For example, to delete a specific public key from a user account using gcloud or the API, you must provide the fingerprint of the key.

The Cloud Platform Console does not require a fingerprint key to manage your keys through the UI.

gcloud


To get the fingerprint of a key:

gcloud beta compute users describe USERNAME
creationTimestamp: '2015-04-03T09:23:20.148-07:00'
id: '6763872456096809111'
kind: clouduseraccounts#user
name: USERNAME
owner: user@example.com
publicKeys:
- creationTimestamp: '2015-04-03T10:02:00.652-07:00'
  description: ''
  expirationTimestamp: '2015-04-08T10:02:00.000-07:00'
  fingerprint: 0b710292276c327dd7518ae8d6eff27d
  key: |
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCqxdrLBUeDRy9GctfQsiYb...
selfLink: https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME

API


In the API, perform a GET request:

GET https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME
{
 "kind": "clouduseraccounts#user",
 "id": "6763872456096809111",
 "creationTimestamp": "2015-04-03T09:23:20.148-07:00",
 "name": "USERNAME",
 "selfLink": "https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME",
 "owner": "user@example.com",
 "publicKeys": [
  {
   "fingerprint": "0b710292276c327dd7518ae8d6eff27d",
   "creationTimestamp": "2015-04-03T10:02:00.652-07:00",
   "expirationTimestamp": "2015-04-08T10:02:00.000-07:00",
   "description": "",
   "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCqiBWn3qDQK.."
  }
 ]
}

Remove a public key

Removing a public key revokes its access to the user account. This can only be done if you are an owner of the corresponding user account. It is not possible for a Cloud Platform Console project owner or editor to remove a public key from a user account, unless they are also the account owner.

Console


  1. Go to the User Accounts page.
  2. Click the account you want to remove keys from.
  3. Select the checkbox next to each key you want to remove.
  4. Click the Delete button.

gcloud


To remove a specific public key, you must have the public key's fingerprint. See Identify a public key for more information.

To revoke a public key from an account, use the remove-keys sub-command and provide the FINGERPRINT, which is a unique string returned by performing a GET request on the account. The fingerprint is used to identify the public key to remove, and conforms to standard RFC4716.

gcloud beta compute users remove-keys [USERNAME] --fingerprints FINGERPRINT

To revoke all public keys for an account, omit the --fingerprints property:

gcloud beta compute users remove-keys [USERNAME]

A username is recommended but not required, and if not provided, gcloud assumes that the user is the email account authenticated with gcloud.

API


To remove a specific public key, you must have the public key's fingerprint. See Identify a public key for more information.

In the API, make an empty POST request to the removePublicKey() method, providing the fingerprint of the key as a query parameter:

POST https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME/removePublicKey?alt=json&fingerprint=FINGERPRINT

Create a user group

Create user groups and these groups will appear on your virtual machine instances as Linux groups. Linux groups are commonly used to manage file permissions. Add user accounts to groups to grant them permissions specified by that group on Linux virtual machine instances.

For example, you can create a group called devs that has write access to a number of source code files, and then add users to the devs group to give them permissions to these files.

Console


To create a group:

  1. Go to the Linux groups page.
  2. If prompted, select a project.
  3. Click Create a Linux user group to create a new group.

To delete a group:

  1. Go to the Linux groups page.
  2. If prompted, select a project.
  3. Check the box next to the group you want to delete and click Delete.

To see members of a group:

  1. Go to the Linux groups page.
  2. If prompted, select a project.
  3. Click the group you want to view members for.

gcloud


To create a new group, run:

gcloud beta compute groups create GROUP

To add a user to a group, run:

gcloud beta compute groups add-members GROUP --members USERNAME,[USERNAME..]

To list the users of a group:

gcloud beta compute groups describe GROUP

To remove users:

gcloud beta compute groups remove-members GROUP --members USERNAME

API


To create a new group, create a POST request with the name of the group as the request body:

POST https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/groups

{"name": "GROUP"}

To add members to a group, create a POST request to the group's addMember()method, providing a fully-qualified URL of the user account to add in the request body:

POST https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/groups/GROUP/addMember

{"user": "https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME"}

Similarly, to remove an account, create the same request to the group's removeMembers() method:

POST https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/groups/GROUP/removeMember

{"user": "https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME"}

Delete an account

You can delete a user account if you are a Cloud Platform Console project editor or owner.

Console


  1. Go to the User Accounts page.
  2. Check the boxes next to the accounts you want to delete and click Delete.

gcloud


In gcloud compute, run the following command to delete a specific user account:

gcloud beta compute users delete USERNAME

To delete multiple accounts, provide multiple usernames:

gcloud beta compute users delete USERNAME1 USERNAME2 ..

You can also delete all accounts that belong to certain owners by specifying the --owners flag:

gcloud beta compute users delete owner1@example.com owner2@another-domain.com .. --owners

When you provide the --owners flag, the provided arguments are treated as owner emails and all accounts owned by those emails are deleted.

API


In the API, create a DELETE request to the account's URL with an empty request body:

DELETE https://www.googleapis.com/clouduseraccounts/beta/projects/myproject/global/users/USERNAME

Troubleshooting

I have successfully created a user account, and the account owner has added a public key but they cannot connect to the instance. What's going on?

  • If the instance has a service account, make sure you have granted the iam.serviceAccountActor role to the account owner.

  • Double-check that the account owner has added the correct public key.

  • Make sure the account owner is connecting using gcloud beta compute ssh, and not gcloud compute ssh or SSH from the browser.

I tried to log in with a user account on an instance but it rejected my request.

Send feedback about...

Compute Engine Documentation