MobileIdToken

MobileIdToken verifies Apple and Google OAuth id_token JWTs in mobile-first backend flows.

It validates JWT signature (RS256), issuer, audience, expiry, subject, nonce, and provider email-verification claims, with in-memory JWKS caching for key rotation.

Usage

Use MobileIdToken.verify/3 as the primary API.

Google example

case MobileIdToken.verify(:google, id_token,
       client_ids: ["your-google-client-id"],
       nonce: "optional-nonce"
     ) do
  {:ok, claims} ->
    claims

  {:error, reason} ->
    {:error, reason}
end

Apple example

case MobileIdToken.verify(:apple, id_token,
       client_ids: ["com.example.ios"],
       nonce: "expected-nonce"
     ) do
  {:ok, claims} ->
    claims

  {:error, reason} ->
    {:error, reason}
end

Real controller-style example

def apple(conn, %{"id_token" => id_token, "nonce" => nonce}) do
  case MobileIdToken.verify(:apple, id_token,
         client_ids: Application.get_env(:my_app, :apple_oauth_client_ids, []),
         nonce: nonce
       ) do
    {:ok, claims} ->
      json(conn, %{data: claims})

    {:error, :invalid_signature} ->
      send_resp(conn, 401, "Invalid token signature")

    {:error, :invalid_audience} ->
      send_resp(conn, 401, "Invalid client id")

    {:error, :token_expired} ->
      send_resp(conn, 401, "Token expired")

    {:error, :invalid_nonce} ->
      send_resp(conn, 401, "Invalid login nonce")

    {:error, :jwks_unavailable} ->
      send_resp(conn, 503, "Unable to verify token right now")

    {:error, reason} ->
      send_resp(conn, 422, Atom.to_string(reason))
  end
end

Why This Exists

Most Elixir OAuth libraries focus on server-side OAuth flows where your backend performs redirect/callback handling.

• ueberauth_* providers are great, but coupled to Ueberauth flow abstractions.
• Multi-provider frameworks (for example, broader OAuth/OIDC stacks) can be heavier than needed for mobile apps.

This package focuses on one problem:

• mobile client already completed provider auth
• backend only needs to verify the id_token safely

What It Does

• Fetches and caches provider JWKS (Apple/Google).
• Verifies RS256 signatures against kid selected JWK.
• Validates required claims (iss, aud, exp, sub).
• Validates provider email-verification claims.
• Validates nonce (with Apple hash-compatible behavior).
• Returns clear error atoms for HTTP mapping.

What It Does Not Do

• No redirect/callback OAuth flow orchestration.
• No provider SDK wrapper.
• No user creation/session issuance.
• No persistence layer.
• No Google hd (hosted domain) policy enforcement; enforce domain/org rules in host app.

This is a verification primitive you compose inside your own auth pipeline.

Installation

def deps do
  [
    {:mobile_id_token, "~> 0.1.0"}
  ]
end

API

• MobileIdToken.verify/3
• MobileIdToken.Apple.verify_id_token/2
• MobileIdToken.Google.verify_id_token/2

Return shape:

• {:ok, claims_map}
• {:error, reason_atom}

Options

• :client_ids - accepted aud values (["..."], "a,b", or "single").
• :nonce - expected nonce.

Audience validation behavior:

• aud string: must be one of the configured :client_ids.
• aud list: every audience in the token must be trusted (no extra untrusted values).
• If azp is present, it must be a trusted client ID.

Provider-specific nonce behavior:

• Google: optional (nil allowed), but if provided must be a non-empty string.
• Apple: required.

Client ID Configuration

The library intentionally does not read app environment variables directly.

Host apps must resolve config and pass :client_ids explicitly.

Example host convention (optional):

# config/runtime.exs
config :my_app, :google_oauth_client_ids,
  System.get_env("GOOGLE_OAUTH_CLIENT_IDS", "")
  |> String.split(",", trim: true)
  |> Enum.reject(&(&1 == ""))

config :my_app, :apple_oauth_client_ids,
  System.get_env("APPLE_OAUTH_CLIENT_IDS", "")
  |> String.split(",", trim: true)
  |> Enum.reject(&(&1 == ""))

Then pass them into verify/3 as shown in the controller example.

Nonce Matching Details

Nonce matching accepts either:

• exact plaintext nonce match
• lowercase SHA-256 hash of the expected nonce

This supports providers/SDKs that send hashed nonce claims (commonly seen in Apple flows).

JWKS Caching

JWKS are cached in :persistent_term for 600 seconds.

Verification flow:

1. read cached JWKS
2. select JWK by kid
3. if missing, force refresh once and retry
4. fail with :jwk_not_found or :jwks_unavailable

Current behavior note:

• stale cache + failed refresh returns :jwks_unavailable (library does not serve stale keys during refresh failures)

Error Atoms

• :invalid_token (malformed token / unsupported token input shape)
• :missing_kid
• :jwk_not_found
• :invalid_signature
• :invalid_issuer
• :missing_client_id
• :invalid_audience
• :token_expired
• :invalid_claims
• :email_not_verified
• :invalid_nonce
• :jwks_unavailable
• :unsupported_provider (only from MobileIdToken.verify/3)

Provider Notes

Google:

• accepted issuers: https://accounts.google.com, accounts.google.com
• requires non-empty email with truthy email_verified

Apple:

• issuer must be https://appleid.apple.com
• if email claim exists, email_verified must be truthy
• nonce is required by this package API

Multi-Audience Tokens

If a token's aud claim is an array, every value must be in :client_ids. This matches the OIDC Core §3.1.3.7 requirement to reject tokens that list audiences the client does not trust — not just tokens that omit the client's own ID.

When the azp (authorized party) claim is present, it must also be in :client_ids. It does not need to appear in the token's aud value.

In typical mobile sign-in flows aud is a single string (the app's bundle ID or OAuth client ID), while azp may identify another trusted client in the same app family.

Security Notes

• Always verify tokens server-side, never trust raw claims from the client.
• Keep client_ids scoped to your real app bundle/web client IDs.
• Treat :jwks_unavailable as temporary infrastructure failure (typically HTTP 503).
• Keep library versions current to pick up crypto/runtime fixes.