_AuthenticationServices_SwiftUI · IOS API REFERENCE
WebAuthenticationSession
struct · iOS 16.4+ · SDK 27.1
@MainActor struct WebAuthenticationSession
A value provided in the SwiftUI environment that views can use to
authenticate a user through a web service.
Use the ``SwiftUI/Environment`` property wrapper to get an instance of
this structure from the ``EnvironmentValues/webAuthenticationSession``
environment value.
For example, you can start a web authentication session when the
user taps a button:
struct WebAuthenticationSessionExample: View {
@Environment(\.webAuthenticationSession) private var webAuthenticationSession
var body: some View {
Button("Sign In") {
Task {
do {
let urlWithToken = try await webAuthenticationSession.authenticate(
using: URL(string: "https://www.example.com")!,
callbackURLScheme: "x-example-app")
try await signIn(using: urlWithToken) // defined elsewhere
} catch {
// code to handle authentication errors
}
}
}
}
}
Use ``WebAuthenticationSession/BrowserSession/ephemeral``
to request that the browser doesn't share cookies or other browsing data
between the authentication session and the user's normal browser session.
Whether the request is honored depends on the user's default web browser.
Safari always honors the request.
let urlWithToken = try await webAuthenticationSession.authenticate(
using: URL(string: "https://www.example.com")!,
callbackURLScheme: "x-example-app",
preferredBrowserSession: .ephemeral)
After the user authenticates, the authentication provider redirects the
browser to a URL that uses the callback scheme. The browser detects the
redirect, dismisses itself, and the complete URL will be returned. Inspect
the URL to determine the outcome of the authentication:
let queryItems = URLComponents(string: urlWithToken.absoluteString)?.queryItems
let token = queryItems?.first(where: { $0.name == "token" })?.value
The above example looks for a token stored as a query parameter. The
specific parsing that you have to do depends on how the authentication
provider structures the callback URL.
Start a web authentication session.
For example, you can start a web authentication session when the
user taps a button:
struct WebAuthenticationSessionExample: View {
@Environment(\.webAuthenticationSession) private var webAuthenticationSession
var body: some View {
Button("Sign In") {
Task {
do {
let urlWithToken = try await webAuthenticationSession.authenticate(
using: URL(string: "https://www.example.com")!,
callbackURLScheme: "x-example-app")
try await signIn(using: urlWithToken) // defined elsewhere
} catch {
// code to handle authentication errors
}
}
}
}
}
Use ``WebAuthenticationSession/BrowserSession/ephemeral``
to request that the browser doesn't share cookies or other browsing data
between the authentication session and the user's normal browser session.
Whether the request is honored depends on the user's default web browser.
Safari always honors the request.
let urlWithToken = try await webAuthenticationSession.authenticate(
using: URL(string: "https://www.example.com")!,
callbackURLScheme: "x-example-app",
preferredBrowserSession: .ephemeral)
After the user authenticates, the authentication provider redirects the
browser to a URL that uses the callback scheme. The browser detects the
redirect, dismisses itself, and the complete URL will be returned. Inspect
the URL to determine the outcome of the authentication:
let queryItems = URLComponents(string: urlWithToken.absoluteString)?.queryItems
let token = queryItems?.first(where: { $0.name == "token" })?.value
The above example looks for a token stored as a query parameter. The
specific parsing that you have to do depends on how the authentication
provider structures the callback URL.
- Parameters:
- url: A URL with the `http` or `https` scheme pointing to the
authentication webpage.
- callbackURLScheme: The custom scheme that the app expects in
the callback URL.
- preferredBrowserSession: The preferred type of browser session
that should be used by the authentication session. Pass `nil`
to use the the default behavior provided by the system.
- Returns: The URL returned by the authentication provider.
Similar to the above method, except using `ASWebAuthenticationSession.Callback` for the callback matching.
This method also provides the option to pass additional headers for the initial page load.
- additionalHeaderFields: A dictionary containing additional header fields to send when loading the initial URL. All header field names must start with the "X-" prefix.
