Add DoCC article on Web Auth user agents

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 = "<group>"; };
 		5C809D95275F878E00F15A67 /* CredentialsManagerErrorSpec.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CredentialsManagerErrorSpec.swift; sourceTree = "<group>"; };
 		5C809D99275FA3EF00F15A67 /* ManagementErrorSpec.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ManagementErrorSpec.swift; sourceTree = "<group>"; };
+		5CA541CC2B1A81A700E4284D /* Documentation.docc */ = {isa = PBXFileReference; lastKnownFileType = folder.documentationcatalog; path = Documentation.docc; sourceTree = "<group>"; };
 		5CB41D3C23D0BA2C00074024 /* IDTokenValidatorContext.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = IDTokenValidatorContext.swift; sourceTree = "<group>"; };
 		5CB41D3D23D0BA2C00074024 /* IDTokenSignatureValidator.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = IDTokenSignatureValidator.swift; sourceTree = "<group>"; };
 		5CB41D3E23D0BA2C00074024 /* IDTokenValidator.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = IDTokenValidator.swift; sourceTree = "<group>"; };
@@ -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 */,

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).

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)