NMAAuthCloudApiRegistration

@objc
public protocol NMAAuthCloudApiRegistration : NMAHttpOperation

The object that can be used to trigger a registration operation from the response of the Cloud HTTP API to the enroll (https://$instance.mauth.nevis.cloud/api/v1/users/enroll) endpoint.

Usage example:

@interface NMAAuthenticatorSelectorImpl : NSObject <NMAAuthenticatorSelector>

@end

@implementation NMAAuthenticatorSelectorImpl

- (void)selectAuthenticatorWithContext:(id<NMAAuthenticatorSelectionContext> _Nonnull)context handler:(id<NMAAuthenticatorSelectionHandler> _Nonnull)handler {
    [handler aaid:aaid];
}

@end

@interface NMABiometricUserVerifierImpl : NSObject <NMABiometricUserVerifier>

@end

@implementation NMABiometricUserVerifierImpl

- (void)verifyBiometricWithContext:(id<NMABiometricUserVerificationContext> _Nonnull)context handler:(id<NMABiometricUserVerificationHandler> _Nonnull)handler {
    [handler verify];
}

@end

@interface NMADevicePasscodeUserVerifierImpl : NSObject <NMADevicePasscodeUserVerifier>

@end

@implementation NMADevicePasscodeUserVerifierImpl

- (void)verifyDevicePasscodeWithContext:(id<NMADevicePasscodeUserVerificationContext> _Nonnull)context handler:(id<NMADevicePasscodeUserVerificationHandler> _Nonnull)handler {
    [handler verify];
}

@end

id<NMAAuthCloudApiRegistration> authCloudApiRegistration = [[client operations] authCloudApiRegistration];

[authCloudApiRegistration deviceInformation:[[NMADeviceInformation alloc] initWithName:@"<Device name>" fcmRegistrationToken:@"<FCM token>"]];
[authCloudApiRegistration enrollResponse:@"<Cloud API - enroll response>"];
[authCloudApiRegistration authenticatorSelector:[[NMAAuthenticatorSelectorImpl alloc] init]];
[authCloudApiRegistration biometricUserVerifier:[[NMABiometricUserVerifierImpl alloc] init]];
[authCloudApiRegistration devicePasscodeUserVerifier:[[NMADevicePasscodeUserVerifierImpl alloc] init]];
[authCloudApiRegistration onSuccess:^{...}];
[authCloudApiRegistration onError:^(NMAAuthCloudApiError * _Nonnull error) {...}];
[authCloudApiRegistration execute];

The biometric and device Passcode authenticators are enrolled at the OS level. That is why, if one of them must be registered, the user must authenticate through NMABiometricUserVerifier or NMADevicePasscodeUserVerifier. In the case of the PIN, the PIN is enrolled during registration, so no verification is needed.


                    
                    
                    enrollResponse(_:)

Specifies the response of the Cloud HTTP API to the enroll (https://$instance.mauth.nevis.cloud/api/v1/users/enroll) endpoint. The JSON has the following format:

{
    "userId": "<userID>",
    "username": "<username>",
    "status": "new",
    "createdAt": "<timestamp>",
    "updatedAt": "<timestamp>",
    "authenticators": [],
    "enrollment": {
        "transactionId": "<transactionID>",
        "statusToken": "<statusToken>",
        "qrCode": {
            "type": "<image mime type>",
            "size": <size>,
            "dataUri": "data:<image mime type>;base64,<image>"
        },
        "appLinkUri": "https://{instance}.mauth.nevis.cloud/open?dispatchTokenResponse=<dispatchTokenResponse>"
    }
}

Important

You must provide either the whole response through this method, or the URL with the appLinkUri(_:) method. Only one of them can be provided.

Declaration

Swift

@discardableResult
func enrollResponse(_ response: String) -> NMAAuthCloudApiRegistration

Parameters


                                response

the JSON response of the enroll endpoint.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    appLinkUri(_:)

Specifies the value of the appLinkUri attribute in the enroll response sent by the server. The URL has the following format https://{instance}-app.mauth.nevis.cloud/open?dispatchTokenResponse=<dispatchTokenResponse>.

Important

You must provide either the appLinkUri through the method, or the whole response with the enrollResponse(_:) method. Only one of them can be provided.

Declaration

Swift

@discardableResult
func appLinkUri(_ appLinkUri: String) -> NMAAuthCloudApiRegistration

Parameters


                                appLinkUri

the URL contained in the appLinkUri attribute value.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    deviceInformation(_:)

Specifies the device information to be used. The NMADeviceInformation is required only if you require support for encrypted out-of-band payloads or push notifications. If an NMADeviceInformation was already provided in an existing registration, the provided value will be ignored.

Declaration

Swift

@discardableResult
func deviceInformation(_ deviceInformation: NMADeviceInformation) -> NMAAuthCloudApiRegistration

Parameters


                                deviceInformation

the device information.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    allowDevicePasscodeAsFallback(_:)

Specifies whether the OS device passcode can be used as fallback during biometric authentication. If not specified, the device passcode cannot be used as fallback.

Declaration

Swift

@discardableResult
func allowDevicePasscodeAsFallback(_ allowDevicePasscodeAsFallback: Bool) -> NMAAuthCloudApiRegistration

Parameters


                                allowDevicePasscodeAsFallback

indicates whether the device passcode can be used as fallback.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    invalidateOnNewOsBiometrics(_:)

Specifies whether the authenticator must be invalidated if the user adds new biometric credentials in the OS settings. If the authenticator has been invalidated, and you try to authenticate with it, an error with code FidoErrorCode.keyDisappearedPermanently will be returned by the authentication operation.

This setting only applies to faceRecognition (NMAAuthenticatorAaid.faceRecognition) and fingerprint (NMAAuthenticatorAaid.fingerprint) authenticators. By setting this parameter to true, you increase the security but there is a loss of convenience: adding a new OS biometric credential does not imply necessarily that there is a security risk, but if the end-user does it, a new registration will be required, because an invalidated authenticator cannot be recovered. If not specified, the authenticator will be invalidated when the user adds a new biometric credential in the OS settings.

Declaration

Swift

@discardableResult
func invalidateOnNewOsBiometrics(_ invalidateOnNewOsBiometrics: Bool) -> NMAAuthCloudApiRegistration

Parameters


                                invalidateOnNewOsBiometrics

indicates whether an addition of biometric credentials in the OS should invalidate this authenticator (if the authenticator is Face ID or Touch ID)

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    authenticatorSelector(_:)

Specifies the object that will take care of the selection of the authenticator to be used.

Important

Providing the authenticator selector is required.

Declaration

Swift

@discardableResult
func authenticatorSelector(_ authenticatorSelector: NMAAuthenticatorSelector) -> NMAAuthCloudApiRegistration

Parameters


                                authenticatorSelector

the NMAAuthenticatorSelector.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    biometricUserVerifier(_:)

Specifies the object that will take care of the biometric user verification. It must be provided only if a biometric authenticator must be registered.

Important

Providing at least one of the NMABiometricUserVerifier, NMADevicePasscodeUserVerifier or NMAPinEnroller is required.

Declaration

Swift

@discardableResult
func biometricUserVerifier(_ biometricUserVerifier: NMABiometricUserVerifier) -> NMAAuthCloudApiRegistration

Parameters


                                biometricUserVerifier

the NMABiometricUserVerifier.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    devicePasscodeUserVerifier(_:)

Specifies the object that will take care of the device passcode user verification.

Important

Providing at least one of the NMABiometricUserVerifier, NMADevicePasscodeUserVerifier or NMAPinEnroller is required.

Declaration

Swift

@discardableResult
func devicePasscodeUserVerifier(_ devicePasscodeUserVerifier: NMADevicePasscodeUserVerifier) -> NMAAuthCloudApiRegistration

Parameters


                                devicePasscodeUserVerifier

the DevicePasscodeUserVerifier.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    pinEnroller(_:)

Specifies the object that will take care of enrolling the PIN of the authenticator. It must be provided only if a PIN authenticator must be registered.

If not provided, and in the NMAAuthenticatorSelector the PIN authenticator is provided, completion handler of onError(_:) will be invoked with an userNotEnrolled.

Important

Providing at least one of the NMABiometricUserVerifier, NMADevicePasscodeUserVerifier or NMAPinEnroller is required.

Declaration

Swift

@discardableResult
func pinEnroller(_ pinEnroller: NMAPinEnroller) -> NMAAuthCloudApiRegistration

Parameters


                                pinEnroller

the NMAPinEnroller

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    onSuccess(_:)

Specifies the block to execute if the registration was successful.

Important

Providing the onSuccess block is required.

Declaration

Swift

@discardableResult
func onSuccess(_ onSuccess: @escaping () -> ()) -> NMAAuthCloudApiRegistration

Parameters


                                onSuccess

the block to execute on successful registration.

Return Value

the NMAAuthCloudApiRegistration builder.


                    
                    
                    onError(_:)

Specifies the block to execute if the registration failed.

Important

Providing the onError block is required.

Declaration

Swift

@discardableResult
func onError(_ onError: @escaping (NMAAuthCloudApiError) -> ()) -> NMAAuthCloudApiRegistration

Parameters


                                onError

the block to execute on failed registration, receives an NMAAuthCloudApiError.

Return Value

the NMAAuthCloudApiRegistration builder.