Authenticating as an End User

In most situations, we recommend using a service account for authenticating to a Google Cloud Platform (GCP) API. In some situations you might want your users to authenticate directly. For example:

• You need to access resources on behalf of an end user of your application. For example, your application needs to access Google BigQuery datasets that belong to users of your application.

• You need to authenticate as yourself instead of your application. For example, because the Cloud Resource Manager API can create and manage projects owned by a specific user, you would need to authenticate as a user to create projects on their behalf.

This guide discusses end user credentials. It doesn't discuss authenticating a user to your application. For that use case, we recommend Firebase authentication.

Authentication flow

When an application needs to access resources on behalf of a user, the application presents a consent screen to the user. After the user accepts, your application requests credentials from an authorization server. With the credentials, the application can access resources on behalf of the user.

This process is a protocol called OAuth 2.0.

Your app

User consent

User data

To learn more about OAuth 2.0, see OAuth 2.0.

Specifying API scopes

When you use a service account to authenticate to a GCP API, GCP automatically authenticates the service account with full access to the API. When authenticating as an end user, you must specify OAuth scopes manually. OAuth scopes limit the actions your application can perform on behalf of the end user. For example, these actions might include reading files from Cloud Storage, or managing GCP projects.

See the specific API page for more information on what OAuth scopes are available. For example, if you plan to use the disks.get() method for the Compute Engine API, you would need to set one of these OAuth scopes. Set the minimum scope needed based on your use case.

Granting and limiting access to project resources

If you're using end user credentials to access resources within your project, you must grant the user access to resources within your project. Do this in GCP by setting a role in Google Cloud Identity and Access Management (Cloud IAM).

You may want to limit which resources the user has access to. This is especially true when you're allowing the user to access resources in a project that you own. Set roles according to the least privilege the user needs.

Each service has a set of Cloud IAM roles, and you can choose to create custom roles instead. For more information, see understanding roles and creating and managing custom roles.

End user authentication example

Complete the following sections to obtain credentials for an end user. The following steps use the BigQuery API, but you can replicate this process with any GCP API that has a client library.

Setting up your project

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Cloud Console, on the project selector page, select or create a Google Cloud project.

   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.

   Go to the project selector page

3. Make sure that billing is enabled for your Google Cloud project. Learn how to confirm billing is enabled for your project.

4. Enable the BigQuery API.

   Enable the API

5. Install the BigQuery client libraries.
6. If using Python or Node.js, you must install an additional auth library.

   Python

   Install the oauthlib integration for Google Auth.

   pip install --upgrade google-auth-oauthlib

Creating your client credentials

Create your client credentials in Google Cloud Console.

1. Go to the OAuth consent screen page in Cloud Console.

2. On the Credentials page, select the Create credentials button, then select OAuth client ID.

3. Select Other, then select the Create button. Select the OK button after the success dialogue appears.

4. Download the credentials by selecting the Download JSON button for the client ID.

   

5. Save the credentials file to client_secrets.json. This file must be distributed with your application.

Authenticating and calling the API

1. Use the client credentials to perform the OAuth 2.0 flow.

   Python

   View on GitHub

   from google_auth_oauthlib import flow
   
   # TODO: Uncomment the line below to set the `launch_browser` variable.
   # launch_browser = True
   #
   # The `launch_browser` boolean variable indicates if a local server is used
   # as the callback URL in the auth flow. A value of `True` is recommended,
   # but a local server does not work if accessing the application remotely,
   # such as over SSH or from a remote Jupyter notebook.
   
   appflow = flow.InstalledAppFlow.from_client_secrets_file(
       'client_secrets.json',
       scopes=['https://www.googleapis.com/auth/bigquery'])
   
   if launch_browser:
       appflow.run_local_server()
   else:
       appflow.run_console()
   
   credentials = appflow.credentials

2. Use the authenticated credentials to connect to the BigQuery API.

   Python

   View on GitHub

   from google.cloud import bigquery
   
   # TODO: Uncomment the line below to set the `project` variable.
   # project = 'user-project-id'
   #
   # The `project` variable defines the project to be billed for query
   # processing. The user must have the bigquery.jobs.create permission on
   # this project to run a query. See:
   # https://cloud.google.com/bigquery/docs/access-control#permissions
   
   client = bigquery.Client(project=project, credentials=credentials)
   
   query_string = """SELECT name, SUM(number) as total
   FROM `bigquery-public-data.usa_names.usa_1910_current`
   WHERE name = 'William'
   GROUP BY name;
   """
   query_job = client.query(query_string)
   
   # Print the results.
   for row in query_job.result():  # Wait for the job to complete.
       print("{}: {}".format(row['name'], row['total']))

When you run the sample code, the code launches a browser requesting access to the project associated with the client secrets. The resulting credentials can then be used to access the user's BigQuery resources, because the sample requested the BigQuery scope.

In a different use case, you may wish to add IAM roles to determine what the user can access.

What's next

• Learn about authenticating to a GCP API.

• Learn about setting up authentication for production applications.

• Learn about using API keys.