From 4602fdbd6c232ccf5afcb2e96b201f9b65724ce8 Mon Sep 17 00:00:00 2001 From: Rita Zerrizuela Date: Fri, 1 Dec 2023 22:30:15 +0000 Subject: [PATCH] Add DoCC article on Web Auth user agents (#809) --- Auth0.xcodeproj/project.pbxproj | 10 +++ Documentation.docc/Documentation.md | 10 +++ Documentation.docc/WebAuth/UserAgents.md | 79 ++++++++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 Documentation.docc/Documentation.md create mode 100644 Documentation.docc/WebAuth/UserAgents.md diff --git a/Auth0.xcodeproj/project.pbxproj b/Auth0.xcodeproj/project.pbxproj index ff2212c8..7af04f01 100644 --- a/Auth0.xcodeproj/project.pbxproj +++ b/Auth0.xcodeproj/project.pbxproj @@ -109,6 +109,10 @@ 5C809D9A275FA3EF00F15A67 /* ManagementErrorSpec.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5C809D99275FA3EF00F15A67 /* ManagementErrorSpec.swift */; }; 5C809D9B275FA3EF00F15A67 /* ManagementErrorSpec.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5C809D99275FA3EF00F15A67 /* ManagementErrorSpec.swift */; }; 5C809D9C275FA3F000F15A67 /* ManagementErrorSpec.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5C809D99275FA3EF00F15A67 /* ManagementErrorSpec.swift */; }; + 5CA541CD2B1A81A700E4284D /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 5CA541CC2B1A81A700E4284D /* Documentation.docc */; }; + 5CA541CE2B1A81A700E4284D /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 5CA541CC2B1A81A700E4284D /* Documentation.docc */; }; + 5CA541CF2B1A81A700E4284D /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 5CA541CC2B1A81A700E4284D /* Documentation.docc */; }; + 5CA541D02B1A81A700E4284D /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 5CA541CC2B1A81A700E4284D /* Documentation.docc */; }; 5CB41D4023D0BA2C00074024 /* IDTokenValidatorContext.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5CB41D3C23D0BA2C00074024 /* IDTokenValidatorContext.swift */; }; 5CB41D4423D0BA2C00074024 /* IDTokenSignatureValidator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5CB41D3D23D0BA2C00074024 /* IDTokenSignatureValidator.swift */; }; 5CB41D4823D0BA2C00074024 /* IDTokenValidator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5CB41D3E23D0BA2C00074024 /* IDTokenValidator.swift */; }; @@ -497,6 +501,7 @@ 5C80980A275A7B8600DC0A76 /* CredentialsStorage.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CredentialsStorage.swift; sourceTree = ""; }; 5C809D95275F878E00F15A67 /* CredentialsManagerErrorSpec.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CredentialsManagerErrorSpec.swift; sourceTree = ""; }; 5C809D99275FA3EF00F15A67 /* ManagementErrorSpec.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ManagementErrorSpec.swift; sourceTree = ""; }; + 5CA541CC2B1A81A700E4284D /* Documentation.docc */ = {isa = PBXFileReference; lastKnownFileType = folder.documentationcatalog; path = Documentation.docc; sourceTree = ""; }; 5CB41D3C23D0BA2C00074024 /* IDTokenValidatorContext.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = IDTokenValidatorContext.swift; sourceTree = ""; }; 5CB41D3D23D0BA2C00074024 /* IDTokenSignatureValidator.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = IDTokenSignatureValidator.swift; sourceTree = ""; }; 5CB41D3E23D0BA2C00074024 /* IDTokenValidator.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = IDTokenValidator.swift; sourceTree = ""; }; @@ -802,6 +807,7 @@ 5F049B5F1CB42C29006F6C05 = { isa = PBXGroup; children = ( + 5CA541CC2B1A81A700E4284D /* Documentation.docc */, 5F049B6B1CB42C29006F6C05 /* Auth0 */, 5F06DD921CC451430011842B /* Auth0Tests */, 5F3965C81CF67DD800CDE7C0 /* App */, @@ -1669,6 +1675,7 @@ 5FDE87471D8A422300EA27DC /* Telemetry.swift in Sources */, 5FAE9C911D8878D400A871CE /* Auth0WebAuth.swift in Sources */, 5B5E93F91EC45C22002A37F9 /* CredentialsManagerError.swift in Sources */, + 5CA541CD2B1A81A700E4284D /* Documentation.docc in Sources */, 5C41F6AA244DCAFB00252548 /* ClearSessionTransaction.swift in Sources */, 5FDE875D1D8A424700EA27DC /* AuthenticationError.swift in Sources */, 5FADB6061CED27FB00D4BB50 /* Users.swift in Sources */, @@ -1731,6 +1738,7 @@ 5FCAB1741D09009600331C84 /* NSData+URLSafe.swift in Sources */, 970BC36C25C27095007A7745 /* Challenge.swift in Sources */, 5C41F6DD244F982700252548 /* DesktopWebAuth.swift in Sources */, + 5CA541CE2B1A81A700E4284D /* Documentation.docc in Sources */, 5FCAB17A1D09124D00331C84 /* NSURL+Auth0.swift in Sources */, 5FDE87561D8A424700EA27DC /* Auth0Authentication.swift in Sources */, 5FADB6071CED27FB00D4BB50 /* Users.swift in Sources */, @@ -1851,6 +1859,7 @@ 5FDE875B1D8A424700EA27DC /* Authentication.swift in Sources */, 5F23E6E21D4ACD7F00C3F2D9 /* Users.swift in Sources */, 5FDE876B1D8A424700EA27DC /* Credentials.swift in Sources */, + 5CA541D02B1A81A700E4284D /* Documentation.docc in Sources */, 5FE1182A1D8A4A2B00A374BF /* Telemetry.swift in Sources */, 5CC9940324ED9EC50027DC74 /* CredentialsManager.swift in Sources */, 5F23E6E41D4ACD8500C3F2D9 /* JSONObjectPayload.swift in Sources */, @@ -1889,6 +1898,7 @@ 5C29743223FDBD5400BC18FA /* Optional+DebugDescription.swift in Sources */, 5F23E70B1D4B88F600C3F2D9 /* Users.swift in Sources */, 5FDE876C1D8A424700EA27DC /* Credentials.swift in Sources */, + 5CA541CF2B1A81A700E4284D /* Documentation.docc in Sources */, 5FE118291D8A4A2A00A374BF /* Telemetry.swift in Sources */, 5F23E70D1D4B88FC00C3F2D9 /* JSONObjectPayload.swift in Sources */, 5C4F552623C8FBA100C89615 /* JWKS.swift in Sources */, diff --git a/Documentation.docc/Documentation.md b/Documentation.docc/Documentation.md new file mode 100644 index 00000000..5d21876a --- /dev/null +++ b/Documentation.docc/Documentation.md @@ -0,0 +1,10 @@ +# ``Auth0`` + +SDK for Apple platforms. + +## Overview + +- ``Auth0/WebAuth``: Web-based authentication client. +- ``Auth0/CredentialsManager``: Credentials management utility for securely storing and retrieving the user's credentials from the Keychain. +- ``Auth0/Authentication``: Client for the [Auth0 Authentication API](https://auth0.com/docs/api/authentication). +- ``Auth0/Users``: Client for the Users endpoints of the Auth0 [Management API v2](https://auth0.com/docs/api/management/v2). diff --git a/Documentation.docc/WebAuth/UserAgents.md b/Documentation.docc/WebAuth/UserAgents.md new file mode 100644 index 00000000..6c83bc37 --- /dev/null +++ b/Documentation.docc/WebAuth/UserAgents.md @@ -0,0 +1,79 @@ +# ASWebAuthenticationSession vs SFSafariViewController + +## Overview + +Web-based authentication needs a browser. Auth0.swift offers the choice of two system-provided browser APIs: [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) and [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller). + +## When to use ASWebAuthenticationSession + +`ASWebAuthenticationSession` is an API provided specifically for performing web-based authentication. It is not meant for general-purpose browsing, and exposes a pretty limited API. `ASWebAuthenticationSession` can be used with or without ephemeral sessions enabled –through the [`prefersEphemeralWebBrowserSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/3237231-prefersephemeralwebbrowsersessio) option. + +### Without ephemeral sessions (the default) + +```swift +Auth0 + .webAuth() + .start { result in + // ... + } +``` + +By default, Auth0.swift uses `ASWebAuthenticationSession` with `prefersEphemeralWebBrowserSession` set to `false`. This means that: + +- The session cookie will be shared with the Safari app. +- An alert box will be shown when logging in –and logging out– asking for consent, as the session cookie will be placed in a shared jar. This alert box is displayed and managed by `ASWebAuthenticationSession`, not Auth0.swift, and unfortunately it's not customizable. + +#### You want this if... + +- **You need SSO between your app and your website**, when your website is accessed through the Safari app. SSO will not work with any other browser, like Chrome or Firefox. +- **You need SSO across apps**. Since the session cookie will be placed in a shared cookie jar, it will be available for `ASWebAuthenticationSession` across *all* apps. + +### With ephemeral sessions + +Auth0.swift allows to set `prefersEphemeralWebBrowserSession` to `true`, by calling `useEphemeralSession()`. + +```swift +Auth0 + .webAuth() + .useEphemeralSession() + .start { result in + // ... + } +``` + +`prefersEphemeralWebBrowserSession` being set to `true` means that: + +- The session cookie will not be persisted. As soon as the `ASWebAuthenticationSession` window closes, the cookie will be gone. This is akin to using a desktop browser in incognito mode. +- Any features that rely on the persistence of cookies –like SSO, or "Remember this device"– **will not work**. +- No consent alert box will be shown, as the session cookie won't be placed in a shared cookie jar. +- There will be no need to call `clearSession()`. What `clearSession()` does is remove the persisted session cookie. Now there will be no session cookie to remove, so it won't do anything. To log the user out, just delete any stored credentials –for example, by calling the `clear()` method of the Credentials Manager. + +#### You want this if... + +- **You don't need SSO at all**. Since the session cookie won't be persisted, SSO will be effectively disabled. +- **You don't need any features that rely on the persistence of cookies**, like "Remember this device". + +## When to use SFSafariViewController + +```swift +Auth0 + .webAuth() + .provider(WebAuthentication.safariProvider()) + .start { result in + // ... + } +``` + +`SFSafariViewController` is a general purpose in-app browser that can also be used to perform web-based authentication. When used for this purpose, it acts as a middle ground between `ASWebAuthenticationSession` with/without ephemeral sessions. It persists cookies, but won't share them outside of your app. This means that: + +- All the `SFSafariViewController` instances used in your app will have access to the persisted session cookie. +- No consent alert box will be shown, as the session cookie won't be placed in a shared cookie jar. +- All the features that rely on the persistence of cookies –like "Remember this device"– **will work** as expected. + +#### You want this if... + +- **You need SSO between your app and your website**, when your website is accessed through another `SFSafariViewController` instance in your app. + +## See Also + +- [FAQ](https://github.com/auth0/Auth0.swift/blob/master/FAQ.md)