Skip to main content

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 and the OpenID Connect Core 1.0 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 plugin and TV OAuth2 (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, 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.
  • 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 for more info.

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/SPA client.
  • Enable Authorization Code + PKCE.
  • Configure redirect URIs and allowed origins.
  • Provide scopes.
  • Applicaster apps are deployed on the server and could use a secret key, the secret should be set when deploying the web app.

Plugin setup

  • Configure client ID, redirect URI, issuer/discovery or manual endpoints.
  • Flow: browser redirects → user logs in → callback → exchange code → tokens stored (session/local storage).

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

Because of this, Roku integrations must use Applicaster’s 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.