# oauth2-integration-guide

# OAuth2 / OIDC

## Overview

This guide provides a comprehensive explanation of integrating an OAuth 2.0 / OpenID Connect (OIDC) authentication flow into applications using the Applicaster platform. OAuth 2.0 is a widely adopted framework for delegated authorization, and OIDC is an identity layer on top of it. For a deeper understanding, you can refer to the [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749) and the [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) specifications. The integration process varies across different platforms due to their unique constraints, including **Mobile, TV, Web, and Roku**.

---

## 1. General Concepts

- **OAuth2** is a framework for delegated authorization.
- **OIDC** extends OAuth2 with identity information (ID tokens).
- Applicaster apps use the [OAuth2 Login](https://docs.applicaster.com/using-zapp/auth/mobile-login#oauth2-plugin) plugin and [TV OAuth2](https://docs.applicaster.com/using-zapp/auth/tv-login#plugin) (or Login Flow for Roku) plugin to authenticate users, receive tokens, and make authenticated API calls.
- **PKCE (Proof Key for Code Exchange)** should always be enabled for public clients (Mobile, Web).
- Different flows are required depending on platform capabilities:
  - **Mobile/Web** → Authorization Code + PKCE
  - **TV** → Device Authorization Grant
  - **Roku** → Applicaster’s [Login Flow](https://docs.applicaster.com/integrations/auth/implementing-login-flow), which requires ROPC (Password flow) under the hood

---

## 2. Platform-Specific Guides

### 2.1 Mobile (iOS / Android)

**Authorization Service Setup**

- Register a **Native App** client.
- Enable **Authorization Code + PKCE** flow.
- Configure **Redirect URIs** — they must include the app URL scheme as described below.
- For iOS, use `<app_url_scheme>://oauth`. For example, if the app url scheme is `myapp` set `myapp://oauth`.
- For Android use `com.oauth2.<app_url_scheme>://oauth`, For example, if the app url scheme is `myapp` set `com.oauth2.myapp://oauth`.
> Troubleshooting: If you get a redirect URI mismatch error even when the plugin Redirect URL and authorization server settings look the same, add an additional allowed redirect URI with a trailing slash (/) in the authorization server (for example, keep both `myapp://oauth` and `myapp://oauth/`).
- Add required scopes (`openid`, `profile`, `email`, `offline`).
- Enable refresh tokens if long sessions are needed (usually setting `offline` scope enables refresh token, but this could vary between providers).

**Plugin setup**

- Add OAuth2 Login plugin in Zapp Studio.
- Provide `client_id`, `redirect_uri`, `issuer` or explicit endpoints (Authorization, Token, Revocation, etc).
- Configure scopes, storage key, optional extra params.
- Flow: App opens browser → user logs in → redirect URI → plugin exchanges code → tokens stored.

---

### 2.2 TV (Smart TV, Apple TV, Android TV)

**Authorization Service Setup**

- Enable **Device Authorization Grant** (device code flow).
- Register a **TV Client** with allowed scopes.
- Provide device authorization + token endpoints.

See Applicaster’s [Device Authorization Grant guide](https://docs.applicaster.com/integrations/auth/device-authorization-grant) for more info.

**Redirect URIs**

In case the authorization provider does not support the Device Authorization Grant (device flow), the Applicaster Device Flow proxy could be used in some cases — it implements the device code flow on top of your provider. Whether the proxy is a fit for your setup should be identified together with your CSM. When using the Applicaster Device Flow proxy, configure the following redirect URI in your authorization server:

- For the default Applicaster proxy: `https://login-flow.applicaster.com/api/oauth`
- If you were provided a dedicated subdomain: `https://<your domain>/api/oauth`

**Plugin setup**

- Configure client ID, device authorization endpoint, token endpoint and refresh endpoint in the layout used by the app.
- App calls device authorization → shows code + URL → user authorizes on another device → TV polls token endpoint → receives tokens.

**Notes**

- Must respect polling interval.
- Handle errors: `authorization_pending`, `slow_down`, `expired_token`.

---

### 2.3 Web

**Provider-side setup**

- Register a **Web client**. Most web clients are **public** and authenticate with PKCE only (no secret). If your provider requires a **confidential (private) client** with a client secret, the Applicaster web app can support it because it runs the token exchange on the server — see [Using a client secret](#using-a-client-secret-server-side) below.
- Enable Authorization Code + PKCE.
- Configure redirect URIs and allowed origins. Add `https://<your domain>/api/oauth` to your allowed redirect URIs (this is the callback the web app uses).
- For Zapp Preview builds, add `https://oauth2-preview-proxy.vercel.app/callback` to your allowed redirect URIs.
- Provide scopes.

**Plugin setup**

- Configure client ID, redirect URI, issuer/discovery or manual endpoints, and scopes.
- Optional toggles:
  - **Use PKCE** (`usePKCE`, default on) — keep on for public/web clients; only turn off for providers that don't support PKCE.
  - **Use basic authentication header** (`useBasicAuthenticationHeader`, default on) — controls how the client secret is sent (see below).
  - **Extract Token Claims to Storage** — exposes JWT claims as Context Keys.
  - **Additional Parameters** — extra params added to the authorization request (JSON).
- Flow: browser redirects → user logs in → callback (`/api/oauth`) → server exchanges code → tokens stored.

#### Using a client secret (server-side)

This is **optional** — only needed when your provider requires a confidential (private) client with a client secret. Since the web app is deployed on the server, the secret stays server-side. Do not put the secret in the plugin/layout configuration — provide it at deploy time:

- Set the **`OAUTH2_CLIENT_SECRET_OVERRIDE`** environment variable when deploying the web app. This value overrides the plugin's `clientSecret` and is used for both the authorization-code exchange and the token-refresh requests. For Applicaster-hosted deployments it is supplied via the SOPS-encrypted `variables.json`.
- When using a client secret, **disable "Use basic authentication header"** (`useBasicAuthenticationHeader`) in the plugin so the secret is sent as `client_secret` in the request body. Leave it enabled only if your authorization server specifically requires HTTP Basic authentication, in which case the secret is sent as `Authorization: Basic base64(client_id:client_secret)`.

---

### 2.4 Roku

Roku devices impose strict certification requirements: **all account sign‑ups and sign‑ins must occur entirely on the device itself**, with **no external webpages, links, or off-device login flows** allowed. ([Roku Developer Guide](https://developer.roku.com/docs/developer-program/authentication/on-device-authentication.md)).

Because of this, Roku integrations **must use Applicaster’s [Login Flow](https://docs.applicaster.com/integrations/auth/implementing-login-flow)**, which leverages the Resource Owner Password Credentials (ROPC) grant under the hood.

#### Provider-side setup (Roku)

- Enable **ROPC grant** in your OAuth2/OIDC provider (required for Roku).
- Register a dedicated Roku client with minimal scopes (e.g. `openid`, `profile`).
- Ensure your token endpoint accepts `grant_type=password` requests.

#### Plugin setup (Roku)

- In Zapp Studio, configure the **Login Flow plugin**.
- Provide:
  - Client ID (Roku client)
  - Token endpoint URL

#### Flow (Roku with Login Flow)

1. Roku app presents an on-device login form.
2. User enters username + password.
3. Tokens (access, refresh, ID) are returned and stored locally.
4. Logout clears tokens and optionally calls revocation endpoint.

#### Why Login Flow Is Required

- Roku mandates **on-device registration and authentication** for certification.
- Applicaster’s Login Flow plugin ensures compliance while maintaining integration with OAuth2/OIDC backends.
- This is the only supported method for Roku integrations.

---

## 3. Best Practices

- Redirect URIs must match exactly.
- Always use PKCE for public clients.
- Implement token refresh handling.
- Clear tokens properly on logout.
- For Roku: use Login Flow to comply with Roku’s **on-device registration requirement**.