Learn about authentication and authorization  |  Google Workspace  |  Google for Developers (2024)

• Home
• Google Workspace
• Guides

Authentication and authorization are mechanisms used to verify identity andaccess to resources, respectively. This document identifies key terms that youshould know before implementing authentication and authorization in your app.

Authentication identifies who is making the request.Authorization identifies what resources the requestor can accessand what level of access that they have. Authentication is a prerequisite forauthorization. You can't determine what resources to access without firstestablishing the identity of the requestor. For a more detailed definition,see theImportant terminology section.

Consider the following simplified example of a hotel reservation. When youarrive at the hotel, the front desk clerk requests your ID to verify yourreservation. Your ID authenticates you to the hotel. The front desk clerkgives you a hotel key. This key gives you access to certain resources at thehotel such as your hotel room, the gym, and the business center. The hotelkey authorizes you to access those resources.

Process overview

The following diagram shows the high-level steps of authentication andauthorization for Google Workspace APIs:

1. Configure your Google Cloud project and app: Duringdevelopment, you register your app in the Google Cloud console, definingauthorization scopes and access credentials to authenticate your app with anAPI key, end user credential, or service account credential.

2. Authenticate your app for access: When your app runs, the registeredaccess credentials are evaluated. If your app is authenticating as an enduser, a sign-in prompt might be displayed.

3. Request resources: When your app needs access to Google resources, itasks Google using the relevant scopes of access you previously registered.

4. Ask for user consent: If your app is authenticating as an end user,Google displays the OAuth consent screen so the user can decide whether togrant your app access to the requested data.

5. Send approved request for resources: If the user consents to the scopesof access, your app bundles the credentials and the user-approved scopes ofaccess into a request. The request is sent to the Google authorization serverto obtain an access token.

6. Google returns an access token: The access token contains a list ofgranted scopes of access. If the returned list of scopes is more limited thanthe requested scopes of access, your app disables any features limited by thetoken.

7. Access requested resources: Your app uses the access token from Google toinvoke the relevant APIs and access the resources.

8. Get a refresh token (optional): If your app needs access to a Google APIbeyond the lifetime of a single access token, it can obtain a refresh token.

9. Request more resources: If additional access is needed, your app asks theuser to grant new scopes of access, resulting in a new request to get anaccess token (steps 3–6).

Important terminology

Following is a list of terms related to authentication and authorization:

Authentication

The act of ensuring that a principal, which can be a user or an app actingon behalf of a user, is who they say they are. When writing Google Workspaceapps, you should be aware of these types of authentication:

User authentication

The act of a user authenticating (signing in) to your app. Userauthentication is usually carried out through a signing in process in whichthe user uses a username and password combination to verify their identityto the app. User authentication can be incorporated into an app usingSign In With Google.

App authentication

The act of an app authenticating directly to Google services on behalf ofthe user running the app. App authentication is usually carried out usingpre-created credentials in your app's code.

Authorization

The permissions or "authority" the principal has to access data or performoperations. The act of authorization is carried out through code you write inyour app. This code informs the user that the app wishes to act on their behalfand, if allowed, uses your app's unique credentials to obtain an access tokenfrom Google used to access data or perform operations.

Credential

A form of identification used in software security. In terms ofauthentication, a credential is often a username and password combination. Interms of authorization for Google Workspace APIs, a credential is usually someform of identification, such as a unique secret string, known only between theapp developer and the authentication server. Google supports theseauthentication credentials: API key, OAuth 2.0 Client ID,and service accounts.

API key

The credential used to request access to public data, such as dataprovided using the Maps API or Google Workspace files shared using the"Anyone on the Internet with this link" setting withinGoogle Workspace sharing settings.

OAuth 2 client ID

The credential used to request access to user-owned data. This is theprimary credential used when requesting access to data usingGoogle Workspace APIs. This credential requires user consent.

Client secret

A string of characters that should only be known by your application and theauthorization server. The client secret protects the user's data by onlygranting tokens to authorized requestors. You should never include yourunencrypted client secret in your app. We recommend storing the client secretsecurely. For more information, seeHandle client credentials securely.

Service account keys

Used by service accounts to gain authorization to a Google service.

Service account

A credential used for server-to-server interactions, such as a facelessapp that runs as a process to access some data or perform some operation.Service accounts are usually used to access cloud-based data and operations.However, when used with domain-wide delegation of authority, theycan be used to access user data.

Scope

An OAuth 2.0 URI string that defines a level of access to resources or actionsgranted to an app. For Google Workspace, authorization scope URIs contain theGoogle Workspace app name, what kind of data it accesses, and the level ofaccess. Users of your app can review requested scopes and choose what access togrant, then Google's authentication server returns permitted scopes to yourapp in an access token. For more details, refer toHow to choose scopes for your app.

Authorization server

Google's server for granting access, using an access token, to an app'srequested data and operations.

Authorization code

A code sent from the authorization server used to obtain an accesstoken. A code is only needed when your application type is a web server app oran installed app.

Access token

A token granting access to a Google Workspace API. A single access token cangrant varying degrees, known as scopes, of access to multiple APIs. Your app'sauthorization code requests access tokens and uses them to invokeGoogle Workspace APIs.

Resource server

The server hosting the API that your app wants to call.

OAuth 2.0 framework

A standard that your app can use to provide it with “secure delegated access”or access to data and operations on behalf of the app's user. The authenticationand authorization mechanisms you use in your app represent your implementationof the OAuth 2.0 framework.

Principal

An entity, also known as an identity, that can be granted access to aresource. Google Workspace APIs support two types of principals: user accountsand service accounts. For more details, refer toPrincipals.

Data type

In the context of authentication and authorization, data type refers to theentity that owns the data that your app is trying to access. There are threedata types:

Public domain data

Data accessible by anyone, such as some Google maps data. This data isusually accessed using an API key.

End-user data

Data belonging to a specific end user or group, such as a specific user'sGoogle Drive files. This data type is usually accessed using an OAuth 2client ID or service account.

Cloud data

Data owned by a Google Cloud project. This data type is usually accessed by aservice account.

User consent

An authorization step requiring the user of your app to authorize the appto access data and perform operations on the user's behalf.

Application type

The type of app you are going to create. When creating credentials usingthe Google Cloud console, you are asked to select your application type.Application types are: Web application (JavaScript), Android, Chrome app, iOS,TVs and Limited Input devices, Desktop app (also called an "installed app"),and Universal Windows Platform (UWP).

Service account

A special type of Google account intended to represent a non-human user thatneeds to authenticate and be authorized to access data. Your application assumesthe identity of the service account to call Google APIs, so that the usersaren't directly involved. By themselves, service accounts cannot be usedto access user data; data customarily accessed using Workspace APIs. However,a service account can access user data by implementing domain-wide delegationof authority. For more details, refer toUnderstanding service accounts.

Domain-wide delegation of authority

An administration feature that can authorize an application to access userdata on behalf of users in the Google Workspace organization. Domain-widedelegation can be used to perform admin-related tasks on user data. To delegateauthority this way, Google Workspace administrators use service accounts withOAuth 2.0. Because of the power of this feature, only super admins can enabledomain-wide delegation of authority. For more details, refer toDelegating domain-wide authority to a service account.

Next step

Configure your app's OAuth consent screento ensure users can understand and approve what access your app has to theirdata.