AuthenticationService

public final class AuthenticationService : WebcomService

extension AuthenticationService: WebcomCombinable

An object representing the Authentication service of a WebcomApplication instance. This service makes it possible to reliably identify users of applications, in order to finely control their access to data. It additionally retrieves user identity details when they sign in, which can be used by applications to customize their behavior.

To get an object of this type, use the WebcomApplication.authenticationService property of a WebcomApplication instance. There is only one instance of this class for each WebcomApplication instance.

Three kinds of authentication methods are available:

AuthenticationMethodGuest, which gives a temporary (virtual) user account,
AuthenticationMethodInternal, which uses identities directly managed by the back-end, using user e-mail address or user phone number,
delegated authentication methods, based on a third-party identity provider, which includes:
- AuthenticationMethodOrangeMobileNetwork, which relies on the Orange mobile data network and a physical SIM card or an eSIM of the device,
- AuthenticationMethodOAuth2, based on the OAuth 2.0 standard,
- AuthenticationMethodCustom, for applications using an ad hoc authentication mechanism.

Types

Context
A value representing the context for an authentication process.
See more
Declaration
Swift

public enum Context : Equatable
AuthenticationProcess
A value representing an authentication process.
See more
Declaration
Swift

public struct AuthenticationProcess : CustomStringConvertible

Stored Properties


                    
                    
                    application

Declaration

Swift

public let application: WebcomApplication

ongoingAuthentication
The ongoing authentication process.

This property is nil when there is no ongoing authentication process.
Declaration
Swift

public private(set) var ongoingAuthentication: AuthenticationProcess? { get set }
authenticationDetails
The authentication details of the currently authenticated user.

This property is nil when there is currently no authenticated user.
Declaration
Swift

public internal(set) var authenticationDetails: AuthenticationDetails? { get }

API

authenticationDetailsThrows()
Returns the authentication details of the currently authenticated user.

This method behaves like the authenticationDetails property, with the difference it throws instead of returning nil.

Throws
A WebcomError value when the user is unauthenticated.
Declaration
Swift

public func authenticationDetailsThrows() throws -> AuthenticationDetails


                    
                    
                    initializeAuthentication(with:context:)

Initializes an authentication process.

After using this method, the continueAuthentication(queue:then:) method must be called to continue the authentication process. Some additional steps, depending on the method, may be required between the two.

The method may be any authentication method, but single-steps ones should better use authenticate(with:queue:then:) directly, since it includes the call to continueAuthentication(queue:then:).

So, in practice, method should be an instance of AuthenticationMethodInternal.

Declaration

Swift

@discardableResult
public func initializeAuthentication(with method: AuthenticationMethod, context: Context = .new) -> WebcomResult<Void>

Parameters

`method`	The authentication method to use for the authentication process.
`context`	The context to use for the authentication process.

Return Value

A WebcomResult with a void value in case of success or a WebcomError value in case of the failure.


                    
                    
                    continueAuthentication(queue:then:)

Continues an authentication process initialized with initializeAuthentication(with:context:).

Declaration

Swift

public func continueAuthentication(queue: DispatchQueue? = nil, then completionCallback: WebcomResult<AuthenticationDetails>.Callback? = nil)

Parameters

`queue`	The queue to which the provided callback dispatches. When `nil`, the default callback queue of the application of this instance is used.
`completionCallback`	The closure to call upon completion. In case of success, it is called with the authenticated user details. In case of failure, it is called with a `WebcomError` value indicating the reason of the failure.


                    
                    
                    authenticate(with:context:queue:then:)

Authenticates the current user.

This method is only available for single-step authentication methods, that is methods which do not need user interaction driven by the application once started. All available methods, except AuthenticationMethodInternal, are eligible. Although it requires user interaction, AuthenticationMethodOAuth2 is well eligible since that interaction is driven by a ASWebAuthenticationSession, not by the application.

For multi-step methods, use initializeAuthentication(with:context:) and continueAuthentication(queue:then:).

Declaration

Swift

public func authenticate(with method: AuthenticationSingleStepMethod, context: Context = .new, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<AuthenticationDetails>.Callback? = nil)

Parameters

`method`	The single-step authentication method to use for the authentication process.
`context`	The context to use for the authentication process.
`queue`	The queue to which the provided callback dispatches. When `nil`, the default callback queue of the application of this instance is used.
`completionCallback`	The closure to call upon completion. In case of success, it is called with the authenticated user details. In case of failure, it is called with a `WebcomError` value indicating the reason of the failure.

cancelAuthentication()
Cancels the currently ongoing authentication process.

When there is no ongoing authentication process, this method is a no-op.
Declaration
Swift

public func cancelAuthentication()


                    
                    
                    unauthenticate(session:queue:then:)

Unauthenticates the current user.

This method succeeds when there is currently no authenticated user, and will unsubscribe all push notification subscriptions.

Declaration

Swift

public func unauthenticate(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

Parameters

`session`	The session used to send the requests to the back-end. When `nil`, the default session of the application of this instance is used.
`queue`	The queue to which the provided callback dispatches. When `nil`, the default callback queue of the application of this instance is used.
`completionCallback`	The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a `WebcomError` value indicating the reason of the failure.


                    
                    
                    subscribe(stores:file:line:queue:onEvent:onCompletion:)

Subscribes to authentication events.

A subscription must always be stored somewhere in order to be cancelled when it is no longer used. Until a subscription is cancelled, it remains active and consumes resources. The easiest way is to let this instance store it by setting the stores parameter to true (which is its default value). Otherwise, the returned subscription instance must be stored by the application.

Subscriptions stored by a AuthenticationService are cancelled automatically when it is deinitialized.

They can also be cancelled manually:

individually using the AuthenticationSubscription.cancel() method of the returned subscription instance,
globally using the unsubscribeFromAll() method of this service instance, provided that the stores parameter was set to true.

Declaration

Swift

@discardableResult
public func subscribe(stores: Bool = true, file: StaticString = #fileID, line: UInt = #line, queue: DispatchQueue? = nil, onEvent eventCallback: @escaping (_ event: AuthenticationEvent) -> Void, onCompletion completionCallback: (() -> Void)? = nil) -> AuthenticationSubscription?

Parameters

`stores`	Indicates whether the returned subscription should be stored by this instance.
`file`	The file from which the method is called. This is used for debugging purposes.
`line`	The line from which the method is called. This is used for debugging purposes.
`queue`	The queue to which the provided `eventCallback` and `completionCallback` dispatch. When `nil`, the default callback queue of the application of this instance is used.
`eventCallback`	The closure to call when an authentication event occurs.
`event`	The event that occurred.
`completionCallback`	The closure to call when the subscription completes.

Return Value

An instance describing the subscription, or nil if the subscription failed.

unsubscribeFromAll()
Cancels all stored subscriptions.

Subscriptions are stored by the subscribe(stores:file:line:queue:callback:) method when the stores parameter is set to true (which is its default value).

Usually, there is no need to call this method since it is done automatically when this instance is deinitialized.
Declaration
Swift

public func unsubscribeFromAll()


                    
                    
                    detachCurrentIdentity(queue:then:)

Detaches the current identity from the current user account.

In order to succeed, this sensitive operation requires a fresh enough authentication token. If the token is too old, then the operation will fail and the user will need to authenticate again before retrying the operation.

If the current identity is the last one of the user account, that account is destroyed, as the destroyAccount(queue:then:) method would do.

Declaration

Swift

public func detachCurrentIdentity(queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

Parameters

`queue`	The queue to which the provided callback dispatches. When `nil`, the default callback queue of the application of this instance is used.
`completionCallback`	The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a `WebcomError` value indicating the reason of the failure.


                    
                    
                    destroyAccount(queue:then:)

Destroys the account of the current user.

Calling this method does not remove any application-specific data stored using the DatasyncService. This also does not log-out the user, since any valid authentication token issued by the back-end remains valid until its expiration date.

Declaration

Swift

public func destroyAccount(queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

Parameters

`queue`	The queue to which the provided callback dispatches. When `nil`, the default callback queue of the application of this instance is used.
`completionCallback`	The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a `WebcomError` value indicating the reason of the failure.

Combine Module

CombineWrapper
The type that wraps AuthenticationService in order to enrich it with a Combine-based API.

See also the documentation section of WebcomWrapper for the corresponding wrapped type.

To use this type, import the following dependency in your code:
```
import WebcomCombine
```
See more
Declaration
Swift

public final class CombineWrapper : WebcomWrapper, Equatable, CustomDebugStringConvertible
forCombine
The wrapping instance, which has a Combine-based API.
Declaration
Swift

public var forCombine: CombineWrapper { get }