Configuring Apple Authentication

<Callout type={'warning'}> Apple Sign In requires a paid Apple Developer account ($99/year) and does not support localhost. You must use a domain with HTTPS for both development and production. </Callout>

1. Go to Apple Developer Portal
2. Navigate to Certificates, Identifiers & Profiles > Identifiers
3. Click + to register a new identifier
4. Select App IDs > App type > Continue
5. Fill in:
   • Description: e.g., LobeHub
   • Bundle ID: e.g., com.yourcompany.lobechat
6. Enable Sign In with Apple capability
7. Click Continue > Register

Create a Services ID

1. Go back to Identifiers, click +
2. Select Services IDs > Continue
3. Fill in:
   • Description: e.g., LobeHub Web
   • Identifier: e.g., com.yourcompany.lobechat.web (this is your Client ID)
4. Click Continue > Register

Configure Services ID

1. Click on the created Services ID
2. Enable Sign In with Apple
3. Click Configure
4. Select your Primary App ID
5. Add domains and callback URLs:
   • Domains: your-domain.com
   • Return URLs: https://your-domain.com/api/auth/callback/apple
6. Click Save > Continue > Save

<Callout type={'info'}> Callback URL format:

- Production: `https://your-domain.com/api/auth/callback/apple`
- Apple does **not** support localhost or HTTP URLs

Create a Sign In Key

1. Navigate to Keys, click +
2. Fill in key name
3. Enable Sign In with Apple, click Configure
4. Select your Primary App ID
5. Click Save > Continue > Register
6. Download the key file (.p8) - you can only download it once
7. Note down:
   • Key ID: shown on the key page
   • Team ID: shown in top right corner of developer portal

Generate Client Secret

Apple requires a JWT as the client secret. Generate it using your .p8 key file:

// Example using Node.js
const jwt = require('jsonwebtoken');
const fs = require('fs');

const privateKey = fs.readFileSync('AuthKey_XXXXX.p8');
const token = jwt.sign({}, privateKey, {
  algorithm: 'ES256',
  expiresIn: '180d', // Max 6 months
  issuer: 'YOUR_TEAM_ID',
  audience: 'https://appleid.apple.com',
  subject: 'YOUR_SERVICES_ID', // Client ID
  keyid: 'YOUR_KEY_ID',
});

<Callout type={'warning'}> The JWT expires after maximum 180 days. You need to regenerate and update it before expiration. </Callout>

Configure Environment Variables

<Callout type={'tip'}> Go to 📘 Environment Variables for detailed information. </Callout> </Steps>

<Callout type={'info'}> After successful deployment, users will be able to authenticate with Apple and use LobeHub. </Callout>

Common Issues

localhost Not Supported

Apple Sign In does not support localhost or non-HTTPS URLs. For local development, use a tunneling service like ngrok or deploy to a staging environment with HTTPS.

Secret Expiration

The JWT client secret expires after 180 days maximum. Set a reminder to regenerate it before expiration.

Related Resources

• Apple Developer Portal
• Sign In with Apple Documentation