Reference documentation and code samples for the googleauth module Google::Auth::IDTokens.
Verifying Google ID tokens
This module verifies ID tokens issued by Google. This can be used to authenticate signed-in users using OpenID Connect. See https://developers.google.com/identity/sign-in/web/backend-auth for more information.
Basic usage
To verify an ID token issued by Google accounts:
payload = Google::Auth:: IDTokens
. verify_oidc
the_token,
aud: "my-app-client-id"
If verification succeeds, you will receive the token's payload as a hash. If verification fails, an exception (normally a subclass of VerificationError ) will be raised.
To verify an ID token issued by the Google identity-aware proxy (IAP):
payload = Google::Auth:: IDTokens
. verify_iap
the_token,
aud: "my-app-client-id"
These methods will automatically download and cache the Google public
keys necessary to verify these tokens. They will also automatically
verify the issuer ( iss
) field for their respective types of ID tokens.
Advanced usage
If you want to provide your own public keys, either by pointing at a custom URI or by providing the key data directly, use the Verifier class and pass in a key source.
To point to a custom URI that returns a JWK set:
source = Google::Auth::IDTokens::JwkHttpKeySource.new "https://example.com/jwk"
verifier = Google::Auth::IDTokens::Verifier.new key_source: source
payload = verifier.verify the_token, aud: "my-app-client-id"
To provide key data directly:
jwk_data = {
keys: [
{
alg: "ES256",
crv: "P-256",
kid: "LYyP2g",
kty: "EC",
use: "sig",
x: "SlXFFkJ3JxMsXyXNrqzE3ozl_0913PmNbccLLWfeQFU",
y: "GLSahrZfBErmMUcHP0MGaeVnJdBwquhrhQ8eP05NfCI"
}
]
}
source = Google::Auth:: IDTokens
:: StaticKeySource
.from_jwk_set jwk_data
verifier = Google::Auth:: IDTokens
::Verifier key_source: source
payload = verifier. verify
the_token, aud: "my-app-client-id"
Methods
.iap_key_source
def
self
.
iap_key_source
()
-
>
Google
::
Auth
::
IDTokens
::
JwkHttpKeySource
The key source providing public keys that can be used to verify ID tokens issued by Google IAP.
.oidc_key_source
def
self
.
oidc_key_source
()
-
>
Google
::
Auth
::
IDTokens
::
JwkHttpKeySource
The key source providing public keys that can be used to verify ID tokens issued by Google OIDC.
.verify_iap
def
self
.
verify_iap
(
token
,
aud
:
nil
,
azp
:
nil
,
iss
:
IAP_ISSUERS
)
-
>
Hash
A convenience method that verifies a token allegedly issued by Google IAP.
- token(String) — The ID token to verify
- aud(String, Array<String>, nil) (defaults to: nil)
— The expected audience. At least
one
audfield in the token must match at least one of the provided audiences, or the verification will fail with {Google::Auth::IDToken::AudienceMismatchError}. Ifnil(the default), no audience checking is performed. - azp(String, Array<String>, nil) (defaults to: nil)
— The expected authorized party
(azp). At least one
azpfield in the token must match at least one of the provided values, or the verification will fail with {Google::Auth::IDToken::AuthorizedPartyMismatchError}. Ifnil(the default), no azp checking is performed. - iss(String, Array<String>, nil) (defaults to: IAP_ISSUERS)
— The expected issuer. At least
one
issfield in the token must match at least one of the provided issuers, or the verification will fail with {Google::Auth::IDToken::IssuerMismatchError}. Ifnil, no issuer checking is performed. Default is to check against {IAP_ISSUERS}.
- (Hash) — The decoded token payload.
- ( KeySourceError ) — if the key source failed to obtain public keys
- ( VerificationError ) — if the token verification failed. Additional data may be available in the error subclass and message.
.verify_oidc
def
self
.
verify_oidc
(
token
,
aud
:
nil
,
azp
:
nil
,
iss
:
OIDC_ISSUERS
)
-
>
Hash
A convenience method that verifies a token allegedly issued by Google OIDC.
- token(String) — The ID token to verify
- aud(String, Array<String>, nil) (defaults to: nil)
— The expected audience. At least
one
audfield in the token must match at least one of the provided audiences, or the verification will fail with {Google::Auth::IDToken::AudienceMismatchError}. Ifnil(the default), no audience checking is performed. - azp(String, Array<String>, nil) (defaults to: nil)
— The expected authorized party
(azp). At least one
azpfield in the token must match at least one of the provided values, or the verification will fail with {Google::Auth::IDToken::AuthorizedPartyMismatchError}. Ifnil(the default), no azp checking is performed. - iss(String, Array<String>, nil) (defaults to: OIDC_ISSUERS)
— The expected issuer. At least
one
issfield in the token must match at least one of the provided issuers, or the verification will fail with {Google::Auth::IDToken::IssuerMismatchError}. Ifnil, no issuer checking is performed. Default is to check against {OIDC_ISSUERS}.
- (Hash) — The decoded token payload.
- ( KeySourceError ) — if the key source failed to obtain public keys
- ( VerificationError ) — if the token verification failed. Additional data may be available in the error subclass and message.
Constants
OIDC_ISSUERS
value:
["accounts.google.com", "https://accounts.google.com"].freeze
A list of issuers expected for Google OIDC-issued tokens.
IAP_ISSUERS
value:
["https://cloud.google.com/iap"].freeze
A list of issuers expected for Google IAP-issued tokens.
OAUTH2_V3_CERTS_URL
value:
" https://www.googleapis.com/oauth2/v3/certs"
;
The URL for Google OAuth2 V3 public certs
IAP_JWK_URL
value:
" https://www.gstatic.com/iap/verify/public_key-jwk"
;
The URL for Google IAP public keys
