feat: add password method enrollment to My Account API (#1242)

Author: NandanPrabhu

Auth0.xcodeproj/project.pbxproj

@@ -154,6 +154,40 @@ struct Auth0MyAccountAuthenticationMethods: MyAccountAuthenticationMethods {
                        dpop: self.dpop)
     }
 
+    func enrollPassword(userIdentityId: String?,
+                        connection: String?) -> Request<PasswordEnrollmentChallenge, MyAccountError> {
+        var payload: [String: Any] = [:]
+        payload["type"] = "password"
+        payload["identity_user_id"] = userIdentityId
+        payload["connection"] = connection
+        return Request(session: session,
+                       url: url.appending("authentication-methods"),
+                       method: "POST",
+                       handle: myAcccountDecodable,
+                       parameters: payload,
+                       headers: defaultHeaders,
+                       logger: logger,
+                       telemetry: telemetry,
+                       dpop: self.dpop)
+    }
+
+    func confirmPasswordEnrollment(id: String,
+                                   authSession: String,
+                                   newPassword: String) -> Request<AuthenticationMethod, MyAccountError> {
+        var payload: [String: Any] = [:]
+        payload["auth_session"] = authSession
+        payload["new_password"] = newPassword
+        return Request(session: session,
+                       url: url.appending("authentication-methods").appending(id).appending("verify"),
+                       method: "POST",
+                       handle: myAcccountDecodable,
+                       parameters: payload,
+                       headers: defaultHeaders,
+                       logger: logger,
+                       telemetry: telemetry,
+                       dpop: self.dpop)
+    }
+
     func confirmTOTPEnrollment(id: String,
                                authSession: String,
                                otpCode: String) -> Request<AuthenticationMethod, MyAccountError> {

Auth0/MyAccount/AuthenticationMethods/Auth0MyAccountAuthenticationMethods.swift

@@ -106,6 +106,78 @@ public protocol MyAccountAuthenticationMethods: MyAccountClient {
                 challenge: PasskeyEnrollmentChallenge) -> Request<PasskeyAuthenticationMethod, MyAccountError>
 #endif
 
+    /// Requests a challenge for enrolling a password authentication method. This is the first part of the enrollment flow.
+    ///
+    /// You can specify an optional user identity identifier and an optional database connection name. If a
+    /// connection name is not specified, your tenant's default directory will be used.
+    ///
+    /// ## Scopes Required
+    ///
+    /// `create:me:authentication_methods`
+    ///
+    /// ## Usage
+    ///
+    /// ```swift
+    /// Auth0
+    ///     .myAccount(token: apiCredentials.accessToken)
+    ///     .authenticationMethods
+    ///     .enrollPassword()
+    ///     .start { result in
+    ///         switch result {
+    ///         case .success(let enrollmentChallenge):
+    ///             print("Obtained enrollment challenge: \(enrollmentChallenge)")
+    ///         case .failure(let error):
+    ///             print("Failed with: \(error)")
+    ///         }
+    ///     }
+    /// ```
+    ///
+    /// Use the challenge's ``PasswordEnrollmentChallenge/policy`` to guide the user toward a compliant password,
+    /// then call ``confirmPasswordEnrollment(id:authSession:newPassword:)`` with the new password to complete
+    /// the enrollment.
+    ///
+    /// - Parameters:
+    ///   - userIdentityId: Unique identifier of the current user's identity. Needed if the user logged in with a [linked account](https://auth0.com/docs/manage-users/user-accounts/user-account-linking).
+    ///   Pass the bare identifier **without** the identity provider prefix (e.g. use `123456` rather than `auth0|123456`).
+    ///   Defaults to `nil`.
+    ///   - connection:     Name of the database connection where the user is stored. Defaults to `nil`.
+    /// - Returns: A request that will yield a password enrollment challenge, including the password policy to satisfy.
+    func enrollPassword(userIdentityId: String?,
+                        connection: String?) -> Request<PasswordEnrollmentChallenge, MyAccountError>
+
+    /// Confirms the enrollment of a password authentication method by providing a new password that satisfies
+    /// the policy from the enrollment challenge. This is the last part of the enrollment flow.
+    ///
+    /// ## Scopes Required
+    ///
+    /// `create:me:authentication_methods`
+    ///
+    /// ## Usage
+    ///
+    /// ```swift
+    /// Auth0
+    ///     .myAccount(token: apiCredentials.accessToken)
+    ///     .authenticationMethods
+    ///     .confirmPasswordEnrollment(id: id, authSession: authSession, newPassword: newPassword)
+    ///     .start { result in
+    ///         switch result {
+    ///         case .success(let authenticationMethod):
+    ///             print("Enrolled password: \(authenticationMethod)")
+    ///         case .failure(let error):
+    ///             print("Failed with: \(error)")
+    ///         }
+    ///     }
+    /// ```
+    ///
+    /// - Parameters:
+    ///   - id: The ``PasswordEnrollmentChallenge/authenticationId`` returned by ``enrollPassword(userIdentityId:connection:)``. It should be used as it is, without any modifications.
+    ///   - authSession: The unique session identifier for the enrollment as returned by POST /authentication-methods
+    ///   - newPassword: The new password to set, satisfying the policy from the enrollment challenge.
+    /// - Returns: A request that will yield an enrolled password authentication method.
+    func confirmPasswordEnrollment(id: String,
+                                   authSession: String,
+                                   newPassword: String) -> Request<AuthenticationMethod, MyAccountError>
+
     /// Requests a challenge for enrolling a recovery code authentication method. This is the first part of the enrollment flow.
     ///
     /// ## Scopes Required
@@ -558,6 +630,11 @@ public extension MyAccountAuthenticationMethods {
                          preferredAuthenticationMethod: preferredAuthenticationMethod)
     }
 
+    func enrollPassword(userIdentityId: String? = nil,
+                        connection: String? = nil) -> Request<PasswordEnrollmentChallenge, MyAccountError> {
+        self.enrollPassword(userIdentityId: userIdentityId, connection: connection)
+    }
+
     func getAuthenticationMethods(type: AuthenticationMethodType? = nil) -> Request<[AuthenticationMethod], MyAccountError> {
         self.getAuthenticationMethods(type: type)
     }

Auth0/MyAccount/AuthenticationMethods/MyAccountAuthenticationMethods.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+/// A Password enrollment challenge.
+public struct PasswordEnrollmentChallenge {
+
+    /// The unique identifier for the authentication method.
+    public let authenticationId: String
+
+    /// The unique session identifier for the enrollment.
+    public let authenticationSession: String
+
+    /// The password policy the new password must satisfy.
+    public let policy: PasswordPolicy
+}
+
+extension PasswordEnrollmentChallenge: Decodable {
+
+    enum CodingKeys: String, CodingKey {
+        case authenticationSession = "auth_session"
+        case authenticationId = "id"
+        case policy
+    }
+
+    /// `Decodable` initializer.
+    public init(from decoder: Decoder) throws {
+        guard let locationHeader = decoder.userInfo[.locationHeaderKey] as? String,
+              let _ = locationHeader.components(separatedBy: "/").last else {
+            let errorDescription = "Missing authentication method identifier in header 'Location'"
+            let errorContext = DecodingError.Context(codingPath: [],
+                                                     debugDescription: errorDescription)
+            throw DecodingError.dataCorrupted(errorContext)
+        }
+
+        let values = try decoder.container(keyedBy: CodingKeys.self)
+        self.init(authenticationId: try values.decode(String.self, forKey: .authenticationId),
+                  authenticationSession: try values.decode(String.self, forKey: .authenticationSession),
+                  policy: try values.decode(PasswordPolicy.self, forKey: .policy))
+    }
+
+}

Auth0/MyAccount/AuthenticationMethods/PasswordEnrollmentChallenge.swift

@@ -0,0 +1,102 @@
+/// Describes the password policy that a new password must satisfy, as returned by the My Account API
+/// when starting a password enrollment. Use it to build a UI that guides the user toward a compliant
+/// password.
+public struct PasswordPolicy: Decodable, Sendable {
+
+    /// Rules governing the structural complexity of the password (length, character types, etc.).
+    public let complexity: PasswordComplexity
+
+    /// Rules that prevent the password from containing personal information taken from the user profile.
+    public let profileData: PasswordProfileData
+
+    /// Rules that prevent reuse of previously used passwords.
+    public let history: PasswordHistory
+
+    /// Rules that prevent the use of common dictionary words as passwords.
+    public let dictionary: PasswordDictionary
+
+    enum CodingKeys: String, CodingKey {
+        case complexity
+        case profileData = "profile_data"
+        case history
+        case dictionary
+    }
+
+}
+
+/// Structural complexity requirements for a password.
+public struct PasswordComplexity: Decodable, Sendable {
+
+    /// The minimum number of characters the password must contain.
+    public let minLength: Int?
+
+    /// The character classes the password may be required to include.
+    /// Possible values: `uppercase`, `lowercase`, `number`, `special`.
+    public let characterTypes: [String]?
+
+    /// How the ``characterTypes`` requirement is enforced.
+    /// Possible values: `all` (every listed type is required), `three_of_four`.
+    public let characterTypeRule: String?
+
+    /// Whether identical consecutive characters are permitted.
+    /// Possible values: `allow`, `block`.
+    public let identicalCharacters: String?
+
+    /// Whether sequential characters (e.g. `abc`, `123`) are permitted.
+    /// Possible values: `allow`, `block`.
+    public let sequentialCharacters: String?
+
+    /// How a password that exceeds the maximum allowed length is handled.
+    /// Possible values: `truncate`, `error`.
+    public let maxLengthExceeded: String?
+
+    enum CodingKeys: String, CodingKey {
+        case minLength = "min_length"
+        case characterTypes = "character_types"
+        case characterTypeRule = "character_type_rule"
+        case identicalCharacters = "identical_characters"
+        case sequentialCharacters = "sequential_characters"
+        case maxLengthExceeded = "max_length_exceeded"
+    }
+
+}
+
+/// Rules that block the use of personal information from the user profile within a password.
+public struct PasswordProfileData: Decodable, Sendable {
+
+    /// Whether blocking of personal information is enabled.
+    public let active: Bool?
+
+    /// The user profile fields whose values must not appear in the password
+    /// (e.g. `name`, `email`, `user_metadata.first`).
+    public let blockedFields: [String]?
+
+    enum CodingKeys: String, CodingKey {
+        case active
+        case blockedFields = "blocked_fields"
+    }
+
+}
+
+/// Rules that prevent reuse of previously used passwords.
+public struct PasswordHistory: Decodable, Sendable {
+
+    /// Whether password history enforcement is enabled.
+    public let active: Bool?
+
+    /// The number of previous passwords that cannot be reused.
+    public let size: Int?
+
+}
+
+/// Rules that prevent the use of common dictionary words as passwords.
+public struct PasswordDictionary: Decodable, Sendable {
+
+    /// Whether dictionary checking is enabled.
+    public let active: Bool?
+
+    /// The default dictionary used for the check.
+    /// Possible values: `en_10k`, `en_100k`.
+    public let `default`: String?
+
+}

Auth0/MyAccount/AuthenticationMethods/PasswordPolicy.swift

@@ -238,6 +238,30 @@ func haveRecoveryCodeChallenge(id: String, authSession: String, recoveryCode: St
     }
 }
 
+func havePasswordEnrollmentChallenge(id: String,
+                                     authSession: String,
+                                     minLength: Int? = nil,
+                                     characterTypeRule: String? = nil,
+                                     blockedFields: [String]? = nil,
+                                     historySize: Int? = nil,
+                                     dictionaryDefault: String? = nil) -> Nimble.Matcher<MyAccountResult<PasswordEnrollmentChallenge>> {
+    let definition = "havePasswordEnrollmentChallenge with " +
+    "identifier <\(id)>, " +
+    "authSession <\(authSession)>"
+    return Matcher<MyAccountResult<PasswordEnrollmentChallenge>>.define(definition) { expression, failureMessage in
+        return try beSuccessful(expression, failureMessage) { (created: PasswordEnrollmentChallenge) ->
+            Bool in
+            return created.authenticationId == id &&
+            created.authenticationSession == authSession &&
+            created.policy.complexity.minLength == minLength &&
+            created.policy.complexity.characterTypeRule == characterTypeRule &&
+            created.policy.profileData.blockedFields == blockedFields &&
+            created.policy.history.size == historySize &&
+            created.policy.dictionary.default == dictionaryDefault
+        }
+    }
+}
+
 func haveAuthMethodEnrolmentError<T>(type: String,
                                      title: String,
                                      detail: String,