iOS: Guide - Sign in with Apple (#1397)

Co-authored-by: Alexis Aguilar <[email protected]>
Co-authored-by: Brad Cornes <[email protected]>

docs/manifest.json

@@ -2130,7 +2130,11 @@
               "items": [
                 [
                   { "title": "Overview", "href": "/docs/references/ios/overview" },
-                  { "title": "`getToken()`", "href": "/docs/references/ios/get-token" }
+                  { "title": "`getToken()`", "href": "/docs/references/ios/get-token" },
+                  {
+                    "title": "Guides",
+                    "items": [[{ "title": "Sign in with Apple", "href": "/docs/references/ios/sign-in-with-apple" }]]
+                  }
                 ]
               ]
             },

docs/references/ios/sign-in-with-apple.mdx

@@ -0,0 +1,72 @@
+---
+title: Sign in with Apple
+description: Learn how to use Clerk to natively Sign in with Apple.
+---
+
+> [!WARNING]
+> The Clerk iOS SDK is currently in beta. It is **not yet recommended for production use**.
+
+This guide will teach you how to add native Sign in with Apple to your Clerk apps on Apple platforms.
+
+<Steps>
+  ### Configure the Apple social connection
+
+  To support native Sign in with Apple, you need to configure the Apple social connection in the Clerk Dashboard. To do so, follow the **native-specific instructions** in the [OAuth with Apple guide](/docs/authentication/social-connections/apple).
+
+  ### Add the Sign in with Apple capability to your app
+
+  [Add the Sign in with Apple capability to your app](https://developer.apple.com/documentation/xcode/configuring-sign-in-with-apple#Add-the-Sign-in-with-Apple-capability-to-your-app).
+
+  ### Obtain an Apple ID Credential
+
+  To authenticate with Apple and Clerk, you need to obtain an [Apple ID Credential](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidcredential).
+
+  To obtain an Apple ID Credential, you can do one of the following:
+
+  - Use one of [Apple's built-in Sign in with Apple buttons](https://developer.apple.com/documentation/sign_in_with_apple/displaying_sign_in_with_apple_buttons_in_your_app).
+  - Obtain it manually by following [the Apple docs](https://developer.apple.com/documentation/sign_in_with_apple/)
+
+  > [!NOTE]
+  > You must set the nonce property of the `ASAuthorizationAppleIDRequest` when requesting an Apple ID Credential in order to authenticate with Clerk.
+
+  ### Build your sign-in flow
+
+  Once you have obtained your [Apple ID Credential](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidcredential), you can use it to authenticate with Clerk by calling [`SignIn.signInWithAppleIdToken()`](https://swiftpackageindex.com/clerk/clerk-ios/main/documentation/clerksdk/signin/#type-methods).
+
+  The following example uses Apple's built-in `SignInWithAppleButton` to obtain an Apple ID Credential and calls `SignIn.signInWithAppleIdToken()` to authenticate with Clerk.
+
+  ```swift {{ filename: 'SignInWithAppleView.swift' }}
+  import SwiftUI
+  import ClerkSDK
+  import AuthenticationServices
+
+  struct SignInWithAppleView: View {
+    var body: some View {
+      // Use Apple's built-in SignInWithAppleButton
+      SignInWithAppleButton { request in
+        request.requestedScopes = [.email, .fullName]
+        request.nonce = UUID().uuidString // Setting the nonce is mandatory
+      } onCompletion: { result in
+        Task {
+          // Access the Apple ID Credential
+          guard let credential = try result.get().credential as? ASAuthorizationAppleIDCredential else {
+            dump("Unable to get credential of type ASAuthorizationAppleIDCredential")
+            return
+          }
+
+          // Access the necessary identity token on the Apple ID Credential
+          guard let token = credential.identityToken.flatMap({ String(data: $0, encoding: .utf8) }) else {
+            dump("Unable to get ID token from Apple ID Credential.")
+            return
+          }
+
+          // Authenticate with Clerk
+          try await SignIn.signInWithAppleIdToken(
+            idToken: token
+          )
+        }
+      }
+    }
+  }
+  ```
+</Steps>