Overview

This guide will walk you through setting up Sign in with Apple authentication for your Convex application. By the end of this setup, your users will be able to sign in using their Apple accounts.

Important Note: Unlike other providers, Apple doesn't allow you to test your Sign in with Apple integration using an app running on localhost. You'll need to fully deploy your application to a public site with a valid SSL certificate.

Prerequisites

Before starting, ensure you have:

• An Apple Developer account (create one at Apple Developer)
• A Convex project set up and deployed to production
• Access to your Convex deployment's HTTP Actions URL
• A deployed application with a valid SSL certificate (HTTPS required)

Step 1: Create an App ID

1. Navigate to the Apple Certificates, Identifiers & Profiles page
2. Select "App IDs" in the dropdown on the right (if not already selected)
3. Click the "+" button next to Identifiers

Configure App ID

1. On the Register a New Identifier page, ensure "App IDs" is selected
2. Click "Continue"
3. On the next page, with "App" selected, click "Continue"
4. Fill in the required fields:
   • Description: Enter a descriptive name for your app
   • Bundle ID: Choose "Explicit" and enter your unique bundle identifier (e.g., com.yourcompany.yourapp)

Enable Sign in with Apple

1. Scroll down to the Capabilities section
2. Find "Sign In with Apple" in the list and check the box next to it
3. Click "Continue" and then "Register"

Step 2: Create a Service ID

Initial Service ID Setup

1. Back on the Certificates, Identifiers & Profiles page, use the dropdown and select "Services IDs"
2. Click the "+" button next to Identifiers
3. On the Register a New Identifier page, ensure "Services IDs" is selected
4. Click "Continue"

Configure Service ID

1. Fill in the required fields:
   • Description: Enter a description for your service
   • Identifier: Enter a unique identifier (e.g., com.yourcompany.yourapp.service)
2. Click "Continue" and then "Register"

Step 3: Create a Key

Generate Apple Key

1. Click on "Keys" in the left navigation menu
2. Click the "+" button next to Keys
3. Enter a Key Name for identification purposes

Configure Key for Sign in with Apple

1. Scroll down and check the box next to "Sign In with Apple"
2. Click the "Configure" button beside it
3. On the configuration page, select the App ID you created earlier as the Primary App ID
4. Click "Save"

Download and Secure Your Key

1. Back on the Register a New Key page, click "Continue"
2. Click "Register"
3. Important: Download the key file (.p8 format) on the next screen
4. Store this file securely - Apple only allows you to download it once
5. Click "Done"

Step 4: Configure Callback URL

Find Your Convex HTTP Actions URL

1. Open your Convex dashboard
2. Navigate to Settings > URL & Deploy Key > Show development credentials
3. Note your HTTP Actions URL (ends with .site, not .cloud)

Configure Service ID for Web Authentication

1. Return to the Certificates, Identifiers & Profiles page
2. Use the dropdown to select "Services IDs"
3. Click on the Service ID you created earlier
4. Ensure "Sign In with Apple" is checked and click "Configure"

Set Up Website URLs

1. In the Domains and Subdomains field, enter just the domain portion of your HTTP Actions URL:

   fast-horse-123.convex.site
   

2. In the Return URLs field, enter your complete callback URL:

   https://fast-horse-123.convex.site/api/auth/callback/apple
   

3. Click "Next"

4. Confirm the values are correct and click "Done"

5. Back on the Services ID configuration page, click "Continue" and then "Save"

Step 5: Generate Apple Client Secret

Gather Required Information

You'll need the following information to generate your Apple client secret:

1. Team ID (Account ID): Found in the upper-right corner of Apple Developer Center (10 alphanumeric characters)
2. Service ID: The identifier you created for your service (e.g., com.yourcompany.yourapp.service)
3. Key ID: Found in the filename of your downloaded key file (AuthKey_XXXXXXXXXX.p8)
4. Private Key: The content of your downloaded .p8 file

Generate JWT Secret

Apple requires a signed JWT token as the client secret. You can use various methods to generate this:

Method 1: Using Online JWT Generator (Recommended for Development)

Use a secure JWT generator that processes data locally in your browser. The JWT should include:

• Header:

  Copy{
    "alg": "ES256",
    "kid": "YOUR_KEY_ID"
  }

• Payload:

  Copy{
    "iss": "YOUR_TEAM_ID",
    "iat": 1234567890,
    "exp": 1234567890,
    "aud": "https://appleid.apple.com",
    "sub": "YOUR_SERVICE_ID"
  }

Method 2: Using Node.js (For Production)

Copyconst jwt = require('jsonwebtoken');
const fs = require('fs');
 
const privateKey = fs.readFileSync('path/to/AuthKey_XXXXXXXXXX.p8');
 
const token = jwt.sign(
  {
    iss: 'YOUR_TEAM_ID',
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 15777000, // 6 months
    aud: 'https://appleid.apple.com',
    sub: 'YOUR_SERVICE_ID',
  },
  privateKey,
  {
    algorithm: 'ES256',
    header: {
      kid: 'YOUR_KEY_ID',
    },
  }
);
 
console.log(token);

Important: The client secret is valid for a maximum of 6 months. You'll need to regenerate it periodically.

Step 6: Set Convex Environment Variables

Configure Environment Variables

You can set environment variables either via the Convex CLI or through the dashboard.

Option 1: Using Convex CLI (Recommended)

Open your terminal in your Convex application directory and run:

Copy# Set Apple Service ID (Client ID)
npx convex env set AUTH_APPLE_ID your_apple_service_id_here
 
# Set Apple Client Secret (JWT token)
npx convex env set AUTH_APPLE_SECRET your_generated_jwt_token_here

Option 2: Using Convex Dashboard

1. Open your Convex dashboard
2. Navigate to Settings > Environment Variables
3. Add the following variables:
   • Variable Name: AUTH_APPLE_ID, Value: Your Apple Service ID
   • Variable Name: AUTH_APPLE_SECRET, Value: Your generated JWT token

Note: Apple users can choose to share their name only on the first authentication. The profile configuration above ensures that if the user's name is shared initially, it gets stored and retained for future logins.

Common Issues and Solutions

"Invalid Client" Error

• Verify your Service ID is correctly configured
• Ensure the client secret JWT is properly formatted and signed
• Check that the Service ID matches exactly in both Apple Developer Console and environment variables

"Invalid Redirect URI"

• Verify your callback URL exactly matches: {HTTP_ACTIONS_URL}/api/auth/callback/apple
• Ensure you're using the production HTTP Actions URL (not localhost)
• Confirm the domain is properly configured in the Service ID settings

"Client Secret Expired"

• Apple client secrets expire after 6 months maximum
• Generate a new JWT token with updated timestamps
• Update your AUTH_APPLE_SECRET environment variable

"This App Hasn't Been Verified"

• Ensure your app is properly configured in Apple Developer Console
• For production apps, consider submitting for Apple review
• Verify all required fields are completed in your App ID configuration

SSL Certificate Issues

• Apple requires HTTPS for all production integrations
• Ensure your deployment URL uses a valid SSL certificate
• Test your SSL configuration using online SSL checkers

Security Best Practices

• Secure Key Storage: Store your .p8 private key securely and never commit it to version control
• Regular Secret Rotation: Regenerate your client secret every 6 months or sooner
• Environment Isolation: Use different Apple configurations for development, staging, and production
• Audit Trail: Monitor your Apple Developer Console for any suspicious activity
• Backup Keys: Keep secure backups of your private key files

Support

For additional help:

• Convex Auth Documentation
• Apple Sign in Documentation
• Apple Developer Support

Secure Apple authentication for your users! 🍎