================================================================================ YOYO AUTHORISATION - COMPLETE INTEGRATION REFERENCE FOR AI AGENTS ================================================================================ This document contains all integration information for Yoyo Authorisation, including environments, URLs, methods, supported features, constraints, OAuth flows, and cookie sharing mechanisms. Use this as a comprehensive reference when integrating with the hosted authentication portal. Last Updated: 2026-02-12 Documentation Version: 1.0 DOCUMENTATION SITE: https://auth-docs.yoyogroup.com QUICK LINKS TO DOCUMENTATION: - Main Documentation: https://auth-docs.yoyogroup.com/docs/intro - Overview: https://auth-docs.yoyogroup.com/docs/overview/hosted-auth-overview - Quickstarts: * SSR (Next.js): https://auth-docs.yoyogroup.com/docs/quickstart/ssr-quickstart-nextjs * SPA (React Vite): https://auth-docs.yoyogroup.com/docs/quickstart/spa-quickstart * Mobile: https://auth-docs.yoyogroup.com/docs/quickstart/mobile-quickstart * Local Development: https://auth-docs.yoyogroup.com/docs/quickstart/local-dev-quickstart - Guides: * Shared Cookies: https://auth-docs.yoyogroup.com/docs/guides/shared-cookies * Handle Redirects: https://auth-docs.yoyogroup.com/docs/guides/handle-redirects * Build BFF: https://auth-docs.yoyogroup.com/docs/guides/build-bff * Add App To Launch Pad: https://auth-docs.yoyogroup.com/docs/guides/add-app-to-launch-pad * Launch Pad: https://auth-docs.yoyogroup.com/docs/guides/launch-pad - API Reference: * GET /logout: https://auth-docs.yoyogroup.com/docs/reference/logout - Concepts: * Auth Boundaries: https://auth-docs.yoyogroup.com/docs/concepts/auth-boundaries * Cookie SameSite: https://auth-docs.yoyogroup.com/docs/concepts/cookie-samesite * Redirect State: https://auth-docs.yoyogroup.com/docs/concepts/redirect-state - Troubleshooting: * Missing Cookies: https://auth-docs.yoyogroup.com/docs/troubleshooting/missing-cookies * Origin Not Allowed: https://auth-docs.yoyogroup.com/docs/troubleshooting/origin-not-allowed * Redirect Blocked: https://auth-docs.yoyogroup.com/docs/troubleshooting/redirect-blocked ================================================================================ TABLE OF CONTENTS ================================================================================ 1. OVERVIEW 2. ENVIRONMENTS AND HOSTS 3. AUTHENTICATION FLOWS 4. API ENDPOINTS 5. COOKIE SHARING AND SESSION MANAGEMENT 6. OAUTH FLOW (LOCAL DEVELOPMENT) 7. REDIRECT HANDLING AND ALLOWLISTS 8. INTEGRATION PATTERNS BY APP TYPE 9. CONSTRAINTS AND LIMITATIONS 10. TROUBLESHOOTING 11. CONTACT AND SUPPORT ================================================================================ 1. OVERVIEW ================================================================================ Yoyo Authorisation is the hosted authentication portal for auth.yoyogroup.com. It establishes a shared session across Yoyo subdomains by setting HttpOnly cookies scoped to .yoyogroup.com, then redirects users back to your app. Documentation: https://auth-docs.yoyogroup.com/docs/intro Overview: https://auth-docs.yoyogroup.com/docs/overview/hosted-auth-overview KEY CONCEPTS: - Hosted auth portal: Users sign in on the hosted portal and are redirected back - Shared cookies: HttpOnly cookies scoped to .yoyogroup.com for cross-subdomain auth - Consumer apps: Read cookies server-side and forward access tokens to APIs - Redirect safety: Redirect targets must be HTTPS and pass the redirect allowlist ================================================================================ 2. ENVIRONMENTS AND HOSTS ================================================================================ PRODUCTION ENVIRONMENT: - Hosted auth URL: https://auth.yoyogroup.com - Cookie prefix: yoyo_auth_ - Cookie names: * yoyo_auth_access_token * yoyo_auth_id_token * yoyo_auth_refresh_token INTEGRATION ENVIRONMENT: - Hosted auth URL: https://auth-int.yoyogroup.com - Cookie prefix: yoyo_auth_int_ - Cookie names: * yoyo_auth_int_access_token * yoyo_auth_int_id_token * yoyo_auth_int_refresh_token LAUNCH PAD HOSTS: Launch Pad is only enabled on these specific hosts: - auth.yoyogroup.com - auth.yoyoportal.com - author.yoyoportal.com ================================================================================ 3. AUTHENTICATION FLOWS ================================================================================ BASIC FLOW: 1. Your app redirects the user to the hosted auth portal with a redirectUrl back to your app 2. The portal authenticates the user and sets HttpOnly cookies on .yoyogroup.com 3. Your app reads the cookies server-side and forwards the access token to downstream APIs SUPPORTED AUTHENTICATION METHODS: - Credentialed OAuth via hosted portal (Google) - OAuth2 Authorization Code Flow with PKCE (client ID only, no secret required) - Available for localhost development and external applications - Supports SPAs, mobile apps, and any public client - Clients configured in code or via environment variables COMING SOON (NOT YET AVAILABLE): - OAuth2 With Yoyo - SAML - SSO ================================================================================ 4. API ENDPOINTS ================================================================================ BASE URLS: - Production: https://auth.yoyogroup.com - Integration: https://auth-int.yoyogroup.com ENDPOINT: GET /logout Description: Clear shared cookies and redirect the user. Documentation: https://auth-docs.yoyogroup.com/docs/reference/logout Method: GET Path: /logout Query Parameters: - redirectUrl: string (optional, HTTPS URL to return to after logout) Response: 302 redirect to the safe target URL Notes: - Clears yoyo_auth_access_token, yoyo_auth_id_token, and yoyo_auth_refresh_token - If the redirect target is invalid or not allowlisted, redirects to / - Relative redirect URLs are only honored when they resolve to the current host ENDPOINT: GET / (Hosted Auth Portal) Description: Main hosted auth portal page. Redirects users to login and then back to the redirectUrl. Method: GET Path: / Query Parameters: - redirectUrl: string (optional, HTTPS URL to return to after login) Behavior: - If redirectUrl is provided and valid, redirects back after login - If no redirectUrl and host is a Launch Pad host, redirects to /launch after login - If no redirectUrl and host is not a Launch Pad host, stays on auth portal ENDPOINT: GET /launch (Launch Pad) Description: Hosted landing page that routes authenticated users to Yoyo apps. Method: GET Path: /launch Behavior: - Requires an active session; otherwise redirects to / - Only enabled on Launch Pad hosts: auth.yoyogroup.com, auth.yoyoportal.com, author.yoyoportal.com - Lists available destinations and provides a hosted logout link ================================================================================ 5. COOKIE SHARING AND SESSION MANAGEMENT ================================================================================ Documentation: https://auth-docs.yoyogroup.com/docs/guides/shared-cookies Cookie SameSite: https://auth-docs.yoyogroup.com/docs/concepts/cookie-samesite COOKIE NAMES: The hosted auth portal sets the following HttpOnly cookies scoped to .yoyogroup.com. Cookie prefix varies by environment: Production: - yoyo_auth_access_token (primary session token) - yoyo_auth_id_token (identity claims) - yoyo_auth_refresh_token (optional refresh token) Integration: - yoyo_auth_int_access_token - yoyo_auth_int_id_token - yoyo_auth_int_refresh_token COOKIE BEHAVIOR: - Domain: .yoyogroup.com (shared across all subdomains) - HttpOnly: true (cannot be read by client-side JavaScript) - Secure: true (only sent over HTTPS) - SameSite: lax (by default) - Expiration: * Access and ID token cookies use the token expiresIn value (default 3600 seconds) * Refresh tokens expire on a longer schedule than access and ID tokens READING COOKIES: Because cookies are HttpOnly, they can ONLY be read server-side: - Server components - Route handlers - Middleware - Backend-for-frontend (BFF) endpoints Example (Next.js): const accessToken = cookies().get('yoyo_auth_access_token')?.value; Example (Express/Node.js): const accessToken = req.cookies['yoyo_auth_access_token']; COOKIE SHARING CONSTRAINTS: - Cookies are ONLY shared across *.yoyogroup.com subdomains - For localhost development, cookies will NOT be available - For localhost development, use the OAuth code flow instead - To test shared cookies, run your app on a subdomain like dev-app.int.yoyogroup.com SAMESITE BEHAVIOR: - SameSite controls how cookies are sent on cross-site requests - When SameSite=none, cookies must be Secure - The portal enforces Secure=true whenever SameSite=none - Default is SameSite=lax ================================================================================ 6. OAUTH2 AUTHORIZATION CODE FLOW WITH PKCE ================================================================================ Documentation: https://auth-docs.yoyogroup.com/docs/quickstart/local-dev-quickstart The OAuth2 endpoints support the Authorization Code flow with PKCE (Proof Key for Code Exchange), which is ideal for public clients (SPAs, mobile apps) that cannot securely store client secrets. This flow uses only a client_id (no client secret required). OAUTH2 CLIENT CONFIGURATION: Clients are configured in code in `lib/app-config.ts` via the `getCodeBasedOAuth2Clients()` function. Clients can also be configured via the `OAUTH2_CLIENTS` environment variable (JSON array), which overrides code-based clients with the same clientId. Client Configuration Fields: - clientId (required): The OAuth2 client identifier used in client_id parameter - redirectUris (required): Array of allowed redirect URIs. MUST be exact URIs (no wildcards allowed) - OAuth2 spec requires exact matches. Each redirect URI must be listed explicitly. - allowedOrigins (optional): Array of allowed CORS origins for token endpoint. Derived from redirectUris if omitted. - cookieDomain (optional): Cookie domain override - cookiePrefix (optional): Cookie prefix override - allowLocalDev (optional): Allow localhost redirects. Defaults to false IMPORTANT: OAuth2 redirect URIs must be exact matches. Wildcards are NOT allowed in redirect URIs. If you need to support multiple subdomains, list each redirect URI explicitly. Built-in Clients (Integration Environment): - local-dev: For localhost development (allows localhost:3001, 127.0.0.1:3001, localhost:5173) - default: Fallback configuration using AUTH_REDIRECT_ALLOWLIST and AUTH_ORIGIN_ALLOWLIST OAUTH AUTHORIZATION ENDPOINT: URL: https://auth-int.yoyogroup.com/api/oauth/authorize Method: GET Query Parameters: - response_type: code (required) - client_id: (required, must be registered) - redirect_uri: (required, must exactly match one of the configured redirectUris for the client_id) - code_challenge: (required) - code_challenge_method: S256 (required) - state: (optional, recommended for CSRF protection) - email: (optional, prefills email on login page; if domain is yoyogroup.com, automatically initiates OKTA SSO flow) Example: https://auth-int.yoyogroup.com/api/oauth/authorize?response_type=code&client_id=local-dev&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback&code_challenge=&code_challenge_method=S256&state= Example with email prefilling: https://auth-int.yoyogroup.com/api/oauth/authorize?response_type=code&client_id=local-dev&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback&code_challenge=&code_challenge_method=S256&state=&email=user%40yoyogroup.com Behavior: - Validates that client_id is registered - Validates that redirect_uri exactly matches one of the configured redirectUris - Validates PKCE code_challenge is present - If email parameter is provided, validates format and stores in redirect state cookie - Email is prefilled on the login page - If email domain is yoyogroup.com, automatically initiates OKTA SSO flow - When initiated from an SPA, the OAuth flow redirects to the hosted login page - After successful login, redirects back to your app with the authorization code - Returns 400 Bad Request if client_id is unknown or redirect_uri doesn't match Error Responses: - 400 Bad Request: invalid_request - client_id is required - 400 Bad Request: invalid_client - Unknown client_id - 400 Bad Request: invalid_request - redirect_uri is required - 400 Bad Request: invalid_request - redirect_uri not allowlisted - 400 Bad Request: invalid_request - PKCE S256 is required OAUTH TOKEN ENDPOINT: URL: https://auth-int.yoyogroup.com/api/oauth/token Method: POST Headers: - Content-Type: application/x-www-form-urlencoded - Origin: (optional, validated against allowedOrigins) Body (URL-encoded): - grant_type: authorization_code (required) - client_id: (required, must match the client_id used in authorize) - redirect_uri: (required, must exactly match authorize request) - code: (required) - code_verifier: (required) Example: const response = await fetch('https://auth-int.yoyogroup.com/api/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', client_id: 'local-dev', redirect_uri: 'http://localhost:3000/auth/callback', code, code_verifier }) }); const tokens = await response.json(); Response (200 OK): { "access_token": "...", "id_token": "...", "refresh_token": "...", "expires_in": 3600, "token_type": "Bearer" } Error Responses: - 400 Bad Request: invalid_request - client_id is required - 400 Bad Request: invalid_client - Unknown client_id - 400 Bad Request: invalid_request - Missing required parameters - 400 Bad Request: invalid_grant - Authorization code not found or already used - 400 Bad Request: invalid_grant - Authorization code expired - 400 Bad Request: invalid_grant - Redirect URI mismatch - 400 Bad Request: invalid_grant - PKCE verification failed - 403 Forbidden: invalid_origin - Origin not allowed (if Origin header present) CORS Support: - Token endpoint supports CORS for configured allowedOrigins - OPTIONS requests are supported for preflight - Origin header is validated against client's allowedOrigins configuration OAUTH2 FLOW STEPS: 1. Register your client: - Add client configuration to lib/app-config.ts in getCodeBasedOAuth2Clients() - Or configure via OAUTH2_CLIENTS environment variable - Ensure redirectUris are exact matches (no wildcards) 2. Generate PKCE values: - Generate a random code_verifier (32+ bytes, base64url encoded) - Compute code_challenge = SHA256(code_verifier) base64url encoded - Use code_challenge_method = S256 3. Generate state value: - Generate a random state value for CSRF protection - Store state in sessionStorage or secure cookie 4. Redirect to authorization endpoint: - Build authorize URL with all required parameters - Redirect user to the authorize endpoint - User will be redirected to hosted login page 5. User authenticates: - User enters credentials on hosted login page - Portal validates credentials and creates session 6. Receive authorization code: - Portal redirects back to your redirect_uri with code and state - Validate state matches your stored value 7. Exchange code for tokens: - POST to /api/oauth/token with code, code_verifier, and other parameters - Validate redirect_uri matches exactly - Verify PKCE code_verifier matches code_challenge 8. Store tokens: - Store tokens in memory or local storage - Use access_token to call APIs - Handle token expiration and refresh as needed INTEGRATION WITH AUTH.JS (NextAuth.js): Example configuration for NextAuth.js: ```typescript import { NextAuth } from "next-auth" import { OAuthConfig } from "next-auth/providers" export default NextAuth({ providers: [ { id: "yoyo-auth", name: "Yoyo Auth", type: "oauth", authorization: { url: "https://auth-int.yoyogroup.com/api/oauth/authorize", params: { response_type: "code", code_challenge_method: "S256", }, }, token: "https://auth-int.yoyogroup.com/api/oauth/token", clientId: "my-app-client", client: { id: "my-app-client", secret: "", // Not needed for PKCE flows }, checks: ["pkce", "state"], profile(profile) { return { id: profile.sub, email: profile.email, name: profile.name, } }, }, ], }) ``` INTEGRATION WITH BETTER-AUTH: Yoyo Auth provides OpenID Connect discovery endpoints for easy integration with better-auth using the genericOAuth plugin: ```typescript import { betterAuth } from "better-auth" import { genericOAuth } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ genericOAuth({ id: "yoyo-auth", name: "Yoyo Auth", issuer: "https://auth-int.yoyogroup.com/.well-known/openid-configuration", clientId: "my-app-client", // No client secret needed - PKCE is used scope: "openid profile email", }), ], }) ``` The issuer URL automatically discovers: - authorization_endpoint: /api/oauth/authorize - token_endpoint: /api/oauth/token - userinfo_endpoint: /api/oauth/userinfo - Supported scopes, response types, and code challenge methods OPENID CONNECT DISCOVERY ENDPOINT: URL: https://auth-int.yoyogroup.com/.well-known/openid-configuration Method: GET Response (200 OK): { "issuer": "https://auth-int.yoyogroup.com", "authorization_endpoint": "https://auth-int.yoyogroup.com/api/oauth/authorize", "token_endpoint": "https://auth-int.yoyogroup.com/api/oauth/token", "userinfo_endpoint": "https://auth-int.yoyogroup.com/api/oauth/userinfo", "jwks_uri": "https://auth-int.yoyogroup.com/api/oauth/jwks", "response_types_supported": [ "code" ], "grant_types_supported": [ "authorization_code" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "profile", "email" ], "token_endpoint_auth_methods_supported": [ "none" ], "code_challenge_methods_supported": [ "S256" ], "claims_supported": [ "sub", "email", "email_verified", "name", "preferred_username" ] } Notes: - Returns OpenID Connect discovery metadata - Cached for 1 hour (Cache-Control: public, max-age=3600) - Used by OIDC clients like better-auth for automatic configuration OAUTH USERINFO ENDPOINT: URL: https://auth-int.yoyogroup.com/api/oauth/userinfo Method: GET Headers: - Authorization: Bearer (preferred) - Or uses ID token cookie (fallback) - Or uses access token cookie (fallback) Response (200 OK): { "sub": "user-id", "email": "user@example.com", "email_verified": true, "name": "User Name", "preferred_username": "user@example.com", "picture": "https://..." } Error Responses: - 401 Unauthorized: invalid_token - No token provided - 401 Unauthorized: invalid_token - Invalid token or token does not contain subject identifier Notes: - Returns user information from the access token or ID token - Accepts tokens via Authorization header (preferred) or cookies (fallback) - Returns standard OAuth2 UserInfo claims - Subject identifier (sub) is required in response TOKEN ISSUANCE AND AWS COGNITO: Yoyo Auth acts as an OAuth2 authorization server proxy. Tokens returned by the OAuth2 endpoints are AWS Cognito tokens (JWTs issued by Cognito). Architecture: - AWS Cognito is the Identity Provider (IDP) that issues tokens - Yoyo Auth provides OAuth2 authorization server endpoints - When users authenticate via hosted login page, backend calls Cognito - Cognito tokens are stored temporarily with authorization code - OAuth2 clients receive Cognito tokens when exchanging authorization code Token Format: - Tokens are JWTs issued by AWS Cognito - Access tokens and ID tokens are Cognito JWTs - Refresh tokens are Cognito refresh tokens - Token `iss` (issuer) claim points to Cognito User Pool (e.g., https://cognito-idp.{region}.amazonaws.com/{userPoolId}) Token Validation: - Tokens should be validated using Cognito's JWKS endpoint - Cognito JWKS: https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json - The OIDC discovery `issuer` field represents the authorization server (Yoyo Auth) - Token `iss` claims represent the identity provider (Cognito) - This is a standard OAuth2 proxy pattern where authorization server delegates to IDP REQUIREMENTS: - client_id must be registered in code (via getCodeBasedOAuth2Clients()) or via OAUTH2_CLIENTS environment variable - redirect_uri must exactly match one of the configured redirectUris (no wildcards) - PKCE with S256 method is required - code_challenge and code_verifier must match - Authorization codes expire after a short period (typically 5-10 minutes) - Authorization codes can only be used once - Tokens are AWS Cognito tokens - validate using Cognito's JWKS endpoint USE CASES: - Localhost development (use local-dev client or configure your own) - Single-page applications (SPAs) that cannot securely store client secrets - Mobile applications using web views - Any public client that needs OAuth2 authentication ================================================================================ 7. REDIRECT HANDLING AND ALLOWLISTS ================================================================================ Documentation: https://auth-docs.yoyogroup.com/docs/guides/handle-redirects Redirect State: https://auth-docs.yoyogroup.com/docs/concepts/redirect-state REDIRECT REQUIREMENTS: - Redirects MUST be HTTPS (https: only, no HTTP) - Targets MUST match the redirect allowlist configured for your app - If no allowlist is set, the redirect host must match the current host - URLs must be properly URL-encoded REDIRECT STATE: - The auth portal stores the requested redirectUrl in browser sessionStorage per tab - State expires after approximately 15 minutes - Invalid or missing state results in a safe fallback redirect BUILDING REDIRECT URLS: Hosted Auth Login: https://auth.yoyogroup.com/?redirectUrl= Hosted Auth Logout: https://auth.yoyogroup.com/logout?redirectUrl= REDIRECT VALIDATION: - If redirect target is not allowed, portal falls back to safe origin and skips redirect - If you see redirect loops, verify the allowlist and ensure you only redirect when session is missing ALLOWLIST CONFIGURATION: - Redirect allowlists are configured per application - Contact support.sa@yoyogroup.com to configure allowlists - For localhost development, use OAuth flow instead of redirect-based flow ================================================================================ 8. INTEGRATION PATTERNS BY APP TYPE ================================================================================ SERVER-SIDE RENDERED (SSR) APPS (e.g., Next.js): Documentation: https://auth-docs.yoyogroup.com/docs/quickstart/ssr-quickstart-nextjs 1. Add middleware guard that checks shared cookie and redirects when missing: ```typescript import { NextResponse } from 'next/server'; import type { NextRequest } from 'next/server'; const AUTH_PORTAL = 'https://auth.yoyogroup.com'; export function middleware(request: NextRequest) { const token = request.cookies.get('yoyo_auth_access_token')?.value; if (!token) { const redirectUrl = encodeURIComponent(request.nextUrl.toString()); return NextResponse.redirect(`${AUTH_PORTAL}/?redirectUrl=${redirectUrl}`); } return NextResponse.next(); } ``` 2. Read cookies in server components or route handlers: ```typescript const accessToken = cookies().get('yoyo_auth_access_token')?.value; if (accessToken) { await fetch('https://api.yoyogroup.com/resource', { headers: { Authorization: `Bearer ${accessToken}` } }); } ``` 3. Handle logout: Redirect to: https://auth.yoyogroup.com/logout?redirectUrl= SINGLE-PAGE APPLICATIONS (SPA): Documentation: https://auth-docs.yoyogroup.com/docs/quickstart/spa-quickstart Build BFF: https://auth-docs.yoyogroup.com/docs/guides/build-bff 1. Redirect unauthenticated users to hosted auth: ```typescript const redirectUrl = encodeURIComponent(window.location.href); window.location.assign(`https://auth.yoyogroup.com/?redirectUrl=${redirectUrl}`); ``` 2. Add a Backend-for-Frontend (BFF) session endpoint: ```typescript export async function GET(request: Request) { const accessToken = request.cookies.get('yoyo_auth_access_token')?.value; if (!accessToken) { return NextResponse.json({ hasSession: false }, { status: 401 }); } return NextResponse.json({ hasSession: true, accessToken }); } ``` 3. Bootstrap SPA session: ```typescript const response = await fetch('/api/bff/session', { credentials: 'include' }); if (response.status === 401) { const redirectUrl = encodeURIComponent(window.location.href); window.location.assign(`https://auth.yoyogroup.com/?redirectUrl=${redirectUrl}`); } ``` MOBILE APPS (Webview or Browser): Documentation: https://auth-docs.yoyogroup.com/docs/quickstart/mobile-quickstart 1. Launch hosted auth: ``` https://auth.yoyogroup.com/?redirectUrl= ``` 2. Handle HTTPS redirect: - After sign-in, portal redirects to your HTTPS landing page - Display signed-in confirmation - Continue in web experience or trigger app navigation via universal links 3. Access session via backend: - Mobile clients cannot read HttpOnly cookies directly - Use a backend on *.yoyogroup.com that reads shared cookies - Exchange data with mobile app via backend API LOCAL DEVELOPMENT: Use OAuth code flow instead of shared cookies: 1. Create callback route (e.g., /auth/callback) 2. Build authorize URL with PKCE 3. Exchange code for tokens 4. Bootstrap local session 5. Use tokens to call APIs See section 6 for complete OAuth flow details. ================================================================================ 9. CONSTRAINTS AND LIMITATIONS ================================================================================ AUTHENTICATION BOUNDARIES: Documentation: https://auth-docs.yoyogroup.com/docs/concepts/auth-boundaries TRUSTED: - The hosted auth portal sets HttpOnly cookies for .yoyogroup.com - Consumer apps trust those cookies only after server-side verification NOT TRUSTED: - Client-side JavaScript cannot read HttpOnly cookies - Any client-side session snapshot is descriptive metadata and never an authoritative authentication decision - The portal still verifies JWT signatures server-side ENFORCEMENT: - OAuth and redirect endpoints enforce strict validation of allowed origins and redirect URLs - Redirect targets must be HTTPS and allowlisted DOMAIN CONSTRAINTS: - Cookies are ONLY shared across *.yoyogroup.com subdomains - Apps must be hosted on *.yoyogroup.com subdomains to receive shared cookies - Localhost cannot receive shared cookies (use OAuth flow instead) HTTPS REQUIREMENTS: - All redirect URLs must be HTTPS - Cookies require Secure flag (HTTPS only) - OAuth redirect URIs must be HTTPS (except localhost for development) ALLOWLIST REQUIREMENTS: - Redirect URLs must be allowlisted per application - Origin headers must be allowlisted for OAuth token exchange endpoints - Contact support.sa@yoyogroup.com for allowlist configuration LAUNCH PAD CONSTRAINTS: - Only available on specific hosts: auth.yoyogroup.com, auth.yoyoportal.com, author.yoyoportal.com - Requires active session to display - Apps must be registered with Yoyo Auth team to appear COMING SOON (NOT YET AVAILABLE): - OAuth2 With Yoyo - SAML authentication - SSO authentication - Self-service allowlisting for internal applications ================================================================================ 10. TROUBLESHOOTING ================================================================================ ISSUE: Missing Cookies After Login Documentation: https://auth-docs.yoyogroup.com/docs/troubleshooting/missing-cookies Symptoms: - You return from hosted auth but the app sees no yoyo_auth_access_token Checklist: 1. Confirm the auth portal is setting cookies on .yoyogroup.com 2. Verify the app is running on a subdomain of *.yoyogroup.com 3. Ensure your app is hosted on a *.yoyogroup.com subdomain 4. Confirm your site uses HTTPS 5. For local development, use a staging or development subdomain, or use OAuth flow ISSUE: Auth Origin Not Allowed (403) Documentation: https://auth-docs.yoyogroup.com/docs/troubleshooting/origin-not-allowed Symptoms: - POST /api/oauth/token returns 403 with an origin-allowlist error. Checklist: 1. Ensure the request includes a valid Origin or Referer header 2. Ask the Yoyo Auth team to add your origin to the allowlist 3. Use a single parent domain when possible to simplify allowlisting ISSUE: Redirects Are Blocked Or Ignored Documentation: https://auth-docs.yoyogroup.com/docs/troubleshooting/redirect-blocked Symptoms: - The portal returns to / instead of the requested redirectUrl - The redirect target is silently ignored Checklist: 1. Ensure the redirect URL is HTTPS (https: only) 2. Verify the hostname matches the redirect allowlist configured for your app 3. If no allowlist is set, the redirect host must match the current host 4. Confirm the URL is properly URL-encoded ISSUE: Redirect Loops Checklist: 1. Verify the allowlist configuration 2. Ensure you only redirect when the session is missing 3. Check that middleware/guards are not redirecting authenticated users ================================================================================ 11. CONTACT AND SUPPORT ================================================================================ SUPPORT EMAIL: support.sa@yoyogroup.com USE CASES FOR CONTACT: - Access requests - Allowlist updates (redirect URLs, origins) - Launch Pad registration - General integration questions - Troubleshooting assistance LAUNCH PAD REGISTRATION: To add your app to Launch Pad, update the JSON config and open a pull request: - Guide: https://auth-docs.yoyogroup.com/docs/guides/add-app-to-launch-pad - GitHub file: https://github.com/yoyogroup/yoyo-auth-hosted-web/blob/main/apps/yoyo-auth-web/config/launch-pad-apps.json ALLOWLIST REQUESTS: To configure redirect allowlists or origin allowlists, email support.sa@yoyogroup.com with: - Application ID (appId) - Redirect URLs to allowlist - Origins to allowlist (for OAuth token exchange endpoints) ================================================================================ 12. QUICK REFERENCE ================================================================================ PRODUCTION URLS: - Auth Portal: https://auth.yoyogroup.com - Auth Portal (with redirect): https://auth.yoyogroup.com/?redirectUrl= - Logout: https://auth.yoyogroup.com/logout?redirectUrl= INTEGRATION URLS: - Auth Portal: https://auth-int.yoyogroup.com - Auth Portal (with redirect): https://auth-int.yoyogroup.com/?redirectUrl= - Logout: https://auth-int.yoyogroup.com/logout?redirectUrl= - OAuth2 Authorize: https://auth-int.yoyogroup.com/api/oauth/authorize - OAuth2 Token: https://auth-int.yoyogroup.com/api/oauth/token - OAuth2 UserInfo: https://auth-int.yoyogroup.com/api/oauth/userinfo - OIDC Discovery: https://auth-int.yoyogroup.com/.well-known/openid-configuration COOKIE NAMES (Production): - yoyo_auth_access_token - yoyo_auth_id_token - yoyo_auth_refresh_token COOKIE NAMES (Integration): - yoyo_auth_int_access_token - yoyo_auth_int_id_token - yoyo_auth_int_refresh_token REQUIREMENTS: - All redirect URLs must be HTTPS (except localhost for development) - Apps must be on *.yoyogroup.com subdomains for shared cookies - Redirect URLs must be allowlisted - Origin headers must be allowlisted for password/token endpoints - Cookies are HttpOnly and can only be read server-side - OAuth2 redirect URIs must be exact matches (no wildcards) - OAuth2 client_id must be registered before use - OAuth2 requires PKCE with S256 method ================================================================================ END OF DOCUMENT ================================================================================