adal 1.0.0

data/lib/adal/jwt_parameters.rb

@@ -0,0 +1,39 @@
+#-------------------------------------------------------------------------------
+# 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
+  # Literals used in JWT header and payload.
+  module JwtParameters
+    ALGORITHM = 'alg'
+    AUDIENCE = 'aud'
+    EXPIRES_ON = 'exp'
+    ISSUER = 'iss'
+    JWT_ID = 'jti'
+    NOT_BEFORE = 'nbf'
+    RS256 = 'RS256'
+    SELF_SIGNED_JWT_LIFETIME = 10
+    SUBJECT = 'sub'
+    THUMBPRINT = 'x5t'
+    TYPE = 'typ'
+    TYPE_JWT = 'JWT'
+  end
+end

data/lib/adal/logger.rb

@@ -0,0 +1,90 @@
+#-------------------------------------------------------------------------------
+# 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 'logger'
+
+module ADAL
+  # Extended version of Ruby's base logger class to support VERBOSE logging.
+  # This is consistent with ADAL logging across platforms.
+  #
+  # The format of a log message is described in the Ruby docs at
+  # http://ruby-doc.org/stdlib-2.2.2/libdoc/logger/rdoc/Logger.html as
+  # SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message.
+  # SeverityID is the first letter of the severity. In the case of ADAL::Logger
+  # that means one of {V, I, W, E, F}. The DateTime object uses the to_s method
+  # of DateTime from stdlib which is ISO-8601. The ProgName will be the
+  # correlation id if one is sent or absent otherwise.
+  class Logger < Logger
+    SEVS = %w(VERBOSE INFO WARN ERROR FATAL)
+    VERBOSE = SEVS.index('VERBOSE')
+
+    ##
+    # Constructs a new Logger.
+    #
+    # @param String|IO logdev
+    #   A filename (String) or IO object (STDOUT, STDERR).
+    # @param String correlation_id
+    #   The UUID of the request context.
+    def initialize(logdev, correlation_id)
+      super(logdev)
+      @correlation_id = correlation_id
+    end
+
+    def format_severity(severity)
+      SEVS[severity] || 'ANY'
+    end
+
+    ##
+    # For some reason, the default logger implementations of #error, #fatal,
+    # etc. pass message = nil and progname = <the message> to #add, which
+    # interprets that as using the progname as the message. Instead, we will
+    # use the message as the message and the progname as the correlation_id.
+    #
+    # This is purely an internal change, the calling mechanism is exactly the
+    # same and it only affects ADAL::Logger, not Logger.
+
+    # These methods are skipped by the SimpleCov, because it is not our
+    # responsibility to test the standard library's logging framework.
+
+    #:nocov:
+    def error(message = nil, &block)
+      add(ERROR, message, @correlation_id, &block)
+    end
+
+    def fatal(message = nil, &block)
+      add(FATAL, message, @correlation_id, &block)
+    end
+
+    def info(message = nil, &block)
+      add(INFO, message, @correlation_id, &block)
+    end
+
+    def verbose(message = nil, &block)
+      add(VERBOSE, message, @correlation_id, &block)
+    end
+
+    def warn(message = nil, &block)
+      add(WARN, message, @correlation_id, &block)
+    end
+    #:nocov:
+  end
+end

data/lib/adal/logging.rb

@@ -0,0 +1,98 @@
+#-------------------------------------------------------------------------------
+# 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 './logger'
+
+require 'securerandom'
+
+module ADAL
+  # Mix-in module for the ADAL logger. To obtain a logger in class methods the
+  # calling class will need to extend this module. To obtain a logger in
+  # instance methods the calling will need to include this Module.
+  module Logging
+    DEFAULT_LOG_LEVEL = Logger::ERROR
+    DEFAULT_LOG_OUTPUT = STDOUT
+
+    @correlation_id = SecureRandom.uuid
+    @log_level = DEFAULT_LOG_LEVEL
+    @log_output = DEFAULT_LOG_OUTPUT
+
+    # According to the style guide, class instance variables are preferable to
+    # class variables.
+    class << self
+      attr_accessor :correlation_id
+      attr_accessor :log_level
+      attr_accessor :log_output
+    end
+
+    ##
+    # Sets the ADAL log level.
+    #
+    # Example usage:
+    #
+    #     ADAL::Logging.log_level = ADAL::Logger::VERBOSE
+    #
+    def self.log_level=(level)
+      unless Logger::SEVS.map.with_index { |_, i| i }.include? level
+        fail ArgumentError, "Invalid log level: #{level}."
+      end
+      @log_level = level
+    end
+
+    ##
+    # Sets the ADAL log output. All future logs generated by ADAL will be sent
+    # to this location. It is not retroactive.
+    #
+    # @param IO|String output
+    #   This can either be STDERR, STDOUT or a String containing a file path.
+    def self.log_output=(output)
+      output = output.to_s unless output.is_a? IO
+      @log_output = output
+    end
+
+    ##
+    # Creates one ADAL logger per calling class/module with a specified output.
+    # This is to be used within ADAL. Clients will have no use for it.
+    #
+    # Examples usage:
+    #
+    #   require_relative './logging'
+    #
+    #   module ADAL
+    #     module SomeModule
+    #       include Logging
+    #
+    #       def something_bad
+    #         logger.error('An error message')
+    #       end
+    #     end
+    #  end
+    #
+    # @param output
+    #   STDERR, STDOUT or the file name as a string.
+    def logger
+      @logger ||= ADAL::Logger.new(Logging.log_output, Logging.correlation_id)
+      @logger.level = Logging.log_level || DEFAULT_LOG_LEVEL
+      @logger
+    end
+  end
+end

data/lib/adal/memory_cache.rb

@@ -0,0 +1,95 @@
+#-------------------------------------------------------------------------------
+# 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'
+
+module ADAL
+  # A simple cache implementation that is not persisted across application runs.
+  class MemoryCache
+    include Logging
+
+    def initialize
+      @entries = []
+    end
+
+    attr_accessor :entries
+
+    ##
+    # Adds an array of objects to the cache.
+    #
+    # @param Array
+    #   The entries to add.
+    # @return Array
+    #   The entries after the addition.
+    def add(entries)
+      entries = Array(entries)  # If entries is an array, this is a no-op.
+      old_size = @entries.size
+      @entries |= entries
+      logger.verbose("Added #{entries.size - old_size} new entries to cache.")
+    end
+
+    ##
+    # By default, matches all entries.
+    #
+    # @param Block
+    #   A matcher on the token list.
+    # @return Array
+    #   The matching tokens.
+    def find(&query)
+      query ||= proc { true }
+      @entries.select(&query)
+    end
+
+    ##
+    # Removes an array of objects from the cache.
+    #
+    # @param Array
+    #   The entries to remove.
+    # @return Array
+    #   The remaining entries.
+    def remove(entries)
+      @entries -= Array(entries)
+    end
+
+    ##
+    # Converts the cache entries into one JSON string.
+    #
+    # @param JSON::Ext::Generator::State
+    # @return String
+    def to_json(_ = nil)
+      JSON.unparse(entries)
+    end
+
+    ##
+    # Reconstructs the cache from JSON that was previously serialized.
+    #
+    # @param JSON json
+    # @return MemoryCache
+    def self.from_json(json)
+      cache = MemoryCache.new
+      cache.entries = JSON.parse(json).map do |e|
+        CachedTokenResponse.from_json(e)
+      end
+      cache
+    end
+  end
+end

data/lib/adal/mex_request.rb

@@ -0,0 +1,52 @@
+#-------------------------------------------------------------------------------
+# 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 './mex_response'
+require_relative './util'
+
+require 'net/http'
+require 'uri'
+
+module ADAL
+  # A request to a Metadata Exchange endpoint of an ADFS server. Used to obtain
+  # the WSTrust endpoint for username and password authentication of federated
+  # users.
+  class MexRequest
+    include Util
+
+    ##
+    # Constructs a MexRequest object for a specific URL endpoint.
+    #
+    # @param String|URI endpoint
+    #   The Metadata Exchange endpoint.
+    def initialize(endpoint)
+      @endpoint = URI.parse(endpoint.to_s)
+    end
+
+    # @return MexResponse
+    def execute
+      request = Net::HTTP::Get.new(@endpoint.path)
+      request.add_field('Content-Type', 'application/soap+xml')
+      MexResponse.parse(http(@endpoint).request(request).body)
+    end
+  end
+end

data/lib/adal/mex_response.rb

@@ -0,0 +1,141 @@
+#-------------------------------------------------------------------------------
+# 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 './xml_namespaces'
+
+require 'nokogiri'
+require 'uri'
+
+module ADAL
+  # Relevant fields from a Mex response.
+  class MexResponse
+    include XmlNamespaces
+
+    class << self
+      include Logging
+    end
+
+    class MexError < StandardError; end
+
+    POLICY_ID_XPATH =
+      '//wsdl:definitions/wsp:Policy[./wsp:ExactlyOne/wsp:All/sp:SignedSuppor' \
+      'tingTokens/wsp:Policy/sp:UsernameToken/wsp:Policy/sp:WssUsernameToken1' \
+      '0]/@u:Id|//wsdl:definitions/wsp:Policy[./wsp:ExactlyOne/wsp:All/ssp:Si' \
+      'gnedEncryptedSupportingTokens/wsp:Policy/ssp:UsernameToken/wsp:Policy/' \
+      'ssp:WssUsernameToken10]/@u:Id'
+    BINDING_XPATH = '//wsdl:definitions/wsdl:binding[./wsp:PolicyReference]'
+    PORT_XPATH = '//wsdl:definitions/wsdl:service/wsdl:port'
+    ADDRESS_XPATH = './soap12:address/@location'
+
+    ##
+    # Parses the XML string response from the Metadata Exchange endpoint into
+    # a MexResponse object.
+    #
+    # @param String response
+    # @return MexResponse
+    def self.parse(response)
+      xml = Nokogiri::XML(response)
+      policy_ids = parse_policy_ids(xml)
+      bindings = parse_bindings(xml, policy_ids)
+      endpoint, binding = parse_endpoint_and_binding(xml, bindings)
+      MexResponse.new(endpoint, binding)
+    end
+
+    # @param Nokogiri::XML::Document xml
+    # @param Array[String] policy_ids
+    # @return Array[String]
+    def self.parse_bindings(xml, policy_ids)
+      matching_bindings = xml.xpath(BINDING_XPATH, NAMESPACES).map do |node|
+        reference_uri = node.xpath('./wsp:PolicyReference/@URI', NAMESPACES)
+        node.xpath('./@name').to_s if policy_ids.include? reference_uri.to_s
+      end.compact
+      fail MexError, 'No matching bindings found.' if matching_bindings.empty?
+      matching_bindings
+    end
+    private_class_method :parse_bindings
+
+    # @param Nokogiri::XML::Document xml
+    # @param Array[String] bindings
+    # @return Array[[String, String]]
+    def self.parse_all_endpoints(xml, bindings)
+      endpoints = xml.xpath(PORT_XPATH, NAMESPACES).map do |node|
+        binding = node.attr('binding').split(':').last
+        if bindings.include? binding
+          [node.xpath(ADDRESS_XPATH, NAMESPACES).to_s, binding]
+        end
+      end.compact
+      endpoints
+    end
+    private_class_method :parse_all_endpoints
+
+    # @param Nokogiri::XML::Document xml
+    # @param Array[String] bindings
+    # @return [String, String]
+    def self.parse_endpoint_and_binding(xml, bindings)
+      endpoints = parse_all_endpoints(xml, bindings)
+      case endpoints.size
+      when 0
+        fail MexError, 'No valid WS-Trust endpoints found.'
+      when 1
+      else
+        logger.info('Multiple WS-Trust endpoints were found in the mex ' \
+                    'response. Only one was used.')
+      end
+      prefer_13(endpoints).first
+    end
+    private_class_method :parse_endpoint_and_binding
+
+    # @param Nokogiri::XML::Document xml
+    # @return Array[String]
+    def self.parse_policy_ids(xml)
+      policy_ids = xml.xpath(POLICY_ID_XPATH, NAMESPACES)
+                   .map { |attr| "\##{attr.value}" }
+      fail MexError, 'No username token policy nodes.' if policy_ids.empty?
+      policy_ids
+    end
+    private_class_method :parse_policy_ids
+
+    # @param Array[String, String] endpoints
+    # @return Array[String, String] endpoints
+    def self.prefer_13(endpoints)
+      only13 = endpoints.select { |_, b| BINDING_TO_ACTION[b] == WSTRUST_13 }
+      only13.empty? ? endpoints : only13
+    end
+    private_class_method :prefer_13
+
+    attr_reader :action
+    attr_reader :wstrust_url
+
+    ##
+    # Constructs a new MexResponse.
+    #
+    # @param String|URI wstrust_url
+    # @param String action
+    def initialize(wstrust_url, binding)
+      @action = BINDING_TO_ACTION[binding]
+      @wstrust_url = URI.parse(wstrust_url.to_s)
+      return if @wstrust_url.instance_of? URI::HTTPS
+      fail ArgumentError, 'Mex is only done over HTTPS.'
+    end
+  end
+end