omniauth-google-oauth2 1.2.2 → 1.2.3

data/README.md

@@ -4,7 +4,7 @@
 
 Strategy to authenticate with Google via OAuth2 in OmniAuth.
 
-Get your API key at: https://console.cloud.google.com  Note the Client ID and the Client Secret.
+Get your API key at: https://console.cloud.google.com. Note the Client ID and the Client Secret.
 
 For more details, read the Google docs: https://developers.google.com/identity/protocols/oauth2
 
@@ -20,10 +20,10 @@ Then `bundle install`.
 
 ## Google API Setup
 
-* Go to 'https://console.cloud.google.com'
-* Select your project.
-* Go to Credentials, then select the "OAuth consent screen" tab on top, and provide an 'EMAIL ADDRESS' and a 'PRODUCT NAME'
-* Wait 10 minutes for changes to take effect.
+- Go to 'https://console.cloud.google.com'
+- Select your project.
+- Go to Credentials, then select the "OAuth consent screen" tab on top, and provide an 'EMAIL ADDRESS' and a 'PRODUCT NAME'
+- Wait 10 minutes for changes to take effect.
 
 ## Usage
 
@@ -48,49 +48,51 @@ NOTE: While developing your application, if you change the scope in the initiali
 
 You can configure several options, which you pass in to the `provider` method via a hash:
 
-* `scope`: A comma-separated list of permissions you want to request from the user. See the [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/) for a full list of available permissions. Caveats:
-  * The `email` and `profile` scopes are used by default. By defining your own `scope`, you override these defaults, but Google requires at least one of `email` or `profile`, so make sure to add at least one of them to your scope!
-  * Scopes starting with `https://www.googleapis.com/auth/` do not need that prefix specified. So while you can use the smaller scope `books` since that permission starts with the mentioned prefix, you should use the full scope URL `https://docs.google.com/feeds/` to access a user's docs, for example.
+- `scope`: A comma-separated list of permissions you want to request from the user. See the [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/) for a full list of available permissions. Caveats:
+  - The `email` and `profile` scopes are used by default. By defining your own `scope`, you override these defaults, but Google requires at least one of `email` or `profile`, so make sure to add at least one of them to your scope!
+  - Scopes starting with `https://www.googleapis.com/auth/` do not need that prefix specified. So while you can use the smaller scope `books` since that permission starts with the mentioned prefix, you should use the full scope URL `https://docs.google.com/feeds/` to access a user's docs, for example.
 
-* `redirect_uri`: Override the redirect_uri used by the gem.
+- `redirect_uri`: Override the redirect_uri used by the gem.
 
-* `prompt`: A space-delimited list of string values that determines whether the user is re-prompted for authentication and/or consent. Possible values are:
-  * `none`: No authentication or consent pages will be displayed; it will return an error if the user is not already authenticated and has not pre-configured consent for the requested scopes. This can be used as a method to check for existing authentication and/or consent.
-  * `consent`: The user will always be prompted for consent, even if they have previously allowed access a given set of scopes.
-  * `select_account`: The user will always be prompted to select a user account. This allows a user who has multiple current account sessions to select one amongst them.
+- `prompt`: A space-delimited list of string values that determines whether the user is re-prompted for authentication and/or consent. Possible values are:
+  - `none`: No authentication or consent pages will be displayed; it will return an error if the user is not already authenticated and has not pre-configured consent for the requested scopes. This can be used as a method to check for existing authentication and/or consent.
+  - `consent`: The user will always be prompted for consent, even if they have previously allowed access a given set of scopes.
+  - `select_account`: The user will always be prompted to select a user account. This allows a user who has multiple current account sessions to select one amongst them.
 
   If no value is specified, the user only sees the authentication page if they are not logged in and only sees the consent page the first time they authorize a given set of scopes.
 
-* `image_aspect_ratio`: The shape of the user's profile picture. Possible values are:
-  * `original`: Picture maintains its original aspect ratio.
-  * `square`: Picture presents equal width and height.
-  * `smart`: Picture presents equal width and height with smart cropping.
+- `image_aspect_ratio`: The shape of the user's profile picture. Possible values are:
+  - `original`: Picture maintains its original aspect ratio.
+  - `square`: Picture presents equal width and height.
+  - `smart`: Picture presents equal width and height with smart cropping.
 
   Defaults to `original`.
 
-* `image_size`: The size of the user's profile picture. The image returned will have width equal to the given value and variable height, according to the `image_aspect_ratio` chosen. Additionally, a picture with specific width and height can be requested by setting this option to a hash with `width` and `height` as keys. If only `width` or `height` is specified, a picture whose width or height is closest to the requested size and requested aspect ratio will be returned. Defaults to the original width and height of the picture.
+- `image_size`: The size of the user's profile picture. The image returned will have width equal to the given value and variable height, according to the `image_aspect_ratio` chosen. Additionally, a picture with specific width and height can be requested by setting this option to a hash with `width` and `height` as keys. If only `width` or `height` is specified, a picture whose width or height is closest to the requested size and requested aspect ratio will be returned. Defaults to the original width and height of the picture.
 
-* `name`: The name of the strategy. The default name is `google_oauth2` but it can be changed to any value, for example `google`. The OmniAuth URL will thus change to `/auth/google` and the `provider` key in the auth hash will then return `google`.
+- `name`: The name of the strategy. The default name is `google_oauth2` but it can be changed to any value, for example `google`. The OmniAuth URL will thus change to `/auth/google` and the `provider` key in the auth hash will then return `google`.
 
-* `access_type`: Defaults to `offline`, so a refresh token is sent to be used when the user is not present at the browser. Can be set to `online`. More about [offline access](https://developers.google.com/identity/protocols/OAuth2WebServer#offline)
+- `access_type`: Defaults to `offline`, so a refresh token is sent to be used when the user is not present at the browser. Can be set to `online`. More about [offline access](https://developers.google.com/identity/protocols/OAuth2WebServer#offline)
 
-* `hd`: (Optional) Limit sign-in to a particular Google Apps hosted domain. This can be simply string `'domain.com'` or an array `%w(domain.com domain.co)`. More information at: https://developers.google.com/accounts/docs/OpenIDConnect#hd-param
+- `hd`: (Optional) Limit sign-in to a particular Google Apps hosted domain. This can be simply string `'domain.com'` or an array `%w(domain.com domain.co)`. More information at: https://developers.google.com/accounts/docs/OpenIDConnect#hd-param
 
-* `jwt_leeway`: Number of seconds passed to the JWT library as leeway. Defaults to 60 seconds.
+- `jwt_leeway`: Number of seconds passed to the JWT library as leeway. Defaults to 60 seconds.
 
-* `skip_jwt`: Skip JWT processing. This is for users who are seeing JWT decoding errors with the `iat` field. Always try adjusting the leeway before disabling JWT processing.
+- `authorized_client_ids`: Additional Google OAuth client IDs accepted as token audiences. The configured `client_id` is always accepted.
 
-* `login_hint`: When your app knows which user it is trying to authenticate, it can provide this parameter as a hint to the authentication server. Passing this hint suppresses the account chooser and either pre-fill the email box on the sign-in form, or select the proper session (if the user is using multiple sign-in), which can help you avoid problems that occur if your app logs in the wrong user account. The value can be either an email address or the `sub` string (the user's unique Google ID).
+- `skip_jwt`: Omit decoded ID token claims from `extra.id_info`. This only trims the auth hash; an ID token supplied by the caller in a direct access-token callback is still verified against Google's signing keys because it may be exposed as `extra.id_token`.
 
-* `include_granted_scopes`: If this is provided with the value true, and the authorization request is granted, the authorization will include any previous authorizations granted to this user/application combination for other scopes. See Google's [Incremental Authorization](https://developers.google.com/accounts/docs/OAuth2WebServer#incrementalAuth) for additional details.
+- `login_hint`: When your app knows which user it is trying to authenticate, it can provide this parameter as a hint to the authentication server. Passing this hint suppresses the account chooser and either pre-fill the email box on the sign-in form, or select the proper session (if the user is using multiple sign-in), which can help you avoid problems that occur if your app logs in the wrong user account. The value can be either an email address or the `sub` string (the user's unique Google ID).
 
-* `enable_granular_consent`: If this is provided with the value true, users can choose to only grant access to specific data. See Google's [How to handle granular permissions](https://developers.google.com/identity/protocols/oauth2/resources/granular-permissions) guide for additional details.
+- `include_granted_scopes`: If this is provided with the value true, and the authorization request is granted, the authorization will include any previous authorizations granted to this user/application combination for other scopes. See Google's [Incremental Authorization](https://developers.google.com/accounts/docs/OAuth2WebServer#incrementalAuth) for additional details.
 
-* `openid_realm`: Set the OpenID realm value, to allow upgrading from OpenID based authentication to OAuth 2 based authentication. When this is set correctly an `openid_id` value will be set in `['extra']['id_info']` in the authentication hash with the value of the user's OpenID ID URL.
+- `enable_granular_consent`: If this is provided with the value true, users can choose to only grant access to specific data. See Google's [How to handle granular permissions](https://developers.google.com/identity/protocols/oauth2/resources/granular-permissions) guide for additional details.
 
-* `provider_ignores_state`: You will need to set this to `true` when using the `One-time Code Flow` below. In this flow there is no server side redirect that would set the state.
+- `openid_realm`: Set the OpenID realm value, to allow upgrading from OpenID based authentication to OAuth 2 based authentication. When this is set correctly an `openid_id` value will be set in `['extra']['id_info']` in the authentication hash with the value of the user's OpenID ID URL.
 
-* `overridable_authorize_options`: By default, all `authorize_options` can be overridden with request parameters. You can restrict the behavior by using this option.
+- `provider_ignores_state`: You will need to set this to `true` when using the `One-time Code Flow` below. In this flow there is no server side redirect that would set the state.
+
+- `overridable_authorize_options`: By default, all `authorize_options` can be overridden with request parameters. You can restrict the behavior by using this option.
 
 Here's an example of a possible configuration where the strategy name is changed, the user is asked for extra permissions, the user is always prompted to select their account when logging in and the user's profile picture is returned as a thumbnail:
 
@@ -168,6 +170,7 @@ Configuration options can be passed as the last parameter here as key/value pair
 ```ruby
 config.omniauth :google_oauth2, 'GOOGLE_CLIENT_ID', 'GOOGLE_CLIENT_SECRET', {}
 ```
+
 NOTE: If you are using this gem with devise with above snippet in `config/initializers/devise.rb` then do not create `config/initializers/omniauth.rb` which will conflict with devise configurations.
 
 Then add the following to 'config/routes.rb' so the callback routes are defined.
@@ -281,11 +284,11 @@ Google describes the One-time Code Flow [here](https://developers.google.com/ide
 1. The client (web browser) authenticates the user directly via Google's OAuth 2 API. During this process assorted modals may be rendered by Google.
 2. On successful authentication, Google returns a one-time use code, which requires the Google client secret (which is only available server-side).
 3. Using a AJAX request, the code is POSTed to the Omniauth Google OAuth2 callback.
-4. The Omniauth Google OAuth2 gem will validate the code via a server-side request to Google. If the code is valid, then Google will return an access token and, if this is the first time this user is authenticating against this application, a refresh token.  Both of these should be stored on the server. The response to the AJAX request indicates the success or failure of this process.
+4. The Omniauth Google OAuth2 gem will validate the code via a server-side request to Google. If the code is valid, then Google will return an access token and, if this is the first time this user is authenticating against this application, a refresh token. Both of these should be stored on the server. The response to the AJAX request indicates the success or failure of this process.
 
 This flow is immune to replay attacks, and conveys no useful information to a man in the middle.
 
-The omniauth-google-oauth2 gem supports this mode of operation when `provider_ignores_state` is set to `true`.  Implementors simply need to add the appropriate JavaScript to their web page, and they can take advantage of this flow.  An example JavaScript snippet follows.
+The omniauth-google-oauth2 gem supports this mode of operation when `provider_ignores_state` is set to `true`. Implementors simply need to add the appropriate JavaScript to their web page, and they can take advantage of this flow. An example JavaScript snippet follows.
 
 ```javascript
 // Basic hybrid auth example following the pattern at:
@@ -293,48 +296,57 @@ The omniauth-google-oauth2 gem supports this mode of operation when `provider_ig
 
 const handleGoogleOauthSignIn = () => {
   // Google's OAuth 2.0 endpoint for requesting an access token
-  const oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
+  const oauth2Endpoint = "https://accounts.google.com/o/oauth2/v2/auth";
 
   // Parameters to pass to OAuth 2.0 endpoint.
   const params = new URLSearchParams({
     client_id: YOUR_CLIENT_ID,
-    prompt: 'select_account',
+    prompt: "select_account",
     redirect_uri: YOUR_REDIRECT_URI, // This redirect_uri needs to redirect to the same domain as the one where this request is made from.
-    response_type: 'code',
-    scope: 'email openid profile',
-    state: 'google', // The state will be added in the redirect_uri's query params. Use can this if you use the same redirect_uri with different omniauth provider to know which one you're currently handling for example.
+    response_type: "code",
+    scope: "email openid profile",
+    state: "google", // The state will be added in the redirect_uri's query params. Use can this if you use the same redirect_uri with different omniauth provider to know which one you're currently handling for example.
   });
 
   const url = `${oauth2Endpoint}?${params.toString()}`;
 
   // Create <a> element to redirect to OAuth 2.0 endpoint.
-  const a = document.createElement('a');
+  const a = document.createElement("a");
   a.href = url;
-  a.target = '_self';
+  a.target = "_self";
 
   // Add a to page and click it to open the OAuth 2.0 endpoint.
   document.body.appendChild(a);
   a.click();
-}
+};
 
 // Call this method when redirected to your `redirect_uri`
 const handleGoogleOauthCallback = async () => {
   // Get the query params Google included in your `redirect_uri`
   const params = new URL(document.location.toString()).searchParams;
-  const code = params.get('code');
-  const state = params.get('state') // the `state` you added in the sign in request is here if you need it.
+  const code = params.get("code");
+  const state = params.get("state"); // the `state` you added in the sign in request is here if you need it.
 
-  const response = fetch('your.api.domain/auth/google_oauth2/callback', {
+  const response = await fetch("your.api.domain/auth/google_oauth2/callback", {
     body: JSON.stringify({
       code,
       redirect_uri: YOUR_REDIRECT_URI, // The `redirect_uri` used in the server needs to be the same as as initially used in the client.
     }),
     headers: {
-      'Content-type': 'application/json',
+      "Content-type": "application/json",
     },
-    method: 'POST',
+    method: "POST",
   });
-}
+
+  // The response body is your application's own callback output, so handle it
+  // however suits you. A failed sign in redirects to /auth/failure, whose
+  // `message` query parameter says why.
+  if (!response.ok) {
+    throw new Error(`Callback failed: ${response.status}`);
+  }
+
+  return response.text();
+};
 ```
 
 #### Note about mobile clients (iOS, Android)
@@ -347,6 +359,26 @@ In that case, ensure to send an additional parameter `redirect_uri=` (empty stri
 
 If you're making POST requests to `/auth/google_oauth2/callback` from another domain, then you need to make sure `'X-Requested-With': 'XMLHttpRequest'` header is included with your request, otherwise your server might respond with `OAuth2::Error, : Invalid Value` error.
 
+### Access Token Flow
+
+As an alternative to posting a one-time code, a client that already holds a Google access token can post that instead, as either a form parameter or a JSON body:
+
+```json
+{ "access_token": "ACCESS_TOKEN", "id_token": "ID_TOKEN" }
+```
+
+Prefer the One-time Code Flow above where you can. It is immune to replay attacks, and it lets the server obtain a refresh token. This flow exists for clients such as native mobile apps that have already completed sign-in through a Google SDK and hold tokens directly.
+
+`access_token` is required. The gem validates it with Google before using it, and rejects it unless its audience is your own `client_id` or one of `authorized_client_ids`. `uid` and the `info` section are then read from Google's userinfo endpoint using that token, so they always describe the account the access token really belongs to.
+
+`id_token` is optional. When present it is verified against Google's published signing keys, and its issuer, validity window, and audience are checked. Its audience must be your own `client_id` or one of `authorized_client_ids`. It must also describe the same user as the access token, established either through its `at_hash` claim or by matching the userinfo subject. Only then does it populate `extra.id_token`, and `extra.id_info` unless `skip_jwt` is set.
+
+An ID token that fails any of those checks is discarded and the sign-in continues without it, so `extra.id_info` may be absent even though authentication succeeded. An ID token kept from an earlier sign-in will usually have expired by then, so send the one Google issued alongside the access token you are posting.
+
+Other credential fields in the request are ignored. In particular a `refresh_token` or an expiry sent by the client is dropped rather than trusted, since neither can be verified, so `credentials.refresh_token` and `credentials.expires_at` are not populated in this flow.
+
+A request that carries no usable credential, such as an `id_token` with no `access_token`, fails with OmniAuth's standard `invalid_credentials` failure.
+
 ## Fixing Protocol Mismatch for `redirect_uri` in Rails
 
 Just set the `full_host` in OmniAuth based on the Rails.env.

data/examples/config.ru

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Sample app for Google OAuth2 Strategy
-# Make sure to setup the ENV variables GOOGLE_KEY and GOOGLE_SECRET
+# Make sure to setup the ENV variables GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
+# and RACK_COOKIE_SECRET
 # Run with "bundle exec rackup"
 
 require 'rubygems'
@@ -10,12 +11,11 @@ require 'sinatra'
 require 'omniauth'
 require 'omniauth-google-oauth2'
 
-# Do not use for production code.
-# This is only to make setup easier when running through the sample.
-#
-# If you do have issues with certs in production code, this could help:
-# http://railsapps.github.io/openssl-certificate-verify-failed.html
-OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE
+# OmniAuth re-raises authentication failures in development by default, and
+# `rackup` runs in development, so the sample would show a stack trace where a
+# deployed app redirects to /auth/failure. Clearing this lets the example
+# demonstrate the failure a real application would see.
+OmniAuth.config.failure_raise_out_environments = []
 
 # Main example app for omniauth-google-oauth2
 class App < Sinatra::Base
@@ -29,7 +29,7 @@ class App < Sinatra::Base
   use OmniAuth::Builder do
     # For additional provider examples please look at 'omni_auth.rb'
     # The key provider_ignores_state is only for AJAX flows. It is not recommended for normal logins.
-    provider :google_oauth2, ENV['GOOGLE_KEY'], ENV['GOOGLE_SECRET'], access_type: 'offline', prompt: 'consent', provider_ignores_state: true, scope: 'email,profile'
+    provider :google_oauth2, ENV['GOOGLE_CLIENT_ID'], ENV['GOOGLE_CLIENT_SECRET'], access_type: 'offline', prompt: 'consent', provider_ignores_state: true, scope: 'email,profile'
   end
 
   get '/' do
@@ -61,7 +61,7 @@ class App < Sinatra::Base
             const oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
 
             const params = new URLSearchParams({
-              client_id: '#{ENV['GOOGLE_KEY']}',
+              client_id: '#{ENV['GOOGLE_CLIENT_ID']}',
               prompt: 'select_account',
               redirect_uri: 'http://localhost:3000/callback',
               response_type: 'code',
@@ -91,20 +91,37 @@ class App < Sinatra::Base
       </head>
 
       <body>
-        <p>Redirected</p>
+        <h1>Google OAuth2 Example</h1>
+        <p>Posting the one-time code to the callback. The auth hash appears below.</p>
+        <p id="status">Working...</p>
+        <code id="result" style="white-space: pre-wrap; overflow-wrap: anywhere; display: block;"></code>
 
         <script>
           const handleGoogleOauthCallback = async () => {
             const params = new URL(document.location.toString()).searchParams;
             const code = params.get('code');
-
-            const response = fetch('http://localhost:3000/auth/google_oauth2/callback', {
-              body: JSON.stringify({ code, redirect_uri: 'http://localhost:3000/callback' }),
-              headers: {
-                'Content-type': 'application/json',
-              },
-              method: 'POST',
-            });
+            const status = document.querySelector('#status');
+            const output = document.querySelector('#result');
+
+            if (!code) {
+              status.textContent = 'No code parameter in the URL.';
+              return;
+            }
+
+            try {
+              const response = await fetch('http://localhost:3000/auth/google_oauth2/callback', {
+                body: JSON.stringify({ code, redirect_uri: 'http://localhost:3000/callback' }),
+                headers: {
+                  'Content-type': 'application/json',
+                },
+                method: 'POST',
+              });
+
+              status.textContent = `${response.status} ${response.statusText}`;
+              output.textContent = await response.text();
+            } catch (error) {
+              status.textContent = `Request failed: ${error}`;
+            }
           }
 
           handleGoogleOauthCallback();
@@ -132,13 +149,15 @@ class App < Sinatra::Base
     end
   end
 
+  # omniauth.auth is never set on a failure, so report what OmniAuth does pass:
+  # the failure reason and the strategy that produced it.
   get '/auth/failure' do
     content_type 'text/plain'
-    begin
-      request.env['omniauth.auth'].to_hash.inspect
-    rescue StandardError
-      'No Data'
-    end
+    <<~TEXT
+      Authentication failed
+      message:  #{params['message'] || 'unknown'}
+      strategy: #{params['strategy'] || 'unknown'}
+    TEXT
   end
 end
 

data/lib/omniauth/google_oauth2/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module GoogleOauth2
-    VERSION = '1.2.2'
+    VERSION = '1.2.3'
   end
 end