auth0 4.4.0 → 5.1.2

data/lib/auth0/api/v2/tickets.rb

@@ -9,39 +9,86 @@ module Auth0
         # @see https://auth0.com/docs/api/v2#!/Tickets/post_email_verification
         # @param user_id [string] The user_id of for which the ticket is to be created.
         # @param result_url [string] The user will be redirected to this endpoint once the ticket is used.
+        # @param ttl_sec [integer] The ticket's lifetime in seconds starting from the moment of creation.
+        # After expiration, the ticket cannot be used to verify the user's email. If not specified or if
+        # you send 0, the Auth0 default lifetime of five days will be applied
+        # @param identity [hash] Used to verify secondary, federated, and passwordless-email identities.
+        #   * :user_id [string] user_id of the identity.
+        #   * :provider [string] provider of the identity.
+        # @param client_id [string] client id
+        # @param organization_id [string] organization id
         #
         # @return [json] Returns the created ticket url.
-        def post_email_verification(user_id, result_url: nil)
+        def post_email_verification(user_id, result_url: nil, ttl_sec: nil, identity: nil, client_id: nil, organization_id: nil)
           if user_id.to_s.empty?
             raise Auth0::InvalidParameter, 'Must supply a valid user id to post an email verification'
           end
           path = "#{tickets_path}/email-verification"
           request_params = {
             user_id: user_id,
-            result_url: result_url
+            result_url: result_url,
+            ttl_sec: ttl_sec.is_a?(Integer) ? ttl_sec : nil
           }
+          request_params[:client_id] = client_id unless client_id.nil?
+          request_params[:organization_id] = organization_id unless organization_id.nil?
+
+          if identity
+            unless identity.is_a? Hash
+              raise Auth0::InvalidParameter, 'Identity must be a hash to post an email verification'
+            end
+            request_params[:identity] = identity
+          end
+
           post(path, request_params)
         end
 
         # Create a password change ticket
         # @see https://auth0.com/docs/api/v2#!/Tickets/post_password_change
-        # @param new_password [string] The password to be set for the user once the ticket is used.
-        # @param user_id [string] The user_id of for which the ticket is to be created.
         # @param result_url [string] The user will be redirected to this endpoint once the ticket is used.
+        # @param user_id [string] The user_id of for which the ticket is to be created.
         # @param connection_id [string] The connection that provides the identity for which the password is to be
         # changed. If sending this parameter, the email is also required and the user_id is invalid.
         # @param email [string] The user's email.
+        # @param ttl_sec [integer] The ticket's lifetime in seconds starting from the moment of creation. After
+        # expiration, the ticket cannot be used to change the user's password. If not specified or if you send 0,
+        # the Auth0 default lifetime of 5 days will be applied.
+        # @param mark_email_as_verified [boolean] true if email_verified attribute must be set to true once password is
+        # changed, false if email_verified attribute should not be updated
+        # @param includeEmailInRedirect [boolean] Whether or not we include the email as part of the returnUrl
+        # in the reset_email
+        # @param new_password [string] The password to be set for the user once the ticket is used.
+        # @param client_id [string] client id
+        # @param organization_id [string] organization id
         #
         # @return [json] Returns the created ticket url.
-        def post_password_change(new_password: nil, user_id: nil, result_url: nil, connection_id: nil, email: nil)
+        def post_password_change(
+            result_url: nil,
+            user_id: nil,
+            connection_id: nil,
+            email: nil,
+            ttl_sec: nil,
+            mark_email_as_verified: nil,
+            includeEmailInRedirect: nil,
+            new_password: nil,
+            client_id: nil,
+            organization_id: nil
+          )
+
+          booleans = [true, false]
           path = "#{tickets_path}/password-change"
           request_params = {
-            user_id: user_id,
             result_url: result_url,
-            new_password: new_password,
+            user_id: user_id,
             connection_id: connection_id,
-            email: email
+            email: email,
+            ttl_sec: ttl_sec.is_a?(Integer) ? ttl_sec : nil,
+            mark_email_as_verified: booleans.include?(mark_email_as_verified) ? mark_email_as_verified : nil,
+            includeEmailInRedirect: booleans.include?(includeEmailInRedirect) ? includeEmailInRedirect : nil,
+            new_password: new_password
           }
+          request_params[:client_id] = client_id unless client_id.nil?
+          request_params[:organization_id] = organization_id unless organization_id.nil?
+
           post(path, request_params)
         end
 

data/lib/auth0/api/v2/users.rb

@@ -3,20 +3,25 @@ module Auth0
     module V2
       # Methods to use the users endpoints
       module Users
+        include Auth0::Mixins::Validation
+
         attr_reader :users_path
 
-        # Retrieves a list of existing users.
-        # @see https://auth0.com/docs/api/v2#!/Users/get_users
-        # @param per_page [integer] The amount of entries per page. Default: 50. Max value: 100.
-        # @param page [integer]  The page number. Zero based.
-        # @param include_totals [boolean] True if a query summary must be included in the result.
-        # @param sort [string] The field to use for sorting. 1 == ascending and -1 == descending.
-        # @param connection [string] Connection filter.
-        # @param fields [string] A comma separated list of fields to include or exclude from the result.
-        # @param include_fields [boolean] True if the fields specified are to be included in the result, false otherwise.
-        # @param q [string] Query in Lucene query string syntax. Only fields in app_metadata, user_metadata or the
-        # normalized user profile are searchable.
-        #
+        # Retrieves a list of Auth0 users.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/get_users
+        # @param options [hash] The Hash options used to refine the User results.
+        #   * :per_page [integer] The amount of entries per page. Default: 50. Max value: 100.
+        #   * :page [integer] The page number. Zero based.
+        #   * :include_totals [boolean] True if a query summary must be included in the result.
+        #   * :sort [string] The field to use for sorting. 1 == ascending and -1 == descending.
+        #   * :connection [string] Connection to filter results by.
+        #   * :fields [string] A comma separated list of result fields.
+        #   * :include_fields [boolean] True to include :fields, false to exclude.
+        #   * :q [string] Query in Lucene query string syntax.
+        #   * :search_engine [string] User search engine version.
+        #     - Will default to v2 if no value is passed.
+        #     - Default will change to v3 on 11/13/2018
+        #     - See https://auth0.com/docs/users/search/v3#migrate-from-search-engine-v2-to-v3
         # @return [json] Returns the list of existing users.
         def users(options = {})
           request_params = {
@@ -27,9 +32,9 @@ module Auth0
             connection:     options.fetch(:connection, nil),
             fields:         options.fetch(:fields, nil),
             include_fields: options.fetch(:include_fields, nil),
-            q:              options.fetch(:q, nil)
+            q:              options.fetch(:q, nil),
+            search_engine:  options.fetch(:search_engine, nil)
           }
-          request_params[:search_engine] = :v2 if request_params[:q]
           get(users_path, request_params)
         end
         alias get_users users
@@ -38,18 +43,20 @@ module Auth0
         # The attribute connection is always mandatory but depending on the type of connection you are using there
         # could be others too. For instance, Auth0 DB Connections require email and password.
         # @see https://auth0.com/docs/api/v2#!/Users/post_users
-        # @param name [string] The user name.
-        # @param connection [string] The connection the user belongs to.
-        #
+        # @param connection [string]  The connection the user belongs to.
+        # @param options [hash] See https://auth0.com/docs/api/management/v2#!/Users/post_users for available options
         # @return [json] Returns the created user.
-        def create_user(name, options = {})
+        def create_user(connection, options = {})
+          if !connection.is_a?(String) || connection.empty?
+            raise Auth0::MissingParameter, 'Must supply a valid connection'
+          end
           request_params = Hash[options.map { |(k, v)| [k.to_sym, v] }]
-          request_params[:name] = name
+          request_params[:connection] = connection
           post(users_path, request_params)
         end
 
         # Delete all users - USE WITH CAUTION
-        # @see https://auth0.com/docs/api/v2#!/Users/delete_users
+        # @deprecated - 4.8.0, endpoint has been removed
         def delete_users
           delete(users_path)
         end
@@ -93,12 +100,12 @@ module Auth0
         # If your are updating email or phone_number you need to specify the connection and the client_id properties.
         # @see https://auth0.com/docs/api/v2#!/Users/patch_users_by_id
         # @param user_id [string] The user_id of the user to update.
-        # @param body [hash] The optional parametes to update.
+        # @param body [hash] The optional parameters to update.
         #
         # @return [json] Returns the updated user.
         def patch_user(user_id, body)
           raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
-          raise Auth0::InvalidParameter, 'Must supply a valid body' if body.to_s.empty?
+          raise Auth0::InvalidParameter, 'Must supply a valid body' if body.to_s.empty? || body.empty?
           path = "#{users_path}/#{user_id}"
           patch(path, body)
         end
@@ -142,21 +149,23 @@ module Auth0
         # @param secondary_user_id [string] The unique identifier for the user for the identity.
         #
         # @return [json] Returns the array of the unlinked account identities.
-        def unlink_users_account(user_id, provider, secondary_user_id)
+        def unlink_user_account(user_id, provider, secondary_user_id)
           raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
           raise Auth0::MissingUserId, 'Must supply a valid secondary user_id' if secondary_user_id.to_s.empty?
           raise Auth0::InvalidParameter, 'Must supply a valid provider' if provider.to_s.empty?
           path = "#{users_path}/#{user_id}/identities/#{provider}/#{secondary_user_id}"
           delete(path)
         end
+        alias unlink_users_account unlink_user_account
 
         # Retrieve every log event for a specific user id
         # @see https://auth0.com/docs/api/management/v2#!/Users/get_logs_by_user
         # @param user_id [string] The user_id of the logs to retrieve.
-        # @param per_page [integer] The amount of entries per page. Default: 50. Max value: 100.
-        # @param page [integer]  The page number. Zero based.
-        # @param include_totals [boolean] True if a query summary must be included in the result.
-        # @param sort [string] The field to use for sorting. 1 == ascending and -1 == descending.
+        # @param options [hash]
+        #   * :per_page [integer] The amount of entries per page. Default: 50. Max value: 100.
+        #   * :page [integer]  The page number. Zero based.
+        #   * :include_totals [boolean] True if a query summary must be included in the result.
+        #   * :sort [string] The field to use for sorting. 1 == ascending and -1 == descending.
         #
         # @return [json] Returns the list of existing log entries for the given user_id.
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
@@ -164,7 +173,6 @@ module Auth0
           raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
           path = "#{users_path}/#{user_id}/logs"
           request_params = {
-            user_id:        user_id,
             per_page:       options.fetch(:per_page, nil),
             page:           options.fetch(:page, nil),
             include_totals: options.fetch(:include_totals, nil),
@@ -181,12 +189,144 @@ module Auth0
         end
         alias get_user_log_events user_logs
 
+        # Get all roles assigned to a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/get_user_roles
+        #
+        # @param user_id [string] The user_id of the roles to retrieve.
+        # @param options [hash]
+        #   * :per_page [integer] The amount of entries per page. Default: 50. Max value: 100.
+        #   * :page [integer]  The page number. Zero based.
+        #   * :include_totals [boolean] True if a query summary must be included in the result.
+        #   * :sort [string] The field to use for sorting. 1 == ascending and -1 == descending.
+        #
+        # @return [json] Returns roles for the given user_id.
+        def get_user_roles(user_id, options = {})
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          path = "#{users_path}/#{user_id}/roles"
+          request_params = {
+            per_page:       options.fetch(:per_page, nil),
+            page:           options.fetch(:page, nil),
+            include_totals: options.fetch(:include_totals, nil)
+          }
+          get(path, request_params)
+        end
+
+        # Remove one or more roles from a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/delete_user_roles
+        #
+        # @param user_id [string] The user_id of the roles to remove.
+        # @param roles [array] An array of role names to remove.
+        def remove_user_roles(user_id, roles)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          validate_strings_array roles
+          path = "#{users_path}/#{user_id}/roles"
+          delete_with_body path, roles: roles
+        end
+
+        # Add one or more roles to a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/post_user_roles
+        #
+        # @param user_id [string] The user_id of the roles to add.
+        # @param roles [array] An array of role ids to add.
+        def add_user_roles(user_id, roles)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          validate_strings_array roles
+          path = "#{users_path}/#{user_id}/roles"
+          post(path, roles: roles)
+        end
+
+        # Get all Guardian enrollments for a specific user
+        # @see https://auth0.com/docs/api/management/v2#!/Users/get_enrollments
+        #
+        # @param user_id [string] The user_id of the enrollments to get.
+        #
+        # @return [json] Returns Guardian enrollments for the given user_id.
+        def get_enrollments(user_id)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          get "#{users_path}/#{user_id}/enrollments"
+        end
+
+        # Get all permissions for a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/get_permissions
+        #
+        # @param user_id [string] The user_id of the permissions to get.
+        # @param options [hash] A hash of options for getting permissions
+        #   * :per_page [integer] The amount of permissions per page. (optional)
+        #   * :page [integer]  The page number. Zero based. (optional)
+        #   * :include_totals [boolean] True if a query summary must be included in the result. (optional)
+        #
+        # @return [json] Returns permissions for the given user_id.
+        def get_user_permissions(user_id, options = {})
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+
+          request_params = {
+            per_page: options.fetch(:per_page, nil),
+            page: options.fetch(:page, nil),
+            include_totals: options.fetch(:include_totals, nil)
+          }
+
+          get "#{users_path}/#{user_id}/permissions", request_params
+        end
+
+        # Remove one or more permissions from a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/delete_permissions
+        #
+        # @param user_id [string] The user_id of the permissions to remove.
+        # @param permissions [array] An array of Permission structs to remove.
+        def remove_user_permissions(user_id, permissions)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          permissions = validate_permissions_array permissions
+          delete_with_body "#{users_path}/#{user_id}/permissions", permissions: permissions
+        end
+
+        # Add one or more permissions from a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/post_permissions
+        #
+        # @param user_id [string] The user_id of the permissions to add.
+        # @param permissions [array] An array of Permission structs to add.
+        def add_user_permissions(user_id, permissions)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          permissions = validate_permissions_array permissions
+          post "#{users_path}/#{user_id}/permissions", permissions: permissions
+        end
+
+        # Remove the current Guardian recovery code and generates and returns a new one.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/post_recovery_code_regeneration
+        #
+        # @param user_id [string] The user_id of the recovery codes to regenerate.
+        def generate_recovery_code(user_id)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          post "#{users_path}/#{user_id}/recovery-code-regeneration"
+        end
+
+        # Invalidate all remembered browsers for all authentication factors for a specific user.
+        # @see https://auth0.com/docs/api/management/v2#!/Users/post_invalidate_remember_browser
+        #
+        # @param user_id [string] The user_id of the browsers to invalidate.
+        def invalidate_browsers(user_id)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          post "#{users_path}/#{user_id}/multifactor/actions/invalidate-remember-browser"
+        end
+
+
+        # Get a list of organizations for a user.
+        #
+        # @param user_id [string] The user_id of the permissions to get.
+        #
+        # @return [json] Returns organizations for the given user_id.
+        def get_user_organizations(user_id)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+
+          get "#{users_path}/#{user_id}/organizations"
+        end
+
         private
 
         # Users API path
         def users_path
           @users_path ||= '/api/v2/users'
         end
+
       end
     end
   end

data/lib/auth0/api/v2/users_by_email.rb

@@ -8,9 +8,10 @@ module Auth0
         # Retrieves a list of existing users by their email.
         # @see https://auth0.com/docs/api/v2#!/Users/get_users
         # @see https://auth0.com/docs/api/management/v2#!/Users_By_Email/get_users_by_email
-        # @param fields [string] A comma separated list of fields to include or exclude from the result.
-        # @param include_fields [boolean] True if the fields specified are to be included in the result, false otherwise.
         # @param email [string] E-mail to be searched
+        # @param options [hash]
+        #   * :fields [string] A comma separated list of fields to include or exclude from the result.
+        #   * :include_fields [boolean] True if the fields specified are to be included in the result, false otherwise.
         #
         # @return [json] Returns the list of existing users.
         def users_by_email(email, options = {})

data/lib/auth0/api/v2.rb

@@ -1,11 +1,16 @@
+require 'auth0/api/v2/anomaly'
 require 'auth0/api/v2/blacklists'
+require 'auth0/api/v2/branding'
 require 'auth0/api/v2/clients'
 require 'auth0/api/v2/client_grants'
 require 'auth0/api/v2/connections'
 require 'auth0/api/v2/device_credentials'
 require 'auth0/api/v2/emails'
 require 'auth0/api/v2/jobs'
+require 'auth0/api/v2/prompts'
+require 'auth0/api/v2/organizations'
 require 'auth0/api/v2/rules'
+require 'auth0/api/v2/roles'
 require 'auth0/api/v2/stats'
 require 'auth0/api/v2/users'
 require 'auth0/api/v2/users_by_email'
@@ -13,28 +18,37 @@ require 'auth0/api/v2/user_blocks'
 require 'auth0/api/v2/tenants'
 require 'auth0/api/v2/tickets'
 require 'auth0/api/v2/logs'
+require 'auth0/api/v2/log_streams'
 require 'auth0/api/v2/resource_servers'
+require 'auth0/api/v2/guardian'
 
 module Auth0
   module Api
     # https://auth0.com/docs/apiv2
     module V2
+      include Auth0::Api::V2::Anomaly
       include Auth0::Api::V2::Blacklists
+      include Auth0::Api::V2::Branding
       include Auth0::Api::V2::Clients
       include Auth0::Api::V2::ClientGrants
       include Auth0::Api::V2::Connections
       include Auth0::Api::V2::DeviceCredentials
       include Auth0::Api::V2::Emails
+      include Auth0::Api::V2::Guardian
       include Auth0::Api::V2::Jobs
+      include Auth0::Api::V2::Logs
+      include Auth0::Api::V2::LogStreams
+      include Auth0::Api::V2::Prompts
+      include Auth0::Api::V2::Organizations
       include Auth0::Api::V2::Rules
+      include Auth0::Api::V2::Roles
       include Auth0::Api::V2::Stats
       include Auth0::Api::V2::Users
       include Auth0::Api::V2::UsersByEmail
       include Auth0::Api::V2::UserBlocks
+      include Auth0::Api::V2::ResourceServers
       include Auth0::Api::V2::Tenants
       include Auth0::Api::V2::Tickets
-      include Auth0::Api::V2::Logs
-      include Auth0::Api::V2::ResourceServers
     end
   end
 end

data/lib/auth0/client.rb

@@ -1,6 +1,6 @@
 module Auth0
   # Main class
-  # All Api calls are suposed to return hashes, but delete actions return strings.
+  # All Api calls are supposed to return hashes, but delete actions return strings.
   class Client
     include Auth0::Mixins
   end

data/lib/auth0/exception.rb

@@ -2,19 +2,35 @@ module Auth0
   # Default exception in namespace of Auth0
   # if you want to catch all exceptions, then you should use this one.
   # Network exceptions are not included
-  class Exception < StandardError; end
+  class Exception < StandardError
+    attr_reader :error_data
+    def initialize(message,error_data={})
+      super(message)
+      @error_data = error_data
+    end
+  end
+  # Parent for all exceptions that arise out of HTTP error responses.
+  class HTTPError < Auth0::Exception
+    def headers
+      error_data[:headers]
+    end
+
+    def http_code
+      error_data[:code]
+    end
+  end
   # exception for unauthorized requests, if you see it,
   # probably Bearer Token is not set correctly
-  class Unauthorized < Auth0::Exception; end
+  class Unauthorized < Auth0::HTTPError; end
   # exception for not found resource, you query for an
   # unexistent resource, or wrong path
-  class NotFound < Auth0::Exception; end
+  class NotFound < Auth0::HTTPError; end
   # exception for unknown error
-  class Unsupported < Auth0::Exception; end
+  class Unsupported < Auth0::HTTPError; end
   # exception for server error
-  class ServerError < Auth0::Exception; end
+  class ServerError < Auth0::HTTPError; end
   # exception for incorrect request, you've sent wrong params
-  class BadRequest < Auth0::Exception; end
+  class BadRequest < Auth0::HTTPError; end
   # exception for timeouts
   class RequestTimeout < Auth0::Exception; end
   # exception for unset user_id, this might cause removal of
@@ -22,15 +38,24 @@ module Auth0
   class MissingUserId < Auth0::Exception; end
   # exception for unset client_id
   class MissingClientId < Auth0::Exception; end
+  # exception for unset organization_id
+  class MissingOrganizationId < Auth0::Exception; end
   # exception for an unset parameter
   class MissingParameter < Auth0::Exception; end
   # Api v2 access denied
-  class AccessDenied < Auth0::Exception; end
+  class AccessDenied < Auth0::HTTPError; end
   # Invalid parameter passed, e.g. empty where ID is required
   class InvalidParameter < Auth0::Exception; end
-  # Invalid Auth0 credentials either client_id/secret for API v1
-  # or JWT for API v2/
+  # Invalid JWT
   class InvalidCredentials < Auth0::Exception; end
   # Invalid Auth0 API namespace
   class InvalidApiNamespace < Auth0::Exception; end
+  # Auth0 API rate-limiting encountered
+  class RateLimitEncountered < Auth0::HTTPError
+    def reset
+      Time.at(Integer(headers[:x_ratelimit_reset])).utc
+    end
+  end
+
+  class InvalidIdToken < Auth0::Exception; end
 end

data/lib/auth0/mixins/access_token_struct.rb

@@ -0,0 +1,20 @@
+Auth0::AccessToken = Struct.new(
+  :access_token,
+  :expires_in,
+  :refresh_token,
+  :id_token
+) do
+
+  def self.from_response(response)
+    new(
+      response['access_token'],
+      response['expires_in'],
+      response['refresh_token'],
+      response['id_token']
+    )
+  end
+
+  def token
+    access_token
+  end
+end

data/lib/auth0/mixins/api_token_struct.rb

@@ -0,0 +1,10 @@
+Auth0::ApiToken = Struct.new :access_token, :scope, :expires_in do
+
+  def token
+    access_token
+  end
+
+  def scopes
+    scope.split
+  end
+end

data/lib/auth0/mixins/headers.rb

@@ -0,0 +1,35 @@
+require 'json'
+
+module Auth0
+  module Mixins
+    # Module to provide necessary headers for API requests.
+    module Headers
+      def telemetry
+        telemetry_hash = {
+          name: 'ruby-auth0',
+          version: Auth0::VERSION,
+          env: {
+            ruby: RUBY_VERSION
+          }
+        }
+
+        if Gem.loaded_specs['rails'].respond_to? :version
+          telemetry_hash[:env][:rails] = Gem.loaded_specs['rails'].version.to_s
+        end
+
+        telemetry_hash
+      end
+
+      def telemetry_encoded
+        Base64.urlsafe_encode64(JSON.dump(telemetry))
+      end
+
+      def client_headers
+        {
+          'Content-Type' => 'application/json',
+          'Auth0-Client' => telemetry_encoded
+        }
+      end
+    end
+  end
+end