# OmniAuth::GoogleIdToken

A [omnitauth](https://github.com/omniauth/omniauth) strategy primarily used for validating Google ID tokens
(JWT encoded) generated by Google authentication servers. As with other Omniauth strategies, it can also
redirect to Google's Sign In page.

As a validation strategy only this used by backend servers to validate Google ID tokens (Google
authenticated users) passed on by mobile or webapps e.g.
[ios](https://developers.google.com/identity/sign-in/ios/backend-auth),
[Android](https://developers.google.com/identity/sign-in/android/backend-auth),
[websites](https://developers.google.com/identity/sign-in/web/backend-auth).

This makes use of [google-id-token](https://github.com/google/google-id-token) for validating the ID token.

## Installation

Add this line to your application's Gemfile:

    gem 'omniauth-google-id-token'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install omniauth-google-id-token

## Usage

You use OmniAuth::Strategies::GoogleIdToken just like you do any other OmniAuth strategy:

```ruby
use OmniAuth::Strategies::GoogleIdToken, aud_claim: '123.apps.googleusercontent.com', azp_claim: '123.apps.googleusercontent.com'
```

If this strategy is used primarily for validating a Google ID token, then the only required fields are
aud_claim and azp_claim.

If this strategy is also used for redirecting a user to the Google Sign In page before validation,
then a client_id is also required. An example of the URL can be found at
https://developers.google.com/identity/protocols/OAuth2WebServer#handlingresponse Sample OAuth 2.0 server
response section.

* **name:** The name of the strategy. The default name is `google_id_token` 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`.
* **cert:** the x509 certificate can be provided to manually define a certificate to validate the tokens.
* **expiry:** Expiry defines the the time (in seconds) in which the cached Google certificates are valid.
* **uid_claim:** this determines which claim will be used to uniquely identify the user. Defaults
  to `email`
* **client_id:** The client ID string that you obtain from the [API Console](https://console.developers.google.com/),
  as described in [Obtain OAuth 2.0 credentials](https://developers.google.com/identity/protocols/OpenIDConnect#getcredentials)
* **aud_claim:** Identifies the audience that this ID token is intended for. It must be one of the OAuth 2.0 client
  IDs of your application
* **azp_claim:** The client_id of the authorized presenter. This claim is only needed when the party requesting the
  ID token is not the same as the audience of the ID token. This may be the case at Google for hybrid apps where a
  web application and Android app have a different client_id but share the same project.
* **required_claims:** array of claims that are required to make this a valid authentication call.
  Defaults to `['name', 'email']`
* **info_map:** array mapping claim values to info hash values. Defaults to mapping `name` and `email`
  to the same in the info hash.

### Authentication Process

When you authenticate through `omniauth-google-id-token` you can send users to `/auth/googleidtoken`
and it will redirect them to the URL https://accounts.google.com/o/oauth2/auth (and example can be
found at https://developers.google.com/identity/protocols/OAuth2WebServer#handlingresponse
Sample OAuth 2.0 server response).

From there, Google generates a ID token and sends to the redirect_uri passed in URL query params.
The redirect_uri will look like '/auth/googleidtoken/callback`. This is the endpoint to send the id token
to if coming from a mobile or web app looking to validate a user with the backend server:

    /auth/googleidtoken/callback?id_token=ENCODEDJWTGOESHERE

## Contributing

1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request