auth0 4.7.0 → 4.12.0

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

@@ -15,20 +15,39 @@ module Auth0
           get(path)
         end
 
+        # Retrieve error details based on the id of the job. Useful to check its status.
+        # @see https://auth0.com/docs/api/management/v2#!/Jobs/get_errors
+        # @param job_id [string] The ID of the job.
+        #
+        # @return [json] Returns the job error details.
+        def get_job_errors(job_id)
+          raise Auth0::InvalidParameter, 'Must specify a job id' if job_id.to_s.empty?
+
+          path = "#{jobs_path}/#{job_id}/errors"
+          get(path)
+        end
+
         # Imports users to a connection from a file using a long running job.
         # Documentation for the file format: https://docs.auth0.com/bulk-import
         # @see https://auth0.com/docs/api/v2#!/Jobs/post_users_imports
         # @param users_file [file] A file containing the users to import.
         # @param connection_id [string] Database connection ID to import to.
-        #
+        # @param options [hash]
+        #   * :upsert [boolean] Update the user if already exists. False by default.
+        #   * :external_id [string] Customer defined id
+        #   * :send_completion_email [boolean] If true,
+        #     send the completion email to all tenant owners when the job is finished. True by default.
         # @return [json] Returns the job status and properties.
-        def import_users(users_file, connection_id)
+        def import_users(users_file, connection_id, options = {})
           raise Auth0::InvalidParameter, 'Must specify a valid file' if users_file.to_s.empty?
           raise Auth0::InvalidParameter, 'Must specify a connection_id' if connection_id.to_s.empty?
 
           request_params = {
             users: users_file,
-            connection_id: connection_id
+            connection_id: connection_id,
+            upsert: options.fetch(:upsert, false),
+            external_id: options.fetch(:external_id, nil),
+            send_completion_email: options.fetch(:send_completion_email, true)
           }
           path = "#{jobs_path}/users-imports"
           post_file(path, request_params)

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

@@ -0,0 +1,172 @@
+module Auth0
+  module Api
+    module V2
+      # Methods to use the Roles endpoints
+      module Roles
+        include Auth0::Mixins::Validation
+
+        # Get all Roles
+        # Required scope: "read:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/get_roles
+        #
+        # @param options [hash] A hash of options for getting Roles
+        #   - per_page: Number of Roles to return.
+        #   - page: Page number to return, zero-based.
+        #   - include_totals: True to include query summary in the result, false or nil otherwise.
+        #   - name_filter: Optional filter on name (case-insensitive).
+        #
+        # @return [json] All Roles matching the query.
+        def get_roles(options = {})
+          request_params = {
+            per_page: options.fetch(:per_page, nil),
+            page: options.fetch(:page, nil),
+            include_totals: options.fetch(:include_totals, nil),
+            name_filter: options.fetch(:name_filter, nil)
+          }
+          get roles_path, request_params
+        end
+        alias roles get_roles
+
+        # Get a single Role by ID.
+        # Required scope: "read:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/get_roles_by_id
+        #
+        # @param role_id [string] Role ID to get.
+        #
+        # @return [json] Role data.
+        def get_role(role_id)
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?
+
+          get "#{roles_path}/#{role_id}"
+        end
+        alias role get_role
+
+        # Create a new Role.
+        # Required scope: "create:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/post_roles
+        #
+        # @param role_name [string] Role name for the new Role.
+        # @param data [hash] Additional Role data.
+        def create_role(role_name, data = {})
+          raise Auth0::MissingParameter, 'Must supply a valid role_name' if role_name.to_s.empty?
+
+          data[:name] = role_name
+          post roles_path.to_s, data
+        end
+
+        # Update a Role by ID.
+        # Required scope: "update:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/patch_roles_by_id
+        #
+        # @param role_id [string] Role ID to update.
+        # @param data [string] Role data to update.
+        def update_role(role_id, data = {})
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?
+
+          patch "#{roles_path}/#{role_id}", data
+        end
+
+        # Delete a single Role by ID.
+        # Required scope: "delete:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/delete_roles_by_id
+        #
+        # @param role_id [string] Role ID to delete.
+        def delete_role(role_id)
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?
+
+          delete "#{roles_path}/#{role_id}"
+        end
+
+        # Get Users assigned to a specific Role.
+        # Required scopes:
+        #   - "read:roles"
+        #   - "read:users"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/get_role_user
+        #
+        # @param role_id [string] Role ID to which the Users belong to.
+        # @param options [hash] A hash of options for getting Roles
+        #   - per_page: Number of Roles to return.
+        #   - page: Page number to return, zero-based.
+        #   - include_totals: True to include query summary in the result, false or nil otherwise.
+        def get_role_users(role_id, options = {})
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_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 "#{roles_path}/#{role_id}/users", request_params
+        end
+
+        # Add one or more Users to a Role.
+        # Required scopes: "update:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/post_role_users
+        #
+        # @param role_id [string] Role ID to add Users.
+        # @param users [array] Array of string User IDs to add to the Role.
+        def add_role_users(role_id, users = [])
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?
+
+          validate_strings_array(users)
+          post "#{roles_path}/#{role_id}/users", users: users
+        end
+
+        # Get the permissions associated to a Role.
+        # Required scope: "read:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/get_role_permission
+        #
+        # @param role_id [string] Role ID to add permissions.
+        # @param options [hash] A hash of options for getting permissions
+        #   - per_page: Number or permissions to return.
+        #   - page: Page number to return, zero-based
+        #   - include_totals: True to include query summary in the result, false or nil otherwise.
+        #
+        # @return [json] All permissions matching the query.
+        def get_role_permissions(role_id, options = {})
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_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 "#{roles_path}/#{role_id}/permissions", request_params
+        end
+
+        # Associate permissions with a Role.
+        # Required scope: "update:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/post_role_permission_assignment
+        #
+        # @param role_id [string] Role ID to add permissions.
+        # @param permissions [array] Array of Permission structs to add.
+        def add_role_permissions(role_id, permissions)
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?
+
+          permissions = validate_permissions_array(permissions)
+          post "#{roles_path}/#{role_id}/permissions", permissions: permissions
+        end
+
+        # Remove permissions from a Role.
+        # Required scope: "update:roles"
+        # @see https://auth0.com/docs/api/management/v2#!/Roles/delete_role_permission_assignment
+        #
+        # @param role_id [string] Role ID to remove permissions.
+        # @param permissions [array] Array of Permission structs to remove.
+        def remove_role_permissions(role_id, permissions)
+          raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?
+
+          permissions = validate_permissions_array(permissions)
+          delete_with_body("#{roles_path}/#{role_id}/permissions", permissions: permissions)
+        end
+
+        private
+
+        # Roles base API path
+        def roles_path
+          @roles_path ||= '/api/v2/roles'
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,8 @@ module Auth0
     module V2
       # Methods to use the users endpoints
       module Users
+        include Auth0::Mixins::Validation
+
         attr_reader :users_path
 
         # Retrieves a list of Auth0 users.
@@ -52,7 +54,7 @@ module Auth0
         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
@@ -96,7 +98,7 @@ 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)
@@ -145,13 +147,14 @@ 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
@@ -168,7 +171,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),
@@ -185,12 +187,121 @@ 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.
+        #
+        # @return [json] Returns permissions for the given user_id.
+        def get_user_permissions(user_id)
+          raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
+          get "#{users_path}/#{user_id}/permissions"
+        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-generation"
+        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
+
         private
 
         # Users API path
         def users_path
           @users_path ||= '/api/v2/users'
         end
+
       end
     end
   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
@@ -25,7 +41,7 @@ module Auth0
   # 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
@@ -33,4 +49,16 @@ module Auth0
   class InvalidCredentials < Auth0::Exception; end
   # Invalid Auth0 API namespace
   class InvalidApiNamespace < Auth0::Exception; end
+  # Auth0 API rate-limiting encountered
+  # TODO: When making API-breaking changes, make this a subclass
+  # of Auth0::HTTPError directly rather than Auth0::Unsupported.
+  # It's currently under Unsupported to avoid breaking compatibility
+  # with prior gem versions that treated 429 errors as unknown errors.
+  class RateLimitEncountered < Auth0::Unsupported
+    def reset
+      Time.at(headers['X-RateLimit-Reset']).utc
+    end
+  end
+
+  class InvalidIdToken < Auth0::Exception; end
 end