Skip to main content

Runbook: Iframe Authentication Mechanism (v1 to v2) via One-Time Access Token

This runbook documents the Single Sign-On (SSO) and session synchronization mechanism used when embedding Channelku v2 pages inside Channelku v1 using iframes.

Table of Contents​

  1. System Overview
  2. Sequence & Workflow Diagram
  3. Component Breakdown
  4. API & Parameter Specifications
  5. Security & Cookie Configurations
  6. Troubleshooting & Error Handling

1. System Overview​

The purpose of this mechanism is to allow authenticated users in Channelku v1 to seamlessly view specific features or pages hosted in Channelku v2 inside an HTML iframe element without re-authenticating.

  • Source System (v1): Generates a one-time use token based on the logged-in user's session data.
  • Destination System (v2): Validates the token, establishes secure cookies (CMT and USR), checks authorization levels, and redirects to the final intended frontend layout.

2. Sequence & Workflow Diagram​

Flow Diagram

3. Component Breakdown​

Source / Initiator: Channelku v1 (PHP / CodeIgniter)​

The controller initializes the flow by assembling session variables, mapping the system language, converting internal auto-increment database IDs to global Unique Identifiers (UIDs), and creating the cross-application authorization URL.

  • Language Mapping: Normalizes Japanese localization query strings (jp to ja).
  • ID Obfuscation: Uses Model_rooms->GePropertyUIDByID to pass a string UUID instead of numeric IDs over the URL string for safety.
  • Redireksi: Performs a client-side frame refresh redirect to the v2 validation controller.

Destination / Validator: Channelku v2 (Go / Fiber)​

The Fiber endpoint intercepts the query parameters, parses them, resolves dependencies, issues state cookies, and enforces contextual authorization gates.

  • ID Resolution: Transforms incoming property_id (UID) back to internal corporate integer IDs via propertyService.GetIDByUID.
  • Token Verification: Communicates with tokenService.VerifyAccessToken to guarantee integrity, validity, and lifetime criteria of the cross-app payload token.
  • Access Control Gate: Leverages gate.PropertyAccess to verify that the decrypted User ID actually holds permission policies allowing access to the active property identifier scope.

4. API & Parameter Specifications​

Endpoint Configuration​

  • Method: GET
  • Path: /sso/one-time-access-token

Query Parameters​

ParameterTypeRequiredDescriptionExample / Value
tokenStringYesOne-time auth security token passed from v1.cm_v2_token($email)
usrStringYesRaw unencrypted user identity string/integer.1052
property_idStringYesThe string-based Unique Identifier (UID) of the property.PROPDE_01KFWP4KG0ZH3Q25EE2WCAY1J5
langStringYesApplication language code locator.ja, id, en
pageStringYesTarget internal route path destination on the v2 front end application.last-10-logs

5. Security & Cookie Configurations​

Upon successful validation, two specific state containers are written inside the client's web browser context with the following configurations:

  1. CMT (Token Cookie)

    • Value: Raw string token.
    • Lifespan: 15 Minutes (time.Now().Add(15 * time.Minute)).
    • HTTPOnly: true (Protects against Cross-Site Scripting (XSS) extraction).

  2. USR (User Cookie)

    • Value: encrypt.Encrypt(user) (Encrypted payload format to protect user visibility identifiers).
    • Lifespan: 15 Minutes.
    • HTTPOnly: true.

⚠️ Iframe Infrastructure Warning (Cross-Origin Policy)​

Because this application runs embedded within an iframe, browsers will treat these cookies as Third-Party Cookies. Ensure the underlying environment service s.configCookie(c) returns the following properties in production:

  • SecureCookie: true (Requires HTTPS connection layers).
  • SameSite: "None" (Allows cross-site iframe cookie storage injection).

6. Troubleshooting & Error Handling​

HTTP StatusMessage Error JSONPrimary Root CausesMitigation & Resolution Actions
400"Token Not found" or "user is empty"Missing query key arguments inside the redirected URL payload string.Verify the URL string concatenation schema inside the Channelku v1 controller script.
400"token is not valid"Token has expired (past 15m window), was tampered with, or signature secrets mismatch.Generate a fresh v1 session, inspect time/clock synchronization between system servers.
400"Invalid parameter request"The property_id string UID parameter does not map to a real record inside v2 database tables.Verify database record alignment and cluster synchronizations between v1 and v2 environments.
403Forbidden()Authentication was successful, but user lacks authorization permission access maps for the specific target business domain.Check administrative platform user mapping control configurations for the target propertyId.
500"internal server error"Internal execution crash. Database system timeouts or infrastructure exceptions when fetching ID mapping.Check upstream logs configured with logger.New(err) on the application host infrastructure layer.