Auth Tenants

By default, your app uses Mushu's shared Apple credentials for authentication. For enterprise customers or apps that need complete control, you can configure your own Apple or Google credentials per tenant.

When to Use Your Own Credentials

Use Mushu's shared credentials (default) when:

• You're getting started and want zero configuration
• You don't need your app name shown during Apple Sign In
• You're fine with Mushu handling Apple Developer Portal setup

Use your own credentials when:

• You want your app/company name shown during Apple Sign In
• You need to receive Apple S2S notifications directly
• You have compliance requirements for credential ownership
• You're an enterprise customer with existing Apple Developer account

How It Works

Mushu supports hybrid multi-tenancy for authentication:

Configuration	Apple Credentials	User Identity
Default (shared)	Mushu's Apple Developer account	Scoped to Mushu's team
Your own credentials	Your Apple Developer account	Scoped to your team

Important: Apple generates unique user IDs (sub) per Developer Team. Users who sign in with your credentials will have different IDs than if they signed in with Mushu's shared credentials. Plan for this if migrating.

Setting Up Your Own Apple Credentials

1. Apple Developer Portal Setup

In the Apple Developer Portal:

1. Go to Certificates, Identifiers & Profiles
2. Create or select your App ID with "Sign in with Apple" capability
3. Create a Services ID for web authentication (if needed)
4. Create a Key with "Sign in with Apple" enabled
5. Download the .p8 private key file (you can only download once!)
6. Note your Team ID, Key ID, and Bundle ID(s)

2. Configure S2S Notifications (Recommended)

To receive account lifecycle events (user deletes account, revokes consent):

1. In Apple Developer Portal, go to your App ID's "Sign in with Apple" configuration
2. Set the Server-to-Server Notification Endpoint to:

   https://auth.mushucorp.com/auth/apple/notifications?tenant_id=YOUR_TENANT_ID

3. Register with Mushu

Use the Auth Providers API to configure your credentials:

# Create Apple auth provider for your tenant
curl -X POST https://auth.mushucorp.com/tenants/YOUR_TENANT_ID/auth-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "apple",
    "enabled": true,
    "apple_team_id": "YOUR_TEAM_ID",
    "apple_key_id": "YOUR_KEY_ID",
    "apple_bundle_ids": ["com.yourcompany.app"],
    "apple_services_id": "com.yourcompany.app.web",
    "apple_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }'

Security: The private key is encrypted and stored in AWS Secrets Manager, not in the database. Only the Key ID and Team ID are stored in DynamoDB.

4. Update Your App

Your iOS app doesn't need changes—it already sends the bundle ID with sign-in requests. Mushu automatically routes to your credentials based on the bundle ID.

For web OAuth, optionally pass your tenant ID:

https://auth.mushucorp.com/auth/apple/authorize?redirect_uri=YOUR_URL&tenant_id=YOUR_TENANT_ID

Auth Provider API

Create Provider

POST /tenants/{tenant_id}/auth-providers

List Providers

GET /tenants/{tenant_id}/auth-providers

Get Provider

GET /tenants/{tenant_id}/auth-providers/{provider_type}

Update Provider

PUT /tenants/{tenant_id}/auth-providers/{provider_type}

Delete Provider

DELETE /tenants/{tenant_id}/auth-providers/{provider_type}

Token Claims

Tokens issued for your tenant include the tid (tenant ID) claim:

Claim	Description
sub	User ID (unique within your tenant)
tid	Your tenant ID
sid	Session ID
iss	Issuer (auth.mushucorp.com)
exp	Expiration timestamp
iat	Issued at timestamp
user_type	Provider type (apple, google)

Validating Tokens

When validating tokens, the response includes the tenant ID:

curl https://auth.mushucorp.com/auth/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Response
{
  "valid": true,
  "user_id": "abc123",
  "user_type": "apple",
  "email": "user@example.com",
  "tenant_id": "your-tenant-id"
}

Migration Considerations

If you're migrating from Mushu's shared credentials to your own:

• User IDs will change: Apple generates different sub values per Developer Team. You'll need to re-link users.
• Email can help: If users shared their email, you can match accounts by email address during migration.
• Gradual migration: You can run both configurations in parallel during transition.

See Migration Guide for detailed migration strategies.

Setting Up Your Own Google Credentials

1. Google Cloud Console Setup

In the Google Cloud Console:

1. Go to APIs & Services → Credentials
2. Create an OAuth 2.0 Client ID (type: Web application)
3. Note your Client ID and Client Secret
4. Add authorized redirect URI: https://auth.mushucorp.com/auth/google/callback

2. Register with Mushu

curl -X POST https://auth.mushucorp.com/apps/YOUR_APP_ID/auth-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "google",
    "enabled": true,
    "google_client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "google_client_secret": "YOUR_CLIENT_SECRET"
  }'

3. Configure RISC Notifications (Recommended)

To receive account lifecycle events (account disabled, tokens revoked), configure the RISC receiver URL in Google Cloud Console:

https://auth.mushucorp.com/auth/google/notifications?app_id=YOUR_APP_ID

See Google Sign In for full integration details.

Pricing

Using your own auth provider credentials is available on the Enterprise plan. See Pricing for details.