WebAuth

public protocol WebAuth : Loggable, Trackable

Web-based authentication using Auth0.

  • The Auth0 Client ID.

    Declaration

    Swift

    var clientId: String { get }
  • url

    The Auth0 Domain URL.

    Declaration

    Swift

    var url: URL { get }
  • The Telemetry instance.

    Declaration

    Swift

    var telemetry: Telemetry { get set }

Builder

  • Specify an Auth0 connection to directly show that Identity Provider’s login page, skipping the Universal Login page itself. By default no connection is specified, so the Universal Login page will be displayed.

    Declaration

    Swift

    func connection(_ connection: String) -> Self

    Parameters

    connection

    Name of the connection.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify the scopes that will be requested during authentication.

    See

    Scopes

    Declaration

    Swift

    func scope(_ scope: String) -> Self

    Parameters

    scope

    Space-separated list of requested scope values. E.g. openid profile email offline_access.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify provider scopes for OAuth2/social connections, e.g. Facebook, Google, etc.

    Declaration

    Swift

    func connectionScope(_ connectionScope: String) -> Self

    Parameters

    connectionScope

    Space-separated list of requested OAuth2/social scope values. E.g. user_friends email.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify a state parameter that will be sent back after authentication to verify that the response corresponds to your request. By default a random value is used.

    Declaration

    Swift

    func state(_ state: String) -> Self

    Parameters

    state

    State value.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify additional parameters for authentication.

    Declaration

    Swift

    func parameters(_ parameters: [String : String]) -> Self

    Parameters

    parameters

    Additional authentication parameters.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify a custom redirect URL to be used.

    Declaration

    Swift

    func redirectURL(_ redirectURL: URL) -> Self

    Parameters

    redirectURL

    Custom redirect URL.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify an audience name for the API that your application will call using the Access Token returned after authentication. This value must match the API Identifier defined in the APIs section of the Auth0 Dashboard.

    See

    Audience]

    Declaration

    Swift

    func audience(_ audience: String) -> Self

    Parameters

    audience

    Audience value. E.g. https://example.com/api.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify a nonce parameter for ID Token validation.

    Declaration

    Swift

    func nonce(_ nonce: String) -> Self

    Parameters

    nonce

    Nonce value.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify a custom issuer for ID Token validation. This value will be used instead of the Auth0 Domain.

    Declaration

    Swift

    func issuer(_ issuer: String) -> Self

    Parameters

    issuer

    Custom issuer value. E.g. https://example.com/.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify a leeway amount for ID Token validation. This value represents the clock skew for the validation of date claims, e.g. exp.

    Declaration

    Swift

    func leeway(_ leeway: Int) -> Self

    Parameters

    leeway

    Number of milliseconds. Defaults to 60_000 (1 minute).

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify a max_age parameter for authentication. Sending this parameter will require the presence of the auth_time claim in the ID Token.

    Declaration

    Swift

    func maxAge(_ maxAge: Int) -> Self

    Parameters

    maxAge

    Number of milliseconds.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Use a private browser session to avoid storing the session cookie in the shared cookie jar.

    Requires

    iOS 13+ or macOS. Has no effect on iOS 12.

    Important

    This method will disable Single Sign On (SSO).

    Declaration

    Swift

    func useEphemeralSession() -> Self

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify an invitation URL to join an organization.

    Declaration

    Swift

    func invitationURL(_ invitationURL: URL) -> Self

    Parameters

    invitationURL

    Invitation URL for the organization.

    Return Value

    The same WebAuth instance to allow method chaining.

  • Specify an organization identifier to log in to.

    Declaration

    Swift

    func organization(_ organization: String) -> Self

    Parameters

    organization

    ID of the organization.

    Return Value

    The same WebAuth instance to allow method chaining.

Methods

  • Starts the Web Auth flow.

    Auth0
        .webAuth(clientId: clientId, domain: "samples.auth0.com")
        .start { result in
            switch result {
            case .success(let credentials):
                print("Obtained credentials: \(credentials)")
            case .failure(let error):
                print("Failed with: \(error)")
        }
    }
    

    Any ongoing Web Auth session will be automatically cancelled when starting a new one, and its corresponding callback with be called with a failure result containing a userCancelled error.

    Requires

    The Callback URL to have been added to the Allowed Callback URLs field of your Auth0 application settings in the Dashboard.

    Declaration

    Swift

    func start(_ callback: @escaping (WebAuthResult<Credentials>) -> Void)

    Parameters

    callback

    Callback that receives a Result containing either the user’s credentials or an error.

  • start() Asynchronous

    Declaration

    Swift

    func start() async throws -> Credentials
  • Starts the Web Auth flow.

    Auth0
        .webAuth(clientId: clientId, domain: "samples.auth0.com")
        .start()
        .sink(receiveCompletion: { completion in
            if case .failure(let error) = completion {
                print("Failed with: \(error)")
            }
        }, receiveValue: { credentials in
            print("Obtained credentials: \(credentials)")
        })
        .store(in: &cancellables)
    

    Any ongoing Web Auth session will be automatically cancelled when starting a new one, and the subscription will complete with a failure result containing a userCancelled error.

    Requires

    The Callback URL to have been added to the Allowed Callback URLs field of your Auth0 application settings in the Dashboard.

    Declaration

    Swift

    @available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.2, *)
    func start() -> AnyPublisher<Credentials, WebAuthError>

    Return Value

    A type-erased publisher.

  • clearSession(federated:callback:) Default implementation

    Removes the Auth0 session and optionally removes the Identity Provider (IdP) session.

    Auth0
        .webAuth()
        .clearSession { result in
            switch result {
            case .success:
                print("Session cookie cleared")
            case .failure(let error):
                print("Failed with: \(error)")
        }
    

    Remove both the Auth0 session and the Identity Provider session:

    Auth0
        .webAuth()
        .clearSession(federated: true) { print($0) }
    

    Requires

    The Callback URL to have been added to the Allowed Logout URLs field of your Auth0 application settings in the Dashboard.

    Note

    You don’t need to call this method if you are using useEphemeralSession() on login, because there will be no shared cookie to remove.

    See

    Logout

    Default Implementation

    Declaration

    Swift

    func clearSession(federated: Bool, callback: @escaping (WebAuthResult<Void>) -> Void)

    Parameters

    federated

    If the Identity Provider session should be removed. Defaults to false.

    callback

    Callback that receives a Result containing either an empty success case or an error.

  • clearSession(federated:) Default implementation

    Removes the Auth0 session and optionally removes the Identity Provider (IdP) session.

    Auth0
        .webAuth()
        .clearSession()
        .sink(receiveCompletion: { completion in
            switch completion {
            case .finished:
                print("Session cookie cleared")
            case .failure(let error):
                print("Failed with: \(error)")
            }
        }, receiveValue: {})
        .store(in: &cancellables)
    

    Remove both the Auth0 session and the Identity Provider session:

    Auth0
        .webAuth()
        .clearSession(federated: true)
        .sink(receiveCompletion: { print($0) },
              receiveValue: {})
        .store(in: &cancellables)
    

    Requires

    The Callback URL to have been added to the Allowed Logout URLs field of your Auth0 application settings in the Dashboard.

    Note

    You don’t need to call this method if you are using useEphemeralSession() on login, because there will be no shared cookie to remove.

    See

    Logout

    Default Implementation

    Declaration

    Swift

    @available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.2, *)
    func clearSession(federated: Bool) -> AnyPublisher<Void, WebAuthError>

    Parameters

    federated

    If the Identity Provider session should be removed. Defaults to false.

    Return Value

    A type-erased publisher.

  • clearSession(federated:) Default implementation, asynchronous

    Default Implementation

    Declaration

    Swift

    func clearSession(federated: Bool) async throws