Streamlined Linking with OAuth and Sign in with Google

Page Summary

outlined_flag

• OAuth-based Google Sign-In Streamlined linking enhances OAuth linking by adding Google Sign-In for a seamless user experience and enabling account creation using Google accounts.

• The general steps for streamlined linking involve obtaining user consent for Google profile access, checking for existing accounts based on profile info, linking accounts for existing users, and validating ID tokens for creating new accounts when no match is found.

• Requirements for streamlined linking include implementing basic web OAuth linking with compliant authorization and token exchange endpoints that support JWT assertions and the check, create, and get intents.

• The token exchange endpoint must handle check intent requests by validating a JWT assertion containing user identity information and checking if the Google account ID or email exists in your system, responding with account_found=true or account_found=false (with a 404 error).

• The token exchange endpoint must handle get intent requests by validating a JWT assertion, checking for an existing account, and issuing a token if found, or returning a linking_error (with a 401 error) if not found.

• The token exchange endpoint must handle create intent requests by validating a JWT assertion, validating user information, creating a new account if no match is found, and issuing a token upon successful creation, or returning a linking_error (with a 401 error) if a matching account is found.

• To implement streamlined linking, you need to obtain your Google API Client ID from the Google Cloud Console and ensure your OAuth server supports the required intents and JWT handling.

• You can validate your streamlined linking implementation using tools like the OAuth 2.0 Playground and the Google Account Linking Demo.

Overview

OAuth-based Sign in with Google Streamlined linking adds Sign in with Google on top of OAuth linking. This provides a seamless linking experience for Google users, and it also enables account creation, which allows the user to create a new account on your service using their Google Account.

To perform account linking with OAuth and Sign in with Google, follow these general steps:

1. First, ask the user to give consent to access their Google profile.
2. Use the information in their profile to check if the user account exists.
3. For existing users, link the accounts.
4. If you can't find a match for the Google user in your authentication system, validate the ID token received from Google. You can then create a user based on the profile information contained in the ID token.

Figure 1. Account Linking on a user's phone with Streamlined Linking

Streamlined Linking: OAuth + Sign in with Google Flow

The following sequence diagram details interactions between the User, Google, and your token exchange endpoint for Streamlined Linking.

Roles and responsibilities

The following table defines the roles and responsibilities of the actors in the Streamlined Linking flow.

Actor / Component	GAL Role	Responsibilities
Google App / Server	OAuth Client	Obtains user consent for Sign in with Google, passes identity assertions (JWT) to your server, and securely stores the resulting tokens.
Your Token Exchange Endpoint	Identity Provider / Authorization Server	Validates identity assertions, checks for existing accounts, handles the account linking intents (check, get, create), and issues tokens based on the requested intents.
Your Service API	Resource Server	Provides access to user data when presented with a valid access token.

Requirements for Streamlined Linking

• Implement the basic OAuth linking flow. Your service must support OAuth 2.0-compliant authorization and token exchange endpoints.
• Your token exchange endpoint must support JSON Web Token (JWT) assertions and implement the check, create, and get intents.

• Register your Google API Client ID.

Decision Logic for Streamlined Linking

The following logic determines how intents are called during the Streamlined Linking flow:

1. Does the user have an account in your authentication system? (User decides by selecting YES or NO)
   1. YES : Does the user use the email associated with their Google Account to sign into your platform? (User decides by selecting YES or NO)
      1. YES : Does the user have a matching account in your authentication system? (check intent is called to confirm)
         1. YES : get intent is called and the account is linked if get intent returns successfully.
         2. NO : Create New Account? (User decides by selecting YES or NO)
            1. YES : create intent is called and the account is linked if create intent returns successfully.
            2. NO : The OAuth linking flow is triggered, the user is directed to their browser, and the user is given the option to link with a different email.
      2. NO : The OAuth linking flow is triggered, the user is directed to their browser, and the user is given the option to link with a different email.
   2. NO : Does the user have a matching account in your authentication system? (check intent is called to confirm)
      1. YES : get intent is called and the account is linked if get intent returns successfully.
      2. NO : create intent is called and the account is linked if create intent returns successfully.

Implementation Recipe

Your token exchange endpoint must implement the check, get, and create intents to support Streamlined Linking.

Follow these steps to handle the different intents:

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"account_found": "false"}.

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

Handle account creation using Sign in with Google (create intent)

If no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (HTTP 200 OK).

Get your Google API Client ID

You will be required to provide your Google API Client ID during the Account Linking registration process. To get your API Client ID using the project you created while completing the OAuth linking steps. To do so, complete the following steps:

1. Go to the Clients page.

2. Create or select a Google APIs project.

   If your project doesn't have a Client ID for the Web application Type, click Create Client to create one. Be sure to include your site's domain in the Authorized JavaScript origins box. When you perform local tests or development, you must add both http://localhost and http://localhost:<port_number> to the Authorized JavaScript origins field.

Validate your implementation

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.