Login with Apple

Using the OAuth flow for web#

Sign in with Apple's OAuth flow is designed for web or browser based sign in methods. It can be used on web-based apps as well as websites, though some users can benefit by using Sign in with Apple JS directly.

Behind the scenes, Supabase Auth uses the REST APIs provided by Apple.

To initiate sign in, you can use the signInWithOAuth() method from the Supabase JavaScript library:

1
2
3
supabase.auth.signInWithOAuth({  provider: 'apple',})

This call takes the user to Apple's consent screen. Once the flow ends, the user's profile information is exchanged and validated with Supabase Auth before it redirects back to your web application with an access and refresh token representing the user's session.

For a PKCE flow, for example in Server-Side Auth, you need an extra step to handle the code exchange. When calling signInWithOAuth, provide a redirectTo URL which points to a callback route. This redirect URL should be added to your redirect allow list.

1
2
3
4
5
6
await supabase.auth.signInWithOAuth({  provider,  options: {    redirectTo: `http://example.com/auth/callback`,  },})

At the callback endpoint, handle the code exchange to save the user session.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import { NextResponse } from 'next/server'// The client you created from the Server-Side Auth instructionsimport { createClient } from '@/utils/supabase/server'export async function GET(request: Request) {  const { searchParams, origin } = new URL(request.url)  const code = searchParams.get('code')  // if "next" is in param, use it as the redirect URL  let next = searchParams.get('next') ?? '/'  if (!next.startsWith('/')) {    // if "next" is not a relative URL, use the default    next = '/'  }  if (code) {    const supabase = await createClient()    const { error } = await supabase.auth.exchangeCodeForSession(code)    if (!error) {      const forwardedHost = request.headers.get('x-forwarded-host') // original origin before load balancer      const isLocalEnv = process.env.NODE_ENV === 'development'      if (isLocalEnv) {        // we can be sure that there is no load balancer in between, so no need to watch for X-Forwarded-Host        return NextResponse.redirect(`${origin}${next}`)      } else if (forwardedHost) {        return NextResponse.redirect(`https://${forwardedHost}${next}`)      } else {        return NextResponse.redirect(`${origin}${next}`)      }    }  }  // return the user to an error page with instructions  return NextResponse.redirect(`${origin}/auth/auth-code-error`)}

Configuration #

You will require the following information:

1. Your Apple Developer account's Team ID, which is an alphanumeric string of 10 characters that uniquely identifies the developer of the app. It's often accessible in the upper right-side menu on the Apple Developer Console.
2. Register email sources for Sign in with Apple for Email Communication which can be found in the Services section of the Apple Developer Console. This enables Apple to send relay emails through your domain when users choose to hide their email addresses.
3. An App ID which uniquely identifies the app you are building. You can create a new App ID from the Identifiers section in the Apple Developer Console (use the filter menu in the upper right side to see all App IDs). These usually are a reverse domain name string, for example com.example.app. Make sure you configure Sign in with Apple once you create an App ID in the Capabilities list. At this time Supabase Auth does not support Server-to-Server notification endpoints, so you should leave that setting blank. (In the past App IDs were referred to as bundle IDs.)
4. A Services ID which uniquely identifies the web services provided by the app you registered in the previous step. You can create a new Services ID from the Identifiers section in the Apple Developer Console (use the filter menu in the upper right side to see all Services IDs). These usually are a reverse domain name string, for example com.example.app.web.
5. Configure Website URLs for the newly created Services ID. The web domain you should use is the domain your Supabase project is hosted on. This is usually <project-id>.supabase.co while the redirect URL is https://<project-id>.supabase.co/auth/v1/callback.
6. Create a signing Key in the Keys section of the Apple Developer Console. You can use this key to generate a secret key using the tool below, which is added to your Supabase project's Auth configuration. Make sure you safely store the AuthKey_XXXXXXXXXX.p8 file. If you ever lose access to it, or make it public accidentally, revoke it from the Apple Developer Console and create a new one immediately.
7. Finally, add the information you configured above to the Apple provider configuration in the Supabase dashboard.

You can also configure the Apple auth provider using the Management API:

1
2
3
4
5
6
7
8
9
10
11
12
13
# Get your access token from https://supabase.com/dashboard/account/tokensexport SUPABASE_ACCESS_TOKEN="your-access-token"export PROJECT_REF="your-project-ref"# Configure Apple auth providercurl -X PATCH "https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth" \  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "external_apple_enabled": true,    "external_apple_client_id": "your-services-id",    "external_apple_secret": "your-generated-secret-key"  }'

Using sign in with Apple JS#

Sign in with Apple JS is an official Apple framework for authenticating Apple users on websites. Although it can be used in web-based apps, those use cases will benefit more with the OAuth flow described above. We recommend using this method on classic websites only.

You can use the signInWithIdToken() method from the Supabase JavaScript library on the website to obtain an access and refresh token once the user has given consent using Sign in with Apple JS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
async function signIn() {  try {    // Generate a nonce for security    const nonce = crypto.randomUUID() // or use your preferred nonce generation method    const data = await AppleID.auth.signIn()    const { data: authData, error } = await supabase.auth.signInWithIdToken({      provider: 'apple',      token: data.id_token,      nonce: nonce,    })    if (error) {      throw error    }    // Apple only provides the user's name on the first sign-in    // The user object contains name information from Apple's response    if (data.user && data.user.name) {      const fullName = [        data.user.name.firstName,        data.user.name.middleName,        data.user.name.lastName      ].filter(Boolean).join(' ')      // Save the name to user metadata for future use      await supabase.auth.updateUser({        data: {          full_name: fullName,          given_name: data.user.name.firstName,          family_name: data.user.name.lastName,        }      })    }  } catch (error) {    console.error('Apple sign in failed:', error)    // Handle sign-in errors appropriately  }}

Alternatively, you can use the AppleIDSignInOnSuccess event with the usePopup option:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// Generate and store nonce for verificationconst nonce = crypto.randomUUID()// Initialize Apple ID with nonceAppleID.auth.init({  clientId: 'your-services-id',  scope: 'name email',  redirectURI: 'https://your-domain.com/auth/callback',  usePopup: true,  nonce: nonce,})// Listen for authorization successdocument.addEventListener('AppleIDSignInOnSuccess', async (event) => {  try {    const { data: authData, error } = await supabase.auth.signInWithIdToken({      provider: 'apple',      token: event.detail.authorization.id_token,      nonce: nonce,    })    if (error) {      throw error    }    // Apple only provides the user's name on the first sign-in    if (event.detail.user && event.detail.user.name) {      const fullName = [        event.detail.user.name.firstName,        event.detail.user.name.middleName,        event.detail.user.name.lastName      ].filter(Boolean).join(' ')      // Save the name to user metadata for future use      await supabase.auth.updateUser({        data: {          full_name: fullName,          given_name: event.detail.user.name.firstName,          family_name: event.detail.user.name.lastName,        }      })    }  } catch (error) {    console.error('Apple sign in failed:', error)  }})

Make sure you request the scope name email when initializing the library, as shown in the example above.

Configuration #

To use Sign in with Apple JS you need to configure these options:

1. Have an App ID which uniquely identifies the app you are building. You can create a new App ID from the Identifiers section in the Apple Developer Console (use the filter menu in the upper right side to see all App IDs). These usually are a reverse domain name string, for example com.example.app. Make sure you configure Sign in with Apple for the App ID you created or already have, in the Capabilities list. At this time Supabase Auth does not support Server-to-Server notification endpoints, so you should leave that setting blank. (In the past App IDs were referred to as bundle IDs.)
2. Obtain a Services ID attached to the App ID that uniquely identifies the website. Use this value as the client ID when initializing Sign in with Apple JS. You can create a new Services ID from the Identifiers section in the Apple Developer Console (use the filter menu in the upper right side to see all Services IDs). These usually are a reverse domain name string, for example com.example.app.website.
3. Configure Website URLs for the newly created Services ID. The web domain you should use is the domain your website is hosted on. The redirect URL must also point to a page on your website that will receive the callback from Apple.
4. Register the Services ID you created to your project's Apple provider configuration in the Supabase dashboard under Client IDs.