googleauth 0.10.0 → 0.14.0

data/lib/googleauth/credentials.rb

@@ -47,6 +47,8 @@ module Google
       # The default target audience ID to be used when none is provided during initialization.
       AUDIENCE = "https://oauth2.googleapis.com/token".freeze
 
+      @audience = @scope = @target_audience = @env_vars = @paths = nil
+
       ##
       # The default token credential URI to be used when none is provided during initialization.
       # The URI is the authorization server's HTTP endpoint capable of issuing tokens and
@@ -97,20 +99,25 @@ module Google
       # A scope is an access range defined by the authorization server.
       # The scope can be a single value or a list of values.
       #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
       # @return [String, Array<String>]
       #
       def self.scope
         return @scope unless @scope.nil?
 
-        tmp_scope = []
-        # Pull in values is the SCOPE constant exists.
-        tmp_scope << const_get(:SCOPE) if const_defined? :SCOPE
-        tmp_scope.flatten.uniq
+        Array(const_get(:SCOPE)).flatten.uniq if const_defined? :SCOPE
       end
 
       ##
       # Sets the default scope to be used when none is provided during initialization.
       #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
       # @param [String, Array<String>] new_scope
       # @return [String, Array<String>]
       #
@@ -119,6 +126,34 @@ module Google
         @scope = new_scope
       end
 
+      ##
+      # The default final target audience for ID tokens, to be used when none
+      # is provided during initialization.
+      #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
+      # @return [String]
+      #
+      def self.target_audience
+        @target_audience
+      end
+
+      ##
+      # Sets the default final target audience for ID tokens, to be used when none
+      # is provided during initialization.
+      #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
+      # @param [String] new_target_audience
+      #
+      def self.target_audience= new_target_audience
+        @target_audience = new_target_audience
+      end
+
       ##
       # The environment variables to search for credentials. Values can either be a file path to the
       # credentials file, or the JSON contents of the credentials file.
@@ -185,6 +220,13 @@ module Google
       #
       attr_reader :project_id
 
+      ##
+      # Identifier for a separate project used for billing/quota, if any.
+      #
+      # @return [String,nil]
+      #
+      attr_reader :quota_project_id
+
       # @private Delegate client methods to the client object.
       extend Forwardable
 
@@ -201,6 +243,9 @@ module Google
       #   @return [String, Array<String>] The scope for this client. A scope is an access range
       #     defined by the authorization server. The scope can be a single value or a list of values.
       #
+      # @!attribute [r] target_audience
+      #   @return [String] The final target audience for ID tokens returned by this credential.
+      #
       # @!attribute [r] issuer
       #   @return [String] The issuer ID associated with this client.
       #
@@ -213,9 +258,7 @@ module Google
       #
       def_delegators :@client,
                      :token_credential_uri, :audience,
-                     :scope, :issuer, :signing_key, :updater_proc
-
-      # rubocop:disable Metrics/AbcSize
+                     :scope, :issuer, :signing_key, :updater_proc, :target_audience
 
       ##
       # Creates a new Credentials instance with the provided auth credentials, and with the default
@@ -236,23 +279,15 @@ module Google
       #   * +:default_connection+ - the default connection to use for the client
       #
       def initialize keyfile, options = {}
-        scope = options[:scope]
         verify_keyfile_provided! keyfile
         @project_id = options["project_id"] || options["project"]
+        @quota_project_id = options["quota_project_id"]
         if keyfile.is_a? Signet::OAuth2::Client
-          @client = keyfile
-          @project_id ||= keyfile.project_id if keyfile.respond_to? :project_id
+          update_from_signet keyfile
         elsif keyfile.is_a? Hash
-          hash = stringify_hash_keys keyfile
-          hash["scope"] ||= scope
-          @client = init_client hash, options
-          @project_id ||= (hash["project_id"] || hash["project"])
+          update_from_hash keyfile, options
         else
-          verify_keyfile_exists! keyfile
-          json = JSON.parse ::File.read(keyfile)
-          json["scope"] ||= scope
-          @project_id ||= (json["project_id"] || json["project"])
-          @client = init_client json, options
+          update_from_filepath keyfile, options
         end
         CredentialsLoader.warn_if_cloud_sdk_credentials @client.client_id
         @project_id ||= CredentialsLoader.load_gcloud_project_id
@@ -261,7 +296,6 @@ module Google
         @paths = nil
         @scope = nil
       end
-      # rubocop:enable Metrics/AbcSize
 
       ##
       # Creates a new Credentials instance with auth credentials acquired by searching the
@@ -323,7 +357,8 @@ module Google
       # @private Lookup Credentials using Google::Auth.get_application_default.
       def self.from_application_default options
         scope = options[:scope] || self.scope
-        client = Google::Auth.get_application_default scope
+        auth_opts = { target_audience: options[:target_audience] || target_audience }
+        client = Google::Auth.get_application_default scope, auth_opts
         new client, options
       end
 
@@ -362,14 +397,46 @@ module Google
         options["token_credential_uri"] ||= self.class.token_credential_uri
         options["audience"] ||= self.class.audience
         options["scope"] ||= self.class.scope
+        options["target_audience"] ||= self.class.target_audience
 
+        if !Array(options["scope"]).empty? && options["target_audience"]
+          raise ArgumentError, "Cannot specify both scope and target_audience"
+        end
+
+        needs_scope = options["target_audience"].nil?
         # client options for initializing signet client
         { token_credential_uri: options["token_credential_uri"],
           audience:             options["audience"],
-          scope:                Array(options["scope"]),
+          scope:                (needs_scope ? Array(options["scope"]) : nil),
+          target_audience:      options["target_audience"],
           issuer:               options["client_email"],
           signing_key:          OpenSSL::PKey::RSA.new(options["private_key"]) }
       end
+
+      def update_from_signet client
+        @project_id ||= client.project_id if client.respond_to? :project_id
+        @quota_project_id ||= client.quota_project_id if client.respond_to? :quota_project_id
+        @client = client
+      end
+
+      def update_from_hash hash, options
+        hash = stringify_hash_keys hash
+        hash["scope"] ||= options[:scope]
+        hash["target_audience"] ||= options[:target_audience]
+        @project_id ||= (hash["project_id"] || hash["project"])
+        @quota_project_id ||= hash["quota_project_id"]
+        @client = init_client hash, options
+      end
+
+      def update_from_filepath path, options
+        verify_keyfile_exists! path
+        json = JSON.parse ::File.read(path)
+        json["scope"] ||= options[:scope]
+        json["target_audience"] ||= options[:target_audience]
+        @project_id ||= (json["project_id"] || json["project"])
+        @quota_project_id ||= json["quota_project_id"]
+        @client = init_client json, options
+      end
     end
   end
 end

data/lib/googleauth/id_tokens.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require "googleauth/id_tokens/errors"
+require "googleauth/id_tokens/key_sources"
+require "googleauth/id_tokens/verifier"
+
+module Google
+  module Auth
+    ##
+    # ## 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
+    # {Google::Auth::IDTokens::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"
+    #
+    module IDTokens
+      ##
+      # A list of issuers expected for Google OIDC-issued tokens.
+      #
+      # @return [Array<String>]
+      #
+      OIDC_ISSUERS = ["accounts.google.com", "https://accounts.google.com"].freeze
+
+      ##
+      # A list of issuers expected for Google IAP-issued tokens.
+      #
+      # @return [Array<String>]
+      #
+      IAP_ISSUERS = ["https://cloud.google.com/iap"].freeze
+
+      ##
+      # The URL for Google OAuth2 V3 public certs
+      #
+      # @return [String]
+      #
+      OAUTH2_V3_CERTS_URL = "https://www.googleapis.com/oauth2/v3/certs"
+
+      ##
+      # The URL for Google IAP public keys
+      #
+      # @return [String]
+      #
+      IAP_JWK_URL = "https://www.gstatic.com/iap/verify/public_key-jwk"
+
+      class << self
+        ##
+        # The key source providing public keys that can be used to verify
+        # ID tokens issued by Google OIDC.
+        #
+        # @return [Google::Auth::IDTokens::JwkHttpKeySource]
+        #
+        def oidc_key_source
+          @oidc_key_source ||= JwkHttpKeySource.new OAUTH2_V3_CERTS_URL
+        end
+
+        ##
+        # The key source providing public keys that can be used to verify
+        # ID tokens issued by Google IAP.
+        #
+        # @return [Google::Auth::IDTokens::JwkHttpKeySource]
+        #
+        def iap_key_source
+          @iap_key_source ||= JwkHttpKeySource.new IAP_JWK_URL
+        end
+
+        ##
+        # Reset all convenience key sources. Used for testing.
+        # @private
+        #
+        def forget_sources!
+          @oidc_key_source = @iap_key_source = nil
+          self
+        end
+
+        ##
+        # A convenience method that verifies a token allegedly issued by Google
+        # OIDC.
+        #
+        # @param token [String] The ID token to verify
+        # @param aud [String,Array<String>,nil] The expected audience. At least
+        #     one `aud` field in the token must match at least one of the
+        #     provided audiences, or the verification will fail with
+        #     {Google::Auth::IDToken::AudienceMismatchError}. If `nil` (the
+        #     default), no audience checking is performed.
+        # @param azp [String,Array<String>,nil] The expected authorized party
+        #     (azp). At least one `azp` field in the token must match at least
+        #     one of the provided values, or the verification will fail with
+        #     {Google::Auth::IDToken::AuthorizedPartyMismatchError}. If `nil`
+        #     (the default), no azp checking is performed.
+        # @param aud [String,Array<String>,nil] The expected audience. At least
+        #     one `iss` field in the token must match at least one of the
+        #     provided issuers, or the verification will fail with
+        #     {Google::Auth::IDToken::IssuerMismatchError}. If `nil`, no issuer
+        #     checking is performed. Default is to check against {OIDC_ISSUERS}.
+        #
+        # @return [Hash] The decoded token payload.
+        # @raise [KeySourceError] if the key source failed to obtain public keys
+        # @raise [VerificationError] if the token verification failed.
+        #     Additional data may be available in the error subclass and message.
+        #
+        def verify_oidc token,
+                        aud: nil,
+                        azp: nil,
+                        iss: OIDC_ISSUERS
+
+          verifier = Verifier.new key_source: oidc_key_source,
+                                  aud:        aud,
+                                  azp:        azp,
+                                  iss:        iss
+          verifier.verify token
+        end
+
+        ##
+        # A convenience method that verifies a token allegedly issued by Google
+        # IAP.
+        #
+        # @param token [String] The ID token to verify
+        # @param aud [String,Array<String>,nil] The expected audience. At least
+        #     one `aud` field in the token must match at least one of the
+        #     provided audiences, or the verification will fail with
+        #     {Google::Auth::IDToken::AudienceMismatchError}. If `nil` (the
+        #     default), no audience checking is performed.
+        # @param azp [String,Array<String>,nil] The expected authorized party
+        #     (azp). At least one `azp` field in the token must match at least
+        #     one of the provided values, or the verification will fail with
+        #     {Google::Auth::IDToken::AuthorizedPartyMismatchError}. If `nil`
+        #     (the default), no azp checking is performed.
+        # @param aud [String,Array<String>,nil] The expected audience. At least
+        #     one `iss` field in the token must match at least one of the
+        #     provided issuers, or the verification will fail with
+        #     {Google::Auth::IDToken::IssuerMismatchError}. If `nil`, no issuer
+        #     checking is performed. Default is to check against {IAP_ISSUERS}.
+        #
+        # @return [Hash] The decoded token payload.
+        # @raise [KeySourceError] if the key source failed to obtain public keys
+        # @raise [VerificationError] if the token verification failed.
+        #     Additional data may be available in the error subclass and message.
+        #
+        def verify_iap token,
+                       aud: nil,
+                       azp: nil,
+                       iss: IAP_ISSUERS
+
+          verifier = Verifier.new key_source: iap_key_source,
+                                  aud:        aud,
+                                  azp:        azp,
+                                  iss:        iss
+          verifier.verify token
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/id_tokens/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+module Google
+  module Auth
+    module IDTokens
+      ##
+      # Failed to obtain keys from the key source.
+      #
+      class KeySourceError < StandardError; end
+
+      ##
+      # Failed to verify a token.
+      #
+      class VerificationError < StandardError; end
+
+      ##
+      # Failed to verify a token because it is expired.
+      #
+      class ExpiredTokenError < VerificationError; end
+
+      ##
+      # Failed to verify a token because its signature did not match.
+      #
+      class SignatureError < VerificationError; end
+
+      ##
+      # Failed to verify a token because its issuer did not match.
+      #
+      class IssuerMismatchError < VerificationError; end
+
+      ##
+      # Failed to verify a token because its audience did not match.
+      #
+      class AudienceMismatchError < VerificationError; end
+
+      ##
+      # Failed to verify a token because its authorized party did not match.
+      #
+      class AuthorizedPartyMismatchError < VerificationError; end
+    end
+  end
+end