diff --git a/docs/authentication/configuration/sign-up-sign-in-options.mdx b/docs/authentication/configuration/sign-up-sign-in-options.mdx index bfca0ee5c4..82954925eb 100644 --- a/docs/authentication/configuration/sign-up-sign-in-options.mdx +++ b/docs/authentication/configuration/sign-up-sign-in-options.mdx @@ -190,16 +190,20 @@ Clerk currently offers the following MFA strategies: - **Authenticator application (also known as TOTP - Time-based One-time Password)** - **Backup codes** -Enabling MFA allows users of your app to turn it on for their own accounts through their [User Profile](docs/customization/account-portal/overview#user-profile) page. Enabling MFA does not automatically turn on MFA for all users. +Enabling MFA allows users of your app to turn it on for their own accounts through their [User Profile](/docs/customization/account-portal/overview#user-profile) page. Enabling MFA does not automatically turn on MFA for all users. If you're building a custom user interface instead of using Clerk's [Account Portal](/docs/customization/account-portal/overview) or [prebuilt components](/docs/components/overview), you can use [Clerk elements](/docs/customization/elements/examples/sign-in#multi-factor-authentication-mfa) or use [Clerk's API](/docs/custom-flows/email-password-mfa) to build a custom sign-in flow that allows users to sign in with MFA. ### Reset a user's MFA -To reset a user's MFA, you can either make a call to [Clerk's Backend API](https://clerk.com/docs/reference/backend-api/tag/Users#operation/DisableMFA) or use the [`disableUserMFA()`](/docs/references/backend/user/disable-user-mfa) method from the Javascript Backend SDK to remove the need to call the API directly. +You can reset a user's MFA by deleting their MFA enrollments. This will remove all of their MFA methods and they will have to enroll in MFA again. -> [!NOTE] -> Disabling MFA for a user will disable **all** of their MFA methods for the user at once. +To reset a user's MFA: + +1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor). +1. In the top navigation, select **Users**. +1. Select the user from the list. +1. Select the **Delete MFA enrollments** button. ## Sign-up restrictions diff --git a/docs/authentication/social-connections/apple.mdx b/docs/authentication/social-connections/apple.mdx index 1435439297..35726dd4f7 100644 --- a/docs/authentication/social-connections/apple.mdx +++ b/docs/authentication/social-connections/apple.mdx @@ -17,18 +17,30 @@ description: Learn how to allow users to sign into your Clerk app with their App } ]} > - - Use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) to authenticate users with OAuth. + - Use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) to authenticate users with OAuth in your apps and websites. Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) allows your users to sign in and sign up to your Clerk application with their Apple ID. ## Configure for your development instance -To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for _development instances_ - no other configuration is needed. Navigate to the Clerk Dashboard and go to **User & Authentication -> [Social Connections](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections)**. In the list of **Auth Providers**, enable Apple and select **Save**. +To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for _development instances_. +For **web based flows**, no other configuration is needed. For **native sign-in flows**, you must provide your app's [Bundle ID](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids). + +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections). In the top navigation, select **Configure**. Then in the sidebar, select **Social Connections**. In the list of **Auth Providers**, enable Apple. + +- For **web based flows**, select **Save**. +- For **native sign-in flows**, enable **Use custom credentials** and provide the **Apple Bundle ID**. If you're unsure about how to find this value, see the [Get your Apple Bundle ID](#get-your-apple-bundle-id) section. ## Configure for your production instance -In _production instances_, you must provide custom credentials, which includes generating your own **Apple Services ID**, **Apple Private Key**, **Apple Team ID**, and **Apple Key ID** using your Apple Developer account. Don't worry, this tutorial will walk you through that process in just a few steps. +In _production instances_, you must provide custom credentials. + +For **web based browser originated flows**, you need to generate and provide your own **Apple Services ID**, **Apple Private Key**, **Apple Team ID**, and **Apple Key ID** using your Apple Developer account. + +For **native sign in flows** (iOS, macOS, watchOS, tvOS), you must _at least_ provide your app's **Bundle ID**. For better results, it's recommended to also provide the web based flow fields. + +To configure your production instance, follow these steps: ### Enable Apple as a social connection @@ -36,13 +48,15 @@ In _production instances_, you must provide custom credentials, which includes g To get started, you must enable Apple as a social connection in your Clerk Dashboard. 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections). - 1. In the navigation sidebar, go to **User & Authentication > Social Connections**. + 1. In the top navigation, select **Configure**. Then in the sidebar, select **Social Connections**. 1. In the list of **Auth Providers**, enable **Apple**. 1. In the modal that opens, ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Email Source for Apple Private Email Relay** and **Return URL** values somewhere secure, as you'll need to supply them to Apple later. Leave this page and modal open. + 1. (For web based flows) Save the **Email Source for Apple Private Email Relay** and **Return URL** values somewhere secure, as you'll need to supply them to Apple later. Leave this page and modal open. ### Get your Apple Team ID + The **Apple Team ID** is _required_ for web based OAuth flows and _recommended_ for native app flows. + To get your **Apple Team ID**, you must create a new **App ID** in the Apple Developer portal. 1. In another tab, navigate to the [Apple Developer portal](https://developer.apple.com/account). @@ -57,6 +71,8 @@ In _production instances_, you must provide custom credentials, which includes g ### Get your Apple Services ID + The **Apple Services ID** is _required_ for web based OAuth flows and _recommended_ for native app flows. + To get your **Apple Services ID**, you must create a new **Services ID** in the Apple Developer portal. 1. You should be back at the **Identifiers** page. @@ -75,6 +91,8 @@ In _production instances_, you must provide custom credentials, which includes g ### Get your Apple Private Key and Key ID + The **Apple Private Key** and **Key ID** are _required_ for web based OAuth flows and _recommended_ for native app flows. + To get your **Apple Private Key** and **Key ID**, you must create a new **Key** in the Apple Developer portal. 1. You should be back at the **Identifiers** page. @@ -89,6 +107,8 @@ In _production instances_, you must provide custom credentials, which includes g ### Configure Email Source for Apple Private Relay + This step is _required_ for web based OAuth flows only. + Apple provides a privacy feature called [Hide My Email](https://support.apple.com/en-us/HT210425#hideemail), in which users can sign in to your app with Apple without revealing their real email addresses. Instead, your instance will receive an app-specific email address that will nevertheless forward any emails to the real user's address. To be able to send emails properly to users with hidden addresses, you must configure an additional setting in the Apple Developer portal. @@ -109,6 +129,23 @@ In _production instances_, you must provide custom credentials, which includes g - [https://support.apple.com/en-us/HT210425#hideemail](https://support.apple.com/en-us/HT210425#hideemail) - [https://help.apple.com/developer-account/?lang=en#/devf822fb8fc](https://help.apple.com/developer-account/?lang=en#/devf822fb8fc) + ### Get your Apple Bundle ID + + The **Apple Bundle ID** is _required_ for native OAuth flows (iOS, macOS, watchOS, tvOS). + + You can find your **Apple Bundle ID** in the list of app IDs or manually set it up. + + 1. Navigate to the [Apple Developer portal](https://developer.apple.com/account). + 1. Under **Certificates, IDs and Profiles**, select **Identifiers**. + 1. In the dropdown near the top-right of the page, select the **App IDs** option from the list. + 1. If you've already set up your project in XCode, your Bundle ID should be already registered. Otherwise, follow the steps below to create a new identifier. + 1. Next to **Identifiers** at the top of the page, select the plus icon (+) to register a new identifier. + 1. On the **Register a new identifier** page, select **App IDs**, then select **Continue**. + 1. On the next page, you'll be prompted to **Select a type** for your application. Choose **App** and select **Continue.** You will be redirected to the **Register an App ID** page. + 1. Fill in a description for your **App ID** and a **Bundle ID**. Any value is fine, such as "Clerk demo app" and "clerkdemoapp", respectively. Under **Capabilities**, ensure that **Sign In with Apple** is enabled. Then select **Continue**. You'll be redirected to the **Confirm your App ID** page. + 1. At the top of the page, you'll see your **Bundle ID**. Save this value somewhere secure, as you'll need it to configure your Clerk app. This is your **Apple Bundle ID** in Clerk. + 1. Finally, select **Register**. + ### Connect your Apple app to your Clerk app By now, you should have the following values saved from the Apple Developer portal: @@ -117,18 +154,19 @@ In _production instances_, you must provide custom credentials, which includes g - **Apple Services ID** - **Apple Key ID** - **Apple Private Key** file + - **Apple Bundle ID** (for native flows) Connect your Apple app to your Clerk app by adding these values to the Clerk Dashboard. 1. Navigate back to the tab where your Clerk Dashboard and your Apple configuration modal is open. - 1. Add all the corresponding fields. For the **Apple Private Key** file, open it with a text editor and just copy/paste the contents. + 1. Add all the corresponding fields depending on your desired flow. For the **Apple Private Key** file, open it with a text editor and just copy/paste the contents. 1. Select **Save**. ### Test your OAuth The simplest way to test your OAuth is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box. - 1. In the navigation sidebar of the Clerk Dashboard, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal). + 1. In the top navigation of the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=account-portal), select **Configure.** Then in the sidebar, select **Account Portal** 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: - **For development** – `https://your-domain.accounts.dev/sign-in` - **For production** – `https://accounts.your-domain.com/sign-in` diff --git a/docs/authentication/social-connections/oauth.mdx b/docs/authentication/social-connections/oauth.mdx index 4dd318d425..fc055a9a62 100644 --- a/docs/authentication/social-connections/oauth.mdx +++ b/docs/authentication/social-connections/oauth.mdx @@ -137,3 +137,11 @@ To allowlist a redirect URL via the Clerk Dashboard: 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections). 1. In the navigation sidebar, select **User & Authentication > Social Connections**. 1. Scroll to the **Allowlist for mobile OAuth redirect** section and add your redirect URLs. + +## OAuth for Apple native applications + +With Clerk, you can use [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) and offer a native authentication experience in your iOS, watchOS, macOS or tvOS apps. + +Instead of the typical OAuth flow that performs redirects in a browser context, you can utilize Apple's native authorization and provide the openID token and grant code to Clerk. Clerk ensures that the user will be verified in a secure and reliable way with the information that Apple has provided about the user. + +See [the dedicated guide](/docs/authentication/social-connections/apple) for additional information on how to configure Apple as a social provider for your Clerk instance. diff --git a/docs/deployments/set-up-preview-environment.mdx b/docs/deployments/set-up-preview-environment.mdx index bb43242f28..fc049ede8b 100644 --- a/docs/deployments/set-up-preview-environment.mdx +++ b/docs/deployments/set-up-preview-environment.mdx @@ -12,23 +12,23 @@ There are two high-level approaches to using Clerk in a preview environment: ## Sharing production settings and user data -To share production settings and user data with your preview environment, your preview environment must be hosted on the same root domain (but separate subdomain) as your production application. The preview environment must also be configured to use the same API keys as your production environment. +To share production settings and user data with your preview environment, your preview environment must be hosted on the same root domain (but a separate subdomain) as your production application. The preview environment must also be configured to use the same API keys as your production environment. Generally, hosts have a special feature to host the preview environment on a subdomain of your root domain, for example: -- **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only avialable on Vercel's Pro and Enterprise plans. +- **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only available on Vercel's Pro and Enterprise plans. - **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature. ## Using independent settings and user data There are two approaches to creating a preview environment with independent settings and user data: -1. **Easiest:** Use your hosts provided preview domain, like \*.vercel.app or \*.netlify.app, with development API keys from Clerk. +1. **Easiest:** Use your host's provided preview domain, like \*.vercel.app or \*.netlify.app, with development API keys from Clerk. 1. Acquire an additional root domain for your preview environment, completely separate from your production application's root domain. ### Use your host's provided preview domain -Configure the preview environment to use development API keys from Clerk. It is currently not possible to use Clerk production API keys with you host's provided preview domain. +Configure the preview environment to use development API keys from Clerk. It is currently not possible to use Clerk production API keys with your host's provided preview domain. ### Acquire an additional root domain @@ -37,7 +37,7 @@ Configure the preview environment to use development API keys from Clerk. It is To use an additional root domain, you must first configure your host to deploy preview environments to that domain: -- **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only avialable on Vercel's Pro and Enterprise plans. +- **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only available on Vercel's Pro and Enterprise plans. - **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature. -You can configure this environment with either your development API keys (recommended), or you can create an additional production instance and use those production API keys. +You can configure this environment with either your development API keys (recommended) or you can create an additional production instance and use those production API keys. diff --git a/docs/deployments/set-up-staging.mdx b/docs/deployments/set-up-staging.mdx index c1315daa14..03909bef66 100644 --- a/docs/deployments/set-up-staging.mdx +++ b/docs/deployments/set-up-staging.mdx @@ -3,9 +3,9 @@ title: Set up a staging environment with Clerk description: Learn how to set up a staging environment with Clerk authentication. --- -Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers **Development** and **Production** instances. Official support for **Staging** instances is still on [Clerk's roadmap](https://feedback.clerk.com/roadmap/de417dd1-fa2e-4997-868f-4c9248027e7d). However, you can set up a "staging environment" by creating a separate Clerk application with a separate domain. +Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers **Development** and **Production** instances. Official support for **Staging** instances is still on [Clerk's roadmap](https://feedback.clerk.com/roadmap/de417dd1-fa2e-4997-868f-4c9248027e7d). However, you can set up a "staging environment" by creating a subdomain for a separate Clerk application. -Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. And if you are on a Pro, Enterprise, or Startup plan, **Clerk will fully upgrade your staging application for free.** +Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. If you are on a Pro, Enterprise, or Startup plan, **Clerk will fully upgrade your staging application for free.** It is important to note that when you use a separate Clerk application for your staging environment, changes to this application will not be automatically mirrored in your main application for your production environment. You must manually make these changes yourself if you want them to be reflected in both applications. @@ -13,12 +13,12 @@ It is important to note that when you use a separate Clerk application for your The following steps will help you set up a new Clerk application with a staging-specific domain: -1. **Acquire a separate domain** - This domain will be used for your staging environment. _This cannot be a subdomain_ of the domain used in your production environment. For example, if your production domain is `my-site.com`, you could use `my-site-staging.com`. If you do not want to use a new domain, see [the instructions for using a subdomain](/docs/deployments/staging-alternatives). -1. **Create a new Clerk app** - Your staging environment will connect to this app instead of your main Clerk application. See [the Clerk quickstart guide](/docs/quickstarts/setup-clerk) to learn how to create a Clerk app. +1. **Set up a subdomain** - This will be your staging domain. For example, if your domain is `my-site.com`, you could use `staging.my-site.com`. +1. **Create a new Clerk app** - Your staging environment will connect to this app instead of your main one. See [the Clerk quickstart guide](/docs/quickstarts/setup-clerk) to learn how to create a Clerk app. 1. **Deploy and configure your staging app's production instance** - Using production API keys will make your staging app more secure. Follow the [Deploy to production](/docs/deployments/overview) guide to do so. 1. **Contact Clerk support to upgrade your staging app for free** - If you are on a Pro, Enterprise, or Startup plan, Clerk will fully upgrade your staging app for free. -## Alternatives to using a separate domain +## Alternatives ### Preview environments @@ -26,4 +26,4 @@ While staging environments are typically long-lived, preview environments are ty ### Shared production credentials -If you do not want to purchase a separate domain, or if you would like to share settings and data between your production and staging environments, see the [Staging alternatives](/docs/deployments/staging-alternatives) guide. This is not recommended because you will be sharing a user table between your production and staging environments. +If you would like to share settings and data between your production and staging environments, see [the dedicated guide](/docs/deployments/staging-alternatives). This is not recommended because you will be sharing a user table between your production and staging environments. diff --git a/docs/deployments/staging-alternatives.mdx b/docs/deployments/staging-alternatives.mdx index a61ea0fad7..5380935753 100644 --- a/docs/deployments/staging-alternatives.mdx +++ b/docs/deployments/staging-alternatives.mdx @@ -6,25 +6,25 @@ description: ## Shared production credentials > [!CAUTION] -> This is not recommended. Instead, you should either [set up a staging environment with a separate domain](/docs/deployments/set-up-staging) or [use a preview deployment](/docs/deployments/set-up-preview-environment). +> This is not recommended. Instead, you should either [set up a staging environment with a subdomain and separate Clerk app](/docs/deployments/set-up-staging) or [use a preview deployment](/docs/deployments/set-up-preview-environment). -If you do not want to purchase a separate domain, or if you would like to share settings and data between your production and staging environments, you can use a subdomain of your production domain to set up a staging environment. +If you would like to share settings and data between your production and staging environments, you can use a subdomain of your production domain to set up a staging environment. -### Limitations of using a subdomain +### Limitations of shared production credentials -The limitations of using a subdomain to set up a staging environment with Clerk include: +The limitations of using shared production credentials to set up a staging environment with Clerk include: - You will be combining staging data with live production data. - When you enable Clerk features to test in staging, they will be enabled in your Production environment as well. -### Set up staging with a subdomain +### Set up staging with shared production credentials 1. **Add your subdomain to your hosting provider** - Ensure that your subdomain is associated with your staging branch so that it will point to new staging deployments. This process will vary based on your provider. The following are some guides from popular hosting providers: - [Vercel](https://vercel.com/guides/set-up-a-staging-environment-on-vercel) - [Netlify](https://docs.netlify.com/domains-https/netlify-dns/delegate-a-subdomain-to-netlify-dns/) - [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-subdomain/) -1. **Add your CNAME record to your domain provider** - Depending on the provider, the verification process for this can take hours or days. -1. **Add your production instance API keys to your staging deployment** - In your staging deployment's environment variables, add your Clerk app's production instance API keys. Visit the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) section in the Clerk Dashboard to find them, and ensure that the instance at the top of the Dashboard is set to **Production**. The following are environment variable guides from some popular providers: +1. **Add your CNAME record to your domain provider** - Depending on the provider, the verification process can take hours or days. +1. **Add your production instance's API keys to your staging deployment** - In your staging deployment's environment variables, add your production instance's API keys. To find them, visit the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard and ensure that the instance at the top of the Dashboard is set to **Production**. The following are environment variable guides from some popular providers: - [Vercel](https://vercel.com/docs/projects/environment-variables#declare-an-environment-variable) - [Netlify](https://docs.netlify.com/environment-variables/get-started/#create-environment-variables) - - [Cloudflare](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboar) + - [Cloudflare](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard) diff --git a/docs/manifest.json b/docs/manifest.json index 8d73361c00..81caad884e 100644 --- a/docs/manifest.json +++ b/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" }]] + } ] ] }, diff --git a/docs/quickstarts/nextjs.mdx b/docs/quickstarts/nextjs.mdx index b4bdc7e9f1..dcc30e5356 100644 --- a/docs/quickstarts/nextjs.mdx +++ b/docs/quickstarts/nextjs.mdx @@ -53,8 +53,8 @@ description: Add authentication and user management to your Next.js app with Cle - 1. Navigate to the Clerk Dashboard. - 1. In the navigation sidebar, select [API Keys](https://dashboard.clerk.com/last-active?path=api-keys). + 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys). + 1. In the top navigation, select **Configure**. Then in the sidebar, select **API Keys**. 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. 1. Paste your keys into your `.env.local` file. @@ -102,7 +102,7 @@ description: Add authentication and user management to your Next.js app with Cle - [``](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**. - [``](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**. - [``](/docs/components/user/user-button): A prebuilt component that comes styled out of the box to show the avatar from the account the user is signed in with. - - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page or displays the sign-in modal. + - [``](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. For this example, because you have not specified any props or [environment variables](/docs/deployments/clerk-environment-variables) for the sign-in URL, the component will link to the [Account Portal sign-in page.](/docs/customization/account-portal/overview) Select your preferred router to learn how to make this data available across your entire app: @@ -157,7 +157,23 @@ description: Add authentication and user management to your Next.js app with Cle ### Create your first user - Now visit your app's homepage at [`http://localhost:3000`](http://localhost:3000). Sign up to create your first user. + Run your project with the following command: + + + ```bash {{ filename: 'terminal' }} + npm run dev + ``` + + ```bash {{ filename: 'terminal' }} + yarn dev + ``` + + ```bash {{ filename: 'terminal' }} + pnpm dev + ``` + + + Visit your app's homepage at [http://localhost:3000](http://localhost:3000). Sign up to create your first user. ## Next steps diff --git a/docs/references/ios/sign-in-with-apple.mdx b/docs/references/ios/sign-in-with-apple.mdx new file mode 100644 index 0000000000..58efa8cbe6 --- /dev/null +++ b/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. + + + ### 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 + ) + } + } + } + } + ``` +