adal 1.0.0

data/lib/adal/token_response.rb

@@ -0,0 +1,144 @@
+#-------------------------------------------------------------------------------
+# 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 'digest'
+require 'json'
+require 'jwt'
+require 'securerandom'
+
+module ADAL
+  # The return type of all of the instance methods that return tokens.
+  class TokenResponse
+    extend Logging
+
+    ##
+    # Constructs a TokenResponse from a raw hash. It will return either a
+    # SuccessResponse or an ErrorResponse depending on the fields of the hash.
+    #
+    # @param Hash raw_response
+    #   The body of the HTTP response expressed as a raw hash.
+    # @return TokenResponse
+    def self.parse(raw_response)
+      logger.verbose('Attempting to create a TokenResponse from raw response.')
+      if raw_response.nil?
+        ErrorResponse.new
+      elsif raw_response['error']
+        ErrorResponse.new(JSON.parse(raw_response))
+      else
+        SuccessResponse.new(JSON.parse(raw_response))
+      end
+    end
+
+    public
+
+    ##
+    # Shorthand for checking if a token response is successful or failed.
+    #
+    # @return Boolean
+    def error?
+      self.respond_to? :error
+    end
+  end
+
+  # A token response that contains an access token. All fields are read only
+  # and may be nil. Some fields are only populated in certain flows.
+  class SuccessResponse < TokenResponse
+    include Logging
+
+    # These fields may or may not be included in the response from the token
+    # endpoint.
+    OAUTH_FIELDS = [:access_token, :expires_in, :expires_on, :id_token,
+                    :not_before, :refresh_token, :resource, :scope, :token_type]
+    OAUTH_FIELDS.each { |field| attr_reader field }
+    attr_reader :user_info
+    attr_reader :fields
+
+    ##
+    # Constructs a SuccessResponse from a collection of fields returned from a
+    # token endpoint.
+    #
+    # @param Hash
+    def initialize(fields = {})
+      @fields = fields
+      fields.each { |k, v| instance_variable_set("@#{k}", v) }
+      parse_id_token(id_token)
+      @expires_on = @expires_in.to_i + Time.now.to_i
+      logger.info('Parsed a SuccessResponse with access token digest ' \
+                  "#{Digest::SHA256.hexdigest @access_token.to_s} and " \
+                  'refresh token digest ' \
+                  "#{Digest::SHA256.hexdigest @refresh_token.to_s}.")
+    end
+
+    ##
+    # Converts the fields that were used to create this token response into
+    # a JSON string. This is helpful for storing then in a database.
+    #
+    # @param JSON::Ext::Generator::State
+    #   We don't care about this, because the JSON representation of this
+    #   object does not depend on the fields before it.
+    # @return String
+    def to_json(_ = nil)
+      JSON.unparse(fields)
+    end
+
+    ##
+    # Parses the raw id token into an ADAL::UserInformation.
+    # If the id token is missing, an ADAL::UserInformation will still be
+    # generated, it just won't contain any displayable information.
+    #
+    # @param String id_token
+    #   The id token to parse
+    #   Adds an id token to the token response if one is not present
+    def parse_id_token(id_token)
+      if id_token.nil?
+        logger.warn('No id token found.')
+        @user_info ||= ADAL::UserInformation.new(unique_id: SecureRandom.uuid)
+        return
+      end
+      logger.verbose('Attempting to decode id token in token response.')
+      claims = JWT.decode(id_token.to_s, nil, false).first
+      @id_token = id_token
+      @user_info = ADAL::UserInformation.new(claims)
+    end
+  end
+
+  # A token response that contains an error code.
+  class ErrorResponse < TokenResponse
+    include Logging
+
+    OAUTH_FIELDS = [:error, :error_description, :error_codes, :timestamp,
+                    :trace_id, :correlation_id, :submit_url, :context]
+    OAUTH_FIELDS.each { |field| attr_reader field }
+
+    # Constructs a Error from a collection of fields returned from a
+    # token endpoint.
+    #
+    # @param Hash
+    def initialize(fields = {})
+      fields.each { |k, v| instance_variable_set("@#{k}", v) }
+      logger.error("Parsed an ErrorResponse with error: #{@error} and error " \
+                   "description: #{@error_description}.")
+    end
+  end
+end

data/lib/adal/user_assertion.rb

@@ -0,0 +1,57 @@
+#-------------------------------------------------------------------------------
+# 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 './token_request'
+
+module ADAL
+  # An assertion and its representation type, stored as a JWT for
+  # the on-behalf-of flow.
+  class UserAssertion
+    attr_reader :assertion
+    attr_reader :assertion_type
+
+    ##
+    # Creates a new UserAssertion.
+    #
+    # @param String assertion
+    #   An OAuth assertion representing the user.
+    # @optional AssertionType assertion_type
+    #   The type of the assertion being made. Currently only JWT_BEARER is
+    #   supported.
+    def initialize(
+      assertion, assertion_type = ADAL::TokenRequest::GrantType::JWT_BEARER)
+      @assertion = assertion
+      @assertion_type = assertion_type
+    end
+
+    ##
+    # The relevant OAuth access token request parameters for this object.
+    #
+    # @return Hash
+    def request_params
+      { grant_type: assertion_type,
+        assertion: assertion,
+        requested_token_use: :on_behalf_of,
+        scope: :openid }
+    end
+  end
+end

data/lib/adal/user_credential.rb

@@ -0,0 +1,152 @@
+#-------------------------------------------------------------------------------
+# 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 './authority'
+require_relative './logger'
+require_relative './mex_request'
+require_relative './token_request'
+require_relative './wstrust_request'
+
+require 'base64'
+require 'json'
+require 'net/http'
+require 'uri'
+
+module ADAL
+  # A convenience class for username and password credentials.
+  class UserCredential
+    include Logging
+
+    # Federation response type from the userrealm endpoint.
+    module AccountType
+      FEDERATED = 'Federated'
+      MANAGED = 'Managed'
+      UNKNOWN = 'Unknown'
+    end
+
+    # ADAL only supports flows for managed and federated users.
+    class UnsupportedAccountTypeError < StandardError
+      def initialize(account_type)
+        super("Unsupported account type for authentication: #{account_type}.")
+      end
+    end
+
+    attr_reader :username
+    attr_reader :password
+
+    ##
+    # Constructs a new UserCredential.
+    #
+    # @param String username
+    # @param String password
+    # @optional String authority_host
+    #   The host name of the authority to verify the user against.
+    def initialize(
+      username, password, authority_host = Authority::WORLD_WIDE_AUTHORITY)
+      @username = username
+      @password = password
+      @authority_host = authority_host
+      @discovery_path = "/common/userrealm/#{URI.escape @username}"
+    end
+
+    ##
+    # Determines the account type based on a Home Realm Discovery request.
+    #
+    # @return UserCredential::AccountType
+    def account_type
+      realm_discovery_response['account_type']
+    end
+
+    ##
+    # The OAuth parameters that respresent this UserCredential.
+    #
+    # @return Hash
+    def request_params
+      case account_type
+      when AccountType::MANAGED
+        managed_request_params
+      when AccountType::FEDERATED
+        federated_request_params
+      else
+        fail UnsupportedAccountTypeError, account_type
+      end
+    end
+
+    # :nocov:
+    def to_s
+      "UserCredential[Username: #{@username}, AccountType: #{account_type}]"
+    end
+    # :nocov:
+
+    private
+
+    # Memoized response from the discovery endpoint. Since a UserCredential is
+    # read only, this should only ever need to be called once.
+    # @return Hash
+    def realm_discovery_response
+      @realm_discovery_response ||=
+        JSON.parse(Net::HTTP.get(realm_discovery_uri))
+    end
+
+    # @return URI
+    def realm_discovery_uri
+      URI::HTTPS.build(
+        host: @authority_host,
+        path: @discovery_path,
+        query: URI.encode_www_form('api-version' => '1.0'))
+    end
+
+    # @return Hash
+    def federated_request_params
+      logger.verbose("Getting OAuth parameters for Federated #{@username}.")
+      wstrust_response = wstrust_request.execute(@username, @password)
+      { assertion: Base64.encode64(wstrust_response.token).strip,
+        grant_type: wstrust_response.grant_type,
+        scope: :openid }
+    end
+
+    # @return URI
+    def federation_metadata_url
+      URI.parse(realm_discovery_response['federation_metadata_url'])
+    end
+
+    # @return Hash
+    def managed_request_params
+      logger.verbose("Getting OAuth parameters for Managed #{@username}.")
+      { username: @username,
+        password: @password,
+        grant_type: TokenRequest::GrantType::PASSWORD,
+        scope: :openid }
+    end
+
+    # @return MexResponse
+    def mex_response
+      @mex_response ||= MexRequest.new(federation_metadata_url).execute
+    end
+
+    # @return WSTrustRequest
+    def wstrust_request
+      @wstrust_request ||=
+        WSTrustRequest.new(mex_response.wstrust_url, mex_response.action)
+    end
+  end
+end

data/lib/adal/user_identifier.rb

@@ -0,0 +1,83 @@
+#-------------------------------------------------------------------------------
+# 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
+  # Identifier for users in the cache.
+  #
+  # Ideally, the application will first use a different OAuth flow, such as the
+  # Authorization Code flow, to acquire an ADAL::SuccessResponse. Then, it can
+  # create ADAL::UserIdentifier to query the cache which will refresh tokens as
+  # necessary.
+  class UserIdentifier
+    attr_reader :id
+    attr_reader :type
+
+    # Displayable IDs are human readable (eg email addresses) while Unique Ids
+    # are generally random UUIDs.
+    module Type
+      UNIQUE_ID = :UNIQUE_ID
+      DISPLAYABLE_ID = :DISPLAYABLE_ID
+    end
+    include Type
+
+    ##
+    # Creates a UserIdentifier with a specific type. Used for cache lookups.
+    # Matches .NET ADAL implementation.
+    #
+    # @param String id
+    # @param UserIdentifier::Type
+    # @return ADAL::UserIdentifier
+    def initialize(id, type)
+      unless [UNIQUE_ID, DISPLAYABLE_ID].include? type
+        fail ArgumentError, 'type must be an ADAL::UserIdentifier::Type.'
+      end
+      @id = id
+      @type = type
+    end
+
+    ##
+    # These parameters should only be used for cache lookup. This is enforced
+    # by ADAL::TokenRequest.
+    #
+    # @return Hash
+    def request_params
+      { user_info: self }
+    end
+
+    ##
+    # Overrides comparison operator for cache lookups
+    #
+    # @param UserIdentifier other
+    # @return Boolean
+    def ==(other)
+      case other
+      when UserIdentifier
+        self.equal? other
+      when UserInformation
+        (type == UNIQUE_ID && id == other.unique_id) ||
+          (type == DISPLAYABLE_ID && id == other.displayable_id)
+      when String
+        @id == other
+      end
+    end
+  end
+end

data/lib/adal/user_information.rb

@@ -0,0 +1,49 @@
+#-------------------------------------------------------------------------------
+# 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
+  # Basically just a holder for the id token.
+  class UserInformation
+    ID_TOKEN_FIELDS = [:aud, :iss, :iat, :nbf, :exp, :ver, :tid, :oid, :upn,
+                       :sub, :given_name, :family_name, :name, :amr,
+                       :unique_name, :nonce, :email]
+    ID_TOKEN_FIELDS.each { |field| attr_reader field }
+    attr_reader :unique_id
+    attr_reader :displayable_id
+
+    ##
+    # Constructs a new UserInformation.
+    #
+    # @param Hash claims
+    #   Claims from an id token. The exact claims will vary, so whatever is not
+    #   found in the claims will be nil.
+    def initialize(claims)
+      claims.each { |k, v| instance_variable_set("@#{k}", v) }
+      @unique_id = oid || sub || unique_id
+      @displayable_id = upn || email
+    end
+
+    def ==(other)
+      unique_id == other.unique_id && displayable_id == other.displayable_id
+    end
+  end
+end