An authentication can be started by invoking Authenticator.startAuthentication(data:) or its synchronous counterpart
with an instance of AuthenticationInitializationData. The result is an AuthenticateRequest object which contains an
Array/ aList of Role objects from which one must be used for the authentication. If the service is only configured
with one role, that particular role can be set directly.
Otherwise, a role selection SHOULD be prompted to the user to select a supported role. The
Role contains an Array<Array<AuthenticatorType>> / a List<List<AuthenticatorType>> of authenticators
named requestedAuthenticators. These reflect the factors that are used for singing the request later on, e.g. a PIN or
biometric features. The list is two-dimensional from which the first dimension represents acceptable alternatives and
the second the authenticators associated with the respective selection.
The provided alternatives and the required authenticators both depend on the service's configuration. For example, if
the service is configured to either accept authentications using biometrics or PIN the resulting list can be illustrated
as [[biometric, device], [pin, device]] where the device authenticator is required in both alternatives.
The following code snippet shows an example on how an authentication can be started:
internal func startAuthentication(
authenticationInitializationData: AuthenticationInitializationData
) throws {
let authenticator: Authenticator = XignSdk.shared.authenticator
// Submit the `AuthenticationInitializationData` to the XignIn-Manager in order to start
// an authentication.
let request: AuthenticateRequest = try authenticator.startAuthenticationSynchronous(
data: authenticationInitializationData
)
let roles: Array<Role> = request.roles
// Check if more than one `Role` is available. In that case a selection must be made.
if roles.count > 1 {
// Optional: Every `Role` contains a list with optional authenticator constellations with
// which the request must be signed later on. In addition to the role name itself, the alternatives can be
// displayed to the user in order to help making a choice.
let authenticators: Array<Array<AuthenticatorType>>? = roles.first?.requestedAuthenticators
// Let the user select a role.
let selectedRole: Role = YourImplementation.displayRoleSelection(roles)
if request.setSelection(selectedRole) == nil {
// This function returns the set role. It returns `nil` in case `nil` is passed or a role
// that is not part of the given selection `request.roles`. This is only relevant for
// development and can be ignored during production, if implemented correctly.
}
}
// Continue the process by letting the user confirm the requested attributes.
// Note: This is a call to the next documentation example function that illustrates the
// attribute confirmation.
try confirmAuthenticationAttributes(request: request)
}
internal fun startAuthentication(authenticationInitializationData: AuthenticationInitializationData) {
val authenticator: Authenticator = XignSdk.shared.authenticator
// Submit the `AuthenticationInitializationData` to the XignIn-Manager in order to start
// an authentication.
val request: AuthenticateRequest = authenticator.startAuthenticationSynchronous(
authenticationInitializationData
)
val roles: List<Role> = request.roles
// Check if more than one `Role` is available. In that case a selection must be made.
if (roles.size > 1) {
// Optional: Every `Role` contains a list with optional authenticator constellations with
// which the request must be signed later on. In addition to the role name itself, the alternatives can be
// displayed to the user in order to help making a choice.
val authenticators: List<List<AuthenticatorType>>? = roles.firstOrNull()?.requestedAuthenticators
// Let the user select a role.
val selectedRole: Role = YourImplementation.displayRoleSelection(roles)
if (request.setSelection(selectedRole) == null) {
// This function returns the set role. It returns `null` in case `null` is passed or a role
// that is not part of the given selection `request.roles`. This is only relevant for
// development and can be ignored during production, if implemented correctly.
}
}
// Continue the process by letting the user confirm the requested attributes.
// Note: This is a call to the next documentation example function that illustrates the
// attribute confirmation.
confirmAuthenticationAttributes(request = request)
}
Note: Since XignSys SDK version 4.1.0 the functions within the authentication process can throw an error, if the security level of the device/app is not sufficient. The
XignSdkSecurityInsufficientError(XignSdkSecurityInsufficientException) should be handled accordingly. For more information see chapter security check.
After the AuthenticateRequest has been successfully acquired the containing OrganizationInformation
and ServiceInformation should be handled as described in the chapter: