Authentication (authn) and authorization (authz) are mechanisms used to verify the user of your app and their access to resources, respectively. This document identifies key terms that you should know before implementing authentication and authorization in your apps. The following diagram shows key components of an authentication and authorization implementation.
Figure 1 shows the high-level steps of an authentication and authorization implementation:
(not shown) During development, you register the application in the Google Cloud Console and obtain credentials known only by your app and Google. You also configure a consent screen. This screen is shown to users of your app to gain their consent on the scope(s) of access your app needs to their Google resources.
The app might also require the user to authenticate by signing in.
When your app needs access to Google resources, it asks Google for the scope(s) of access needed to access the resources. For example, the app might need to read metadata of the user's files in Google Drive, so it would only request a metadata read-only scope.
Google displays the consent screen.
If the user consents to the scopes of access, your app bundles the credentials and the user-approved scopes of access into a request. The request is sent to the Google Authorization Server to obtain an access token.
Google returns an access token with a list of scopes of access granted by the token. If the returned list of scopes is more limited than the requested scopes of access, the app disables any features limited by the token.
Use the access token to invoke the API and access user data.
(optional) If your application needs access to a Google API beyond the lifetime of a single access token, it can obtain a refresh token.
If additional access is needed by your app, your app asks the user to grant new scopes of access, resulting in a new request to get an access token (steps 3-6).
Following is a list of terms related to authentication and authorization:
The act of ensuring that a principal, which can be a user or an app acting on behalf of a user, is who they say they are. When writing Google Workspace apps, you should be aware of these types of authentication:
- User authentication
- The act of a user authenticating (signing in) to your app. User authentication is usually carried out through a signing in process in which the user uses a username and password combination to verify their identity to the app. User authentication can be incorporated into an app using Google Sign-in .
- App authentication
- The act of an app authenticating directly to Google services on behalf of the user running the app. App authentication is usually carried out using pre-created credentials in your app's code.
The permissions or "authority" the principal has to access data or perform operations. The act of authorization is carried out through code you write in your app. This code informs the user that the app wishes to act on their behalf and, if allowed, uses your app's unique credentials to obtain an access token from Google used to access data or perform operations.
A form of identification used in software security. In terms of authentication, a credential is often a username/password combination. In terms of authorization for Google Workspace APIs, a credential is usually some form of identification, such as a unique secret string, known only between the app developer and the authentication server. Google supports these authentication credentials: API key, OAuth 2.0 Client ID, and service accounts.
- API key
- The credential used to request access to public data, such as data provided using the Maps API. API keys can also be used to access Google Workspace files that are shared using "Anyone on the Internet with this link can (view/edit/comment)" setting within Google Workspace sharings settings.
- OAuth 2 client ID
- The credential used to request access to user-owned data. This is the primary credential used when requesting access to data using Google Workspace APIs. This credential requires user consent.
- Client secret
- A string of characters that should only be known by your application and the authorization server. The client secret protects the user's data by only granting tokens to authorized requestors. You should never include your client secret in your app.
- Service account keys
- Used by service accounts to authorize to Google service.
- Service account
- A credential used for server-to-server interactions, such as a faceless app 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 delegation of authority, they can be used to access user data.
A string defining a level of access to resources required by your app, such as the level of access to data owned by the user. Your app requests one or more scopes on behalf of the user. The authentication server determines which of your requested scopes it permits and returns those scopes in an access token. The "recommended" scopes represent limited access to resources and operations, while "restricted" scopes represent broader access.
- Authorization server
Google's server for granting access, using an access token, to an app's requested data and operations.
- Authorization code
A code sent from the Authorization server used to obtain an access token. A code is only needed when your application type is a web server app or an installed app.
- Access token
A token granting access to a Google Workspace API. A single access token can grant varying degrees, known as scopes, of access to multiple APIs. Your app's authorization code requests access tokens and uses them to invoke Google 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 authentication and authorization mechanisms you use in your app represent your implementation of the OAuth 2.0 framework.
The entity attempting to authenticate to something. A principal can either be a user or an app acting on behalf of a user.
- Data type
In the context of authentication and authorization, data type refers to the entity that owns the data that your app is trying to access. There are three data types:
- Public domain data
- Data accessible by anyone, such as some Google maps data. This data is usually accessed using an API key.
- End-user data
- Data belonging to a specific end user or group, such as a specific user's Google Drive files. This data type is usually accessed using an OAuth 2 client ID or service account.
- Cloud data
- Data owned by a cloud project. This data type is usually accessed by a service account.
- User consent
An authorization step requiring the user of your app to authorize the app to access data and operations on the user's behalf.
- Application type
- Service account
A special type of Google account intended to represent a non-human user that needs to authenticate and be authorized to access data. Your application assumes the identity of the service account to call Google APIs, so that the users aren't directly involved. By themselves, service accounts cannot be used to access user data; data customarily accessed using Workspace APIs. However, a service account can access user data by implementing domain-wide delegation of authority. For further information, refer to Understanding service accounts
- Domain-wide delegation of authority
An Administration feature that allows apps to access users' data across your organization's Google Workspace environment. Domain-wide delegation allows the app to perform admin-related tasks on user data. Because of the power of this feature, only super admins can enable domain-wide delegation of authority.