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 parameters, 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 RS256.

Setup

Call vestibule_apple.initialize() 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.initialize()
let strategy = vestibule_apple.strategy(apple)

Types

AppleCache

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

pub type AppleCache

AppleInitializationError

Errors returned by checked Apple cache initialization.

pub type AppleInitializationError {
  JwksCacheInitializationFailed(jwks.JwksCacheError)
}

Functions

build_authorization_code_request

Build Apple’s authorization-code token request without sending it.

pub fn build_authorization_code_request(
  config.ClientConfig,
  String,
  option.Option(String)
) -> Result(request.Request(String), error.AuthError(a))

build_refresh_token_request

Build Apple’s refresh-token request without sending it.

pub fn build_refresh_token_request(
  config.ClientConfig,
  String
) -> Result(request.Request(String), error.AuthError(a))

initialize

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.initialize()
let strategy = vestibule_apple.strategy(apple)

pub fn initialize() -> Result(AppleCache, AppleInitializationError)

initialize_named

Initialize named Apple strategy caches. Useful for tests that need isolated cache tables.

pub fn initialize_named(String) -> Result(AppleCache, AppleInitializationError)

parse_authorization_code_response

Parse Apple’s authorization-code HTTP response without performing I/O.

pub fn parse_authorization_code_response(response.Response(String)) -> Result(strategy.ExchangeResult, error.AuthError(a))

parse_refresh_token_response

Parse Apple’s refresh-token HTTP response without performing I/O.

pub fn parse_refresh_token_response(response.Response(String)) -> Result(credential.Credentials, error.AuthError(a))

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 initialize(). 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)

verify_id_token

Verify and decode an Apple ID token JWT.

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

Returns the user’s sub (user ID) 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))