custom-adal 1.0.1

data/lib/adal/authentication_parameters.rb

@@ -0,0 +1,126 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require_relative './logging'
+require_relative './util'
+
+require 'net/http'
+require 'uri'
+
+module ADAL
+  # Authentication parameters from an unauthorized 401 response from a resource
+  # server that can be used to create an AuthenticationContext.
+  class AuthenticationParameters
+    extend Logging
+    include Util
+
+    AUTHENTICATE_HEADER = 'www-authenticate'
+    AUTHORITY_KEY = 'authorization_uri'
+    RESOURCE_KEY = 'resource'
+
+    BEARER_CHALLENGE_VALIDATION = /^\s*Bearer\s+([^,\s="]+?)="?([^"]*?)"?\s*
+      (,\s*([^,\s="]+?)="([^:]*?)"\s*)*$/x
+    private_constant :BEARER_CHALLENGE_VALIDATION
+    FIRST_KEY_VALUE = /^\s*Bearer\s+([^, \s="]+?)="([^"]*?)"\s*/
+    private_constant :FIRST_KEY_VALUE
+    OTHER_KEY_VALUE = /(?:,\s*([^,\s="]+?)="([^"]*?)"\s*)/
+    private_constant :OTHER_KEY_VALUE
+
+    attr_reader :authority_uri
+    attr_reader :resource
+
+    ##
+    # Creates authentication parameters from the address of the resource. The
+    # resource server must respond with 401 unauthorized response with a
+    # www-authenticate header containing the authentication parameters.
+    #
+    # @param URI resource_url
+    #   The address of the desired resource.
+    # @return AuthenticationParameters
+    def self.create_from_resource_url(resource_url)
+      logger.verbose('Attempting to retrieve authentication parameters from ' \
+                     "#{resource_url}.")
+      response = Net::HTTP.post_form(URI.parse(resource_url.to_s), {})
+      unless response.key? AUTHENTICATE_HEADER
+        fail ArgumentError, 'The specified resource uri does not support ' \
+          'OAuth challenges.'
+      end
+      create_from_authenticate_header(response[AUTHENTICATE_HEADER])
+    end
+
+    ##
+    # Creates an AuthenticationParameters object from a www-authenticate
+    # response header.
+    #
+    # @param String challenge
+    #   The raw www-authenticate header.
+    # @return AuthenticationParameters
+    def self.create_from_authenticate_header(challenge)
+      params = parse_challenge(challenge)
+      if params.nil? || !params.key?(AUTHORITY_KEY)
+        logger.warn('Unable to create AuthenticationParameters from header ' \
+                    "#{challenge}.")
+        return
+      end
+      logger.verbose("Authentication header #{challenge} was successfully " \
+                     'parsed as an OAuth challenge into a parameters hash.')
+      AuthenticationParameters.new(
+        params[AUTHORITY_KEY], params[RESOURCE_KEY])
+    end
+
+    ##
+    # Parses a challenge from the www-authenticate header into a hash of
+    # parameters.
+    #
+    # @param String challenge
+    # @return Hash
+    def self.parse_challenge(challenge)
+      if challenge !~ BEARER_CHALLENGE_VALIDATION
+        logger.warn("#{challenge} is not parseable as an RFC6750 OAuth2 " \
+                    'challenge.')
+        return
+      end
+      Hash[challenge.scan(FIRST_KEY_VALUE) + challenge.scan(OTHER_KEY_VALUE)]
+    end
+    private_class_method :parse_challenge
+
+    ##
+    # Constructs a new AuthenticationParameters.
+    #
+    # @param String|URI authority_uri
+    #   The uri of the authority server, including both host and tenant.
+    # @param String
+    def initialize(authority_uri, resource = nil)
+      fail_if_arguments_nil(authority_uri)
+      @authority_uri = URI.parse(authority_uri.to_s)
+      @resource = resource
+    end
+
+    ##
+    # Creates an AuthenticationContext based on the parameters.
+    #
+    # @return AuthenticationContext
+    def create_context
+      AuthenticationContext.new(@authority_uri.host, @authority_uri.path[1..-1])
+    end
+  end
+end

data/lib/adal/authority.rb

@@ -0,0 +1,165 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require_relative './logging'
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'uri_template'
+
+module ADAL
+  # An authentication and token server with the ability to self validate.
+  class Authority
+    include Logging
+
+    AUTHORIZE_PATH = '/oauth2/authorize'
+    COMMON_TENANT = 'common'
+    DISCOVERY_TEMPLATE = URITemplate.new('https://{host}/common/discovery/' \
+      'instance?authorization_endpoint={endpoint}&api-version=1.0')
+    TENANT_DISCOVERY_ENDPOINT_KEY = 'tenant_discovery_endpoint'
+    TOKEN_PATH = '/oauth2/token'
+    WELL_KNOWN_AUTHORITY_HOSTS = [
+      'login.windows.net',
+      'login.microsoftonline.com',
+      'login.chinacloudapi.cn',
+      'login.cloudgovapi.us'
+    ]
+    WORLD_WIDE_AUTHORITY = 'login.microsoftonline.com'
+
+    attr_reader :host
+    attr_reader :tenant
+
+    ##
+    # Creates a new Authority.
+    #
+    # @param [String] host
+    #   The host name of the authority server.
+    # @param [String] tenant
+    #   The name of the tenant for the Authority to access.
+    # @option [Boolean] validate_authority (false)
+    #   The setting that controls whether the Authority instance will check that
+    #   it matches a set of know authorities or can dynamically retrieve an
+    #   identifying response.
+    def initialize(host = WORLD_WIDE_AUTHORITY,
+                   tenant = COMMON_TENANT,
+                   validate_authority = false)
+      @host = host
+      @tenant = tenant
+      @validated = !validate_authority
+    end
+
+    public
+
+    ##
+    # URI that can be used to acquire authorization codes.
+    #
+    # @optional Hash params
+    #   Query parameters that will added to the endpoint.
+    # @return [URI]
+    def authorize_endpoint(params = nil)
+      params = params.select { |_, v| !v.nil? } if params.respond_to? :select
+      if params.nil? || params.empty?
+        URI::HTTPS.build(host: @host, path: '/' + @tenant + AUTHORIZE_PATH)
+      else
+        URI::HTTPS.build(host: @host,
+                         path: '/' + @tenant + AUTHORIZE_PATH,
+                         query: URI.encode_www_form(params))
+      end
+    end
+
+    ##
+    # URI that can be used to acquire tokens.
+    #
+    # @return [URI]
+    def token_endpoint
+      URI::HTTPS.build(host: @host, path: '/' + @tenant + TOKEN_PATH)
+    end
+
+    ##
+    # Checks if the authority matches a set list of known authorities or if it
+    # can be resolved by the discovery endpoint.
+    #
+    # @return [Boolean]
+    #   True if the Authority was successfully validated.
+    def validate
+      @validated = validated_statically? unless validated?
+      @validated = validated_dynamically? unless validated?
+      @validated
+    end
+
+    # @return [Boolean]
+    def validated?
+      @validated
+    end
+
+    private
+
+    ##
+    # Creates an instance discovery endpoint url for authority that this object
+    # represents.
+    #
+    # @return [URI]
+    def discovery_uri(host = WORLD_WIDE_AUTHORITY)
+      URI(DISCOVERY_TEMPLATE.expand(host: host, endpoint: authorize_endpoint))
+    end
+
+    ##
+    # Performs instance discovery via a network call to well known authorities.
+    #
+    # @return [String]
+    #   The tenant discovery endpoint, if found. Otherwise nil.
+    def validated_dynamically?
+      logger.verbose("Attempting instance discovery at: #{discovery_uri}.")
+      http_response = Net::HTTP.get(discovery_uri)
+      if http_response.nil?
+        logger.error('Dynamic validation received no response from endpoint.')
+        return false
+      end
+      parse_dynamic_validation(JSON.parse(http_response))
+    end
+
+    # @return [Boolean]
+    def validated_statically?
+      logger.verbose('Performing static instance discovery.')
+      found_it = WELL_KNOWN_AUTHORITY_HOSTS.include? @host
+      if found_it
+        logger.verbose('Authority validated via static instance discovery.')
+      end
+      found_it
+    end
+
+    private
+
+    # @param Hash
+    # @return Boolean
+    def parse_dynamic_validation(response)
+      unless response.key? TENANT_DISCOVERY_ENDPOINT_KEY
+        logger.error('Received unexpected response from instance discovery ' \
+                     "endpoint: #{response}. Unable to validate dynamically.")
+        return false
+      end
+      logger.verbose('Authority validated via dynamic instance discovery.')
+      response[TENANT_DISCOVERY_ENDPOINT_KEY]
+    end
+  end
+end

data/lib/adal/cache_driver.rb

@@ -0,0 +1,171 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require_relative './core_ext'
+require_relative './logging'
+require_relative './request_parameters'
+require_relative './util'
+
+using ADAL::CoreExt
+
+module ADAL
+  # Performs logical operations on the TokenCache in the context of one token
+  # request.
+  class CacheDriver
+    include Logging
+    include RequestParameters
+
+    FIELDS = { user_info: USER_INFO,
+               username: USERNAME,
+               resource: RESOURCE }
+
+    ##
+    # Constructs a CacheDriver to interact with a token cache.
+    #
+    # @param String authority
+    #   The URL of the authority endpoint.
+    # @param ClientAssertion|ClientCredential|etc client
+    #   The credentials representing the calling application. We need this
+    #   instead of just the client id so that the tokens can be refreshed if
+    #   necessary.
+    # @param TokenCache token_cache
+    #   The cache implementation to store tokens.
+    # @optional Fixnum expiration_buffer_sec
+    #   The number of seconds to use as a leeway when dealing with cache expiry.
+    def initialize(
+      authority, client, token_cache = NoopCache.new, expiration_buffer_sec = 0)
+      @authority = authority
+      @client = client
+      @expiration_buffer_sec = expiration_buffer_sec
+      @token_cache = token_cache
+    end
+
+    ##
+    # Checks if a TokenResponse is successful and if so adds it to the token
+    # cache for future retrieval.
+    #
+    # @param SuccessResponse token_response
+    #   The successful token response to be cached. If it is not successful, it
+    #   fails silently.
+    def add(token_response)
+      return unless token_response.instance_of? SuccessResponse
+      logger.verbose('Adding successful TokenResponse to cache.')
+      entry = CachedTokenResponse.new(@client, @authority, token_response)
+      update_refresh_tokens(entry) if entry.mrrt?
+      @token_cache.add(entry)
+    end
+
+    ##
+    # Searches the cache for a token matching a specific query of fields.
+    #
+    # @param Hash query
+    #   The fields to match against.
+    # @return TokenResponse
+    def find(query = {})
+      query = query.map { |k, v| [FIELDS[k], v] if FIELDS[k] }.compact.to_h
+      resource = query.delete(RESOURCE)
+      matches = validate(
+        find_all_cached_entries(
+          query.reverse_merge(
+            authority: @authority, client_id: @client.client_id))
+      )
+      resource_specific(matches, resource) || refresh_mrrt(matches, resource)
+    end
+
+    private
+
+    ##
+    # All cache entries that match a query. This matches keys in values against
+    # a hash to method calls on an object.
+    #
+    # @param Hash query
+    #   The fields to be matched and the values to match them to.
+    # @return Array<CachedTokenResponse>
+    def find_all_cached_entries(query)
+      logger.verbose("Searching cache for tokens by keys: #{query.keys}.")
+      @token_cache.find do |entry|
+        query.map do |k, v|
+          (entry.respond_to? k.to_sym) && (v == entry.send(k.to_sym))
+        end.reduce(:&)
+      end
+    end
+
+    ##
+    # Attempts to obtain an access token for a resource with refresh tokens from
+    # a list of MRRTs.
+    #
+    # @param Array[CachedTokenResponse]
+    # @return SuccessResponse|nil
+    def refresh_mrrt(responses, resource)
+      logger.verbose("Attempting to obtain access token for #{resource} by " \
+                     "refreshing 1 of #{responses.count(&:mrrt?)} matching " \
+                     'MRRTs.')
+      responses.each do |response|
+        if response.mrrt?
+          refresh_response = response.refresh(resource)
+          return refresh_response if add(refresh_response)
+        end
+      end
+      nil
+    end
+
+    ##
+    # Searches a list of CachedTokenResponses for one that matches the resource.
+    #
+    # @param Array[CachedTokenResponse]
+    # @return SuccessResponse|nil
+    def resource_specific(responses, resource)
+      logger.verbose("Looking through #{responses.size} matching cache " \
+                     "entries for resource #{resource}.")
+      responses.select { |response| response.resource == resource }
+        .map(&:token_response).first
+    end
+
+    ##
+    # Updates the refresh tokens of all tokens in the cache that match a given
+    # MRRT.
+    #
+    # @param CachedTokenResponse mrrt
+    #   A new MRRT containing a refresh token to update other matching cache
+    #   entries with.
+    def update_refresh_tokens(mrrt)
+      fail ArgumentError, 'Token must contain an MRRT.' unless mrrt.mrrt?
+      @token_cache.find.each do |entry|
+        entry.refresh_token = mrrt.refresh_token if mrrt.can_refresh?(entry)
+      end
+    end
+
+    ##
+    # Checks if an array of current cache entries are still valid, attempts to
+    # refresh those that have expired and discards those that cannot be.
+    #
+    # @param Array[CachedTokenResponse] entries
+    #   The tokens to validate.
+    # @return Array[CachedTokenResponse]
+    def validate(entries)
+      logger.verbose("Validating #{entries.size} possible cache matches.")
+      valid_entries = entries.group_by(&:validate)
+      @token_cache.remove(valid_entries[false] || [])
+      valid_entries[true] || []
+    end
+  end
+end

data/lib/adal/cached_token_response.rb

@@ -0,0 +1,190 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+module ADAL
+  # Proxy object for a token response with metadata.
+  class CachedTokenResponse
+    attr_reader :authority
+    attr_reader :client_id
+    attr_reader :token_response
+
+    ##
+    # Constructs a new CachedTokenResponse.
+    #
+    # @param ClientCredential|ClientAssertion|ClientAssertionCertificate
+    #   The credentials of the calling client application.
+    # @param Authority authority
+    #   The ADAL::Authority object that the response was retrieved from.
+    # @param SuccessResponse token_response
+    #   The token response to be cached.
+    def initialize(client, authority, token_response)
+      unless token_response.instance_of? SuccessResponse
+        fail ArgumentError, 'Only SuccessResponses can be cached.'
+      end
+      @authority = authority
+      if client.respond_to? :client_id
+        @client = client
+        @client_id = client.client_id
+      else
+        @client = ClientCredential.new(client)
+        @client_id = client
+      end
+      @token_response = token_response
+    end
+
+    ##
+    # Converts the fields in this object and its proxied SuccessResponse into
+    # a JSON string.
+    #
+    # @param JSON::Ext::Generator::State
+    #   We don't care about the state, but JSON::unparse requires this.
+    # @return String
+    def to_json(_ = nil)
+      JSON.unparse(authority: [authority.host, authority.tenant],
+                   client_id: client_id,
+                   token_response: token_response)
+    end
+
+    ##
+    # Reconstructs an object from JSON that was serialized with
+    # CachedTokenResponse#to_json.
+    #
+    # @param JSON raw_json
+    # @return CachedTokenResponse
+    def self.from_json(json)
+      json = JSON.parse(json) if json.instance_of? String
+      CachedTokenResponse.new(json['client_id'],
+                              Authority.new(*json['authority']),
+                              SuccessResponse.new(json['token_response']))
+    end
+
+    ##
+    # Determines if self can be used to refresh other.
+    #
+    # @param CachedTokenResponse other
+    # @return Boolean
+    def can_refresh?(other)
+      mrrt? && (authority == other.authority) &&
+        (user_info == other.user_info) && (client_id == other.client_id)
+    end
+
+    ##
+    # If the access token is within the expiration buffer of expiring, an
+    # attempt will be made to retrieve a new token with the refresh token.
+    #
+    # @param Fixnum expiration_buffer_sec
+    #   The number of seconds to use as leeway in determining if the token is
+    #   expired. A positive buffer will refresh the token early while a negative
+    #   buffer will refresh it late. Used to counter clock skew and network
+    #   latency.
+    # @return Boolean
+    #   True if the token is still valid (even if it was refreshed). False if
+    #   the token is expired an unable to be refreshed.
+    def validate(expiration_buffer_sec = 0)
+      return true if (Time.now + expiration_buffer_sec).to_i < expires_on
+      unless refresh_token
+        logger.verbose('Cached token is almost expired but no refresh token ' \
+                       'is available.')
+        return false
+      end
+      logger.verbose('Cached token is almost expired, attempting to refresh ' \
+                     ' with refresh token.')
+      refresh_response = refresh
+      if refresh_response.instance_of? SuccessResponse
+        logger.verbose('Successfully refreshed token in cache.')
+        @token_response = refresh_response
+        true
+      else
+        logger.warn('Failed to refresh token in cache with refresh token.')
+        false
+      end
+    end
+
+    ##
+    # Attempts to refresh the access token for a given resource. Note that you
+    # can call this method with a different resource even if the token is not
+    # an MRRT, but it will fail
+    #
+    # @param String resource
+    #   The resource that the new access token is beign requested for. Defaults
+    #   to using the same resource as the original token.
+    # @return TokenResponse
+    def refresh(new_resource = resource)
+      token_response = TokenRequest
+                       .new(authority, @client)
+                       .get_with_refresh_token(refresh_token, new_resource)
+      if token_response.instance_of? SuccessResponse
+        token_response.parse_id_token(id_token)
+      end
+      token_response
+    end
+
+    ##
+    # Changes the refresh token of the underlying token response.
+    #
+    # @param String token
+    def refresh_token=(token)
+      token_response.instance_variable_set(:@refresh_token, token)
+      logger.verbose("Updated the refresh token for #{token_response}.")
+    end
+
+    ##
+    # Is the token a Multi Resource Refresh Token?
+    #
+    # @return Boolean
+    def mrrt?
+      token_response.refresh_token && token_response.resource
+    end
+
+    ## Since the token cache may be implemented by the user of this library,
+    ## all means of checking equality must be consistent.
+
+    def ==(other)
+      [:authority, :client_id, :token_response].all? do |field|
+        (other.respond_to? field) && (send(field) == other.send(field))
+      end
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      [authority, client_id, token_response].hash
+    end
+
+    private
+
+    # CachedTokenResponse is just a proxy for TokenResponse.
+    def method_missing(method, *args, &block)
+      if token_response.respond_to?(method)
+        token_response.send(method, *args, &block)
+      else
+        super(method)
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      token_response.respond_to?(method, include_private) || super
+    end
+  end
+end