vestibule_apple

Apple Sign In strategy for vestibule.

Apple’s OAuth implementation has several key differences from standard providers:

• No userinfo endpoint: User info is extracted from the id_token JWT in the token response rather than from a separate API call.
• response_mode=form_post: Apple sends the callback as a POST with form data. The vestibule core handles extracting callback params, so this strategy just adds the parameter to the authorization URL.
• Client secret is a JWT: Apple requires the client_secret to be a signed JWT. Until this strategy supports a dedicated client assertion mode, the caller generates this JWT and provides it as config.ClientSecret(jwt). This strategy passes it through to the token endpoint.
• User info only on first auth: Apple only sends the full user object (with name) on the first authorization. Subsequent authorizations only include sub and email in the ID token.
• JWT signature verification: ID tokens are verified against Apple’s published JWKS keys using ES256.

Setup

Call vestibule_apple.try_init() once per VM at application startup to initialize caches, then use vestibule_apple.strategy() to create the strategy. Handle the error, or assert at the top level of your application where failing to start is the right outcome:

let assert Ok(apple) = vestibule_apple.try_init()
let strategy = vestibule_apple.strategy(apple)

Types

AppleCache

Holds the JWKS cache used for Apple ID token signature verification. Returned by try_init() and required by strategy(). Construction and field access are intentionally opaque so the cache backing store can change without breaking consumers.

pub type AppleCache

AppleInitError

Errors returned by checked Apple cache initialization.

pub type AppleInitError {
  JwksCacheInitFailed(jwks.JwksCacheError)
}

Functions

parse_token_response

Parse Apple token response JSON.

Apple’s token response includes an id_token JWT containing user claims. This function parses the response and returns standard credentials plus provider-specific artifacts such as the raw id_token.

pub fn parse_token_response(String) -> Result(strategy.ExchangeResult, error.AuthError(a))

strategy

Create an Apple Sign In authentication strategy.

Requires the cache handle from try_init(). Apple requires response_mode=form_post for the authorization URL, which is added automatically. The config.ClientSecret(jwt) value must be a signed JWT generated by the caller (see Apple’s documentation).

ID tokens are verified against Apple’s published JWKS keys with claim validation for issuer, audience, and expiration.

pub fn strategy(AppleCache) -> strategy.Strategy(a)

try_init

Try to initialize the Apple strategy’s caches.

Must be called once per VM at application startup before handling any authentication flows. Returns the cache handle needed by strategy(), or an error if the underlying cache tables already exist or cannot be created.

Example

let assert Ok(apple) = vestibule_apple.try_init()
let strategy = vestibule_apple.strategy(apple)

pub fn try_init() -> Result(AppleCache, AppleInitError)

try_init_named

Try to initialize named Apple strategy caches. Useful for tests that need isolated cache tables.

pub fn try_init_named(String) -> Result(AppleCache, AppleInitError)

verify_id_token

Verify and decode an Apple ID token JWT.

Fetches Apple’s JWKS public keys (cached), verifies the JWT signature using ES256, and validates the iss, aud, and exp claims.

Returns the user’s sub (uid) and UserInfo on success.

pub fn verify_id_token(
  jwt: String,
  keys: List(verify_key.VerifyKey),
  client_id: String
) -> Result(#(String, user_info.UserInfo), error.AuthError(a))