ForgeRock SDKs 3.3

Registration

If the user’s mobile device has never been registered in AM, the device must be registered through WebAuthn Registration node, which is returned as WebAuthnRegistrationCallback by the iOS SDK.

With a WebAuthnRegistrationCallback, you must implement the following protocol methods for the registration process:

public protocol PlatformAuthenticatorRegistrationDelegate {
    func excludeCredentialDescriptorConsent(consentCallback: @escaping WebAuthnUserConsentCallback)
    func createNewCredentialConsent(keyName: String, rpName: String, rpId: String?, userName: String, userDisplayName: String, consentCallback: @escaping WebAuthnUserConsentCallback)
}

The func excludeCredentialDescriptorConsent() method is invoked when the Limit registrations option is enabled in the WebAuthn Registration node. This limitation is per device, and based on the user’s profile as per specification (6.3.2.3). AM returns a list of key descriptor identifiers, and the SDK compares the given list to the registered keys.

When creating new credentials, you can use the following method to notify the user for consent within your login UI:

func excludeCredentialDescriptorConsent(consentCallback: @escaping WebAuthnUserConsentCallback) {
    let alert = UIAlertController(title: "Exclude Credentials", message: nil, preferredStyle: .alert)
    let cancelAction = UIAlertAction(title: "Cancel", style: .cancel, handler: { (_) in
        consentCallback(.reject)
    })
    let allowAction = UIAlertAction(title: "Allow", style: .default) { (_) in
        consentCallback(.allow)
    }
    alert.addAction(cancelAction)
    alert.addAction(allowAction)

    guard let vc = self.viewController else {
        return
    }

    DispatchQueue.main.async {
        viewController.present(alert, animated: true, completion: nil)
    }
}

Users can grant or deny consent with the following options:

  • .reject - In this case, the SDK returns WebAuthnError.notAllowed.

  • .allow - In this case, the SDK returns WebAuthnError.invalidState.

The func createNewCredentialConsent() method is invoked to acquire user consent prior to the SDK generating the key-pair as per specification (6.3.2.6). In addition to the consent, the SDK may prompt for biometric local authentication if the WebAuthn Registration node’s User verification requirement is set to PREFERRED or REQUIRED.

  • .reject - In this case, SDK returns WebAuthnError.notAllowed.

  • .allow - In this case, SDK returns WebAuthnError.invalidState.

In your login UI, you can implement this protocol method to notify the user about the newly created credential, and ask for consent.

func createNewCredentialConsent(keyName: String, rpName: String, rpId: String?, userName: String, userDisplayName: String, consentCallback: @escaping WebAuthnUserConsentCallback) {
    let alert = UIAlertController(title: "Create Credentials", message: "KeyName: \(keyName) | Relying Party Name: \(rpName) | User Name: \(userName)", preferredStyle: .alert)
    let cancelAction = UIAlertAction(title: "Cancel", style: .cancel, handler: { (_) in
        consentCallback(.reject)
    })
    let allowAction = UIAlertAction(title: "Allow", style: .default) { (_) in
        consentCallback(.allow)
    }
    alert.addAction(cancelAction)
    alert.addAction(allowAction)

    guard let vc = self.viewController else {
        return
    }

    DispatchQueue.main.async {
        viewController.present(alert, animated: true, completion: nil)
    }
}

Users can grant or deny the consent with following options:

  • .reject - In this case, the SDK returns WebAuthnError.cancelled.

  • .allow - In this case, the SDK proceeds with the key pair and attestation generation.

Perform registration

As part of registration process, the SDK provides the WebAuthnRegistrationCallback for registering the device as a credential.

if let registrationCallback = callback as? WebAuthnRegistrationCallback {

    registrationCallback.delegate = self

    // Note that the `Node` parameter in `.register()` is an optional parameter.
    // If the node is provided, the SDK automatically sets the error outcome or attestation
    // to the designated HiddenValueCallback.
    registrationCallback.register(node: node) { (attestation) in
        // Registration is successful
        // Submit the Node using Node.next()
    } onError: { (error) in
        // An error occurred during the registration process
        // Submit the Node using Node.next()
    }
}

WebAuthnRegistrationCallback.register() has an optional parameter, Node.

If the current node contains WebAuthnRegistrationCallback and HiddenValueCallback, and this node is provided in the WebAuthnRegistrationCallback.register() method as a parameter, the SDK automatically sets the outcome of the registration process for both success and failure to the designated HiddenValueCallback.

If the node is not provided, the attestation or error outcome must be set manually.

Copyright © 2010-2022 ForgeRock, all rights reserved.