# omniauth-google-oauth2: Rails Setup, Configuration, and Limits

> omniauth-google-oauth2 adds Google OAuth2 sign-in to Ruby applications through OmniAuth. It suits Rails applications that need Google identity data, configurable scopes, and established OmniAuth provider integration.

**zquestz/omniauth-google-oauth2** — Oauth2 strategy for Google

- Repository: https://github.com/zquestz/omniauth-google-oauth2
- Stars: 1,524 · Forks: 417
- Language: Ruby
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/zquestz-omniauth-google-oauth2

## Where omniauth-google-oauth2 Fits in a Ruby Authentication Stack

omniauth-google-oauth2 solves a narrow but common problem: connecting a Ruby application's OmniAuth middleware to Google through OAuth2. It is intended for applications that already recognize OmniAuth providers, consume an OmniAuth authentication hash, and want to start authentication at a provider-specific URL. The README gives `/auth/google_oauth2` as the default entry point. Changing the `name` option changes both the request URL and the provider key in that authentication hash.

This is not a complete user-account system. Based on the repository layout and README, the project is a strategy gem, with its implementation under `lib/`, tests under `spec/`, and an example application under `examples/`. The strategy handles the Google-specific OmniAuth integration, while the host application remains responsible for its callback, session, account-linking, authorization, and persistence decisions. The README does not define a database schema or prescribe how a returned Google identity should become a local user.

It is also narrower than a general Google API client. Its stated purpose is authentication through OAuth2 in OmniAuth. Configuration such as `scope`, `redirect_uri`, `prompt`, and `access_type` affects authorization requests, but the README does not describe convenience methods for calling Google Drive, Gmail, Calendar, or other APIs. Those tasks may depend on separately granted permissions and separate API clients, neither of which this repository claims to provide.

## The Google OAuth2 Request and Authentication-Hash Flow

The documented request flow begins when a browser reaches the OmniAuth strategy URL. The strategy sends the user into Google's OAuth2 authentication process, with the configured client credentials, requested permissions, redirect behavior, and optional prompt settings. After Google authenticates or rejects the request, control returns through the OAuth2 redirect path to the OmniAuth callback flow. The README establishes `/auth/google_oauth2` as the initial authentication URL but does not document the complete callback path.

The strategy produces an OmniAuth authentication hash containing Google identity information. Some specific outputs are documented. By default, decoded ID token claims appear in `extra.id_info`, and a decoded ID token is exposed as `extra.id_token`. The `openid_realm` setting can also cause an `openid_id` value to appear under `['extra']['id_info']`, supporting applications migrating from OpenID-based authentication.

Token handling has a distinction that matters when assessing identity data. Setting `skip_jwt` removes decoded ID token claims from `extra.id_info`, reducing the auth hash. It does not skip verification of an ID token supplied through a direct access-token callback, because that token remains available as `extra.id_token` and may be exposed to the application. The strategy also exposes `jwt_leeway`, which defaults to 60 seconds, and `authorized_client_ids`, which adds accepted token audiences while retaining the configured `client_id`.

The README does not provide a field-by-field authentication-hash schema or describe callback error handling. An adopter should therefore inspect the actual auth hash contract before depending on a particular field or custom callback behavior.

## Installing the Gem and Enabling Google Sign-in in Rails

The documented installation path is the Ruby Bundler workflow. Add the published package to the application's `Gemfile`. The README does not prescribe a version constraint, so the application should record a version according to its own dependency policy.

```ruby
gem 'omniauth-google-oauth2'
```

Install the bundle from the directory containing that `Gemfile`. This command resolves the gem and its declared dependencies according to the application's lock state.

```bash
bundle install
```

Create or edit `config/initializers/omniauth.rb`. The documented middleware registration reads the Google client identifier and secret from environment variables rather than placing credentials in source control. It also restricts allowed request methods to GET.

```ruby
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :google_oauth2, ENV['GOOGLE_CLIENT_ID'], ENV['GOOGLE_CLIENT_SECRET']
end
OmniAuth.config.allowed_request_methods = %i[get]
```

Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in the application's runtime environment using the Client ID and Client Secret created in Google Cloud Console. After restarting the Rails application, browse to `/auth/google_oauth2`. The browser should enter Google's authentication and consent flow, then return through the configured OmniAuth OAuth2 callback. The README does not document local environment files, production secret injection, or callback URLs, so deployment configuration must be established outside this snippet.

The Google console setup also requires selecting a project and completing the OAuth consent screen with an email address and product name. The README says to wait 10 minutes for those changes to take effect.

## Scopes, Consent, Offline Access, and Domain Restrictions

Google requires every effective scope set to include at least `email` or `profile`. The strategy uses both by default, but specifying `scope` replaces those defaults. This is an important configuration trap. An application that adds only an API permission may create an invalid authorization request unless it explicitly retains one required identity scope. During development, changing the initializer's scope requires restarting the application server.

Scope names under `https://www.googleapis.com/auth/` may be shortened, but other permissions require their full URL. The README uses Google Docs as the example: `books` can use the shorter form because it belongs to that prefix, while access to a user's Docs requires `https://docs.google.com/feeds/`. A broader scope should therefore not be selected merely because it is convenient. The application must establish why each permission is necessary and ensure its Google Cloud consent configuration matches the requested access.

The default `access_type` is `offline`, which asks Google to send a refresh token for use when the user is absent from the browser. Applications that should operate in online access can set it to `online`. This is a policy decision with operational consequences: offline access implies consideration of refresh-token storage, revocation, and account lifecycle, although the README does not document the gem's storage helpers.

Two options narrow the authorization experience. `hd` can restrict sign-in to one hosted domain or an array of domains. `login_hint` accepts an email address or Google's `sub` identifier when the application already knows which account should be selected. The `prompt` option supports `none`, `consent`, and `select_account`; the README explicitly warns that `none` returns an error when authentication or prior consent is unavailable. The `include_granted_scopes` and `enable_granular_consent` settings expose Google's incremental authorization and granular permission behavior.

## Image Requests, Redirect Control, and OmniAuth Provider Naming

The strategy can shape profile image requests without downloading or resizing the image itself. `image_aspect_ratio` accepts `original`, `square`, or `smart`, with `original` as the default. `image_size` accepts a width value or a hash containing `width` and `height`. Google returns an image according to the selected ratio and size rules described in the README. Consumers should not assume that requesting dimensions guarantees exact storage dimensions in the auth hash without checking how the strategy and Google present the returned URL.

The `redirect_uri` option overrides the redirect URI used by the gem. That flexibility can support different deployment environments, but it also makes configuration alignment important. The README does not document registration requirements for callback URLs or enumerate accepted URI forms, so an adopter must compare the configured redirect URI with the OAuth client in Google Cloud rather than inferring a format.

Provider naming is part of the public contract. The default name is `google_oauth2`, producing `/auth/google_oauth2` and a `provider` value of `google_oauth2`. Changing `name` to `google` changes the URL to `/auth/google` and the provider key to `google`. Any routes, callback checks, logging filters, tests, or account-linking code that assumes the default name must be updated at the same time. This is especially relevant because the provider name is not merely cosmetic.

## Maintenance Evidence, Dependency Changes, and License Unknowns

The repository is not archived, and the last push was on 2026-08-31. That recent commit is consistent with continuing project activity rather than abandonment. The release history also lists v1.2.3 on 2026-08-31, v1.2.2 on 2026-02-24, and v1.2.1 on 2025-01-19. These records support recent release work, although they do not establish how frequently every part of the repository will change.

Upgrades require normal Ruby dependency management. Because this strategy is used by an OmniAuth application, changes in this gem can interact with OmniAuth callback behavior, Rack middleware registration, token libraries, and the host framework. The README does not state Ruby version support, minimum dependency versions, or a compatibility matrix. The repository includes `omniauth-google-oauth2.gemspec`, `Gemfile`, `CHANGELOG.md`, and `spec/`, but the review does not include their contents, so no stronger compatibility claim can be made.

The repository record identifies the license as unknown. No license identifier appears in the README or repository metadata available for this review. An organization should inspect the actual `LICENSE` file and gemspec before copying, modifying, redistributing, or depending on the package. This is a licensing verification requirement, not a claim about permitted use.

## When Direct Google OAuth2 Is the Better Integration

The clearest alternative is a direct Google OAuth2 integration built into the application without using OmniAuth or this strategy. Google's OAuth2 documentation, linked by the README, describes the underlying protocol. A direct implementation would own the authorization request, callback route, authorization-code exchange, token storage, identity mapping, and error handling rather than relying on OmniAuth middleware and its authentication hash.

That approach is appropriate when the application does not use OmniAuth, needs callback semantics outside the strategy's model, or requires control over token persistence that the README does not describe. It avoids adding a provider-specific strategy to an authentication stack, but it also replaces the gem's Google-specific option handling with application code. The trade-off is implementation responsibility: direct code can fit a custom architecture, while omniauth-google-oauth2 reduces the work required to register and consume Google through OmniAuth.

omniauth-google-oauth2 is the wrong tool when OAuth2 authentication is only one incidental part of a larger Google API integration. The README focuses on OmniAuth sign-in and authorization parameters, not on API request clients or resource synchronization. It is also unsuitable if the application cannot accept GET as an OmniAuth request method, because the documented example explicitly sets `OmniAuth.config.allowed_request_methods` to `%i[get]`.

## Conclusion

Rails teams that already use OmniAuth and need Google sign-in should evaluate this strategy, while applications needing a non-OmniAuth callback flow should implement Google OAuth2 directly. Before adoption, verify the requested scopes, offline access requirements, ID token handling, Google Cloud credentials, and the project's unspecified license terms.

## FAQ

### How do I install omniauth-google-oauth2 in a Rails application?

Add `gem 'omniauth-google-oauth2'` to the `Gemfile`, run `bundle install`, and register the provider through `OmniAuth::Builder` in `config/initializers/omniauth.rb`.

### Which Google scopes does omniauth-google-oauth2 request by default?

The strategy requests `email` and `profile` by default. A custom `scope` replaces those defaults, so the custom list must still include at least one of the two required scopes.

### Does omniauth-google-oauth2 skip ID token verification when skip_jwt is enabled?

No. `skip_jwt` omits decoded claims from `extra.id_info`, but an ID token supplied through a direct access-token callback is still verified and may remain available as `extra.id_token`.

### What happens when omniauth-google-oauth2 changes scopes during development?

The README says the application server must be restarted after changing the scope in the initializer. The next request should use the revised authorization configuration.

## Sources

- [Issues](https://github.com/zquestz/omniauth-google-oauth2/issues)
- [README](https://github.com/zquestz/omniauth-google-oauth2/blob/master/README.md)
- [Releases](https://github.com/zquestz/omniauth-google-oauth2/releases)
- [zquestz/omniauth-google-oauth2 on GitHub](https://github.com/zquestz/omniauth-google-oauth2)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zquestz-omniauth-google-oauth2