Control Plane Application Integration Guide

Overview

The Control Plane is a centralized authentication and application launcher for Dotmatics AWS services. Users authenticate once with the Control Plane and can then launch registered applications directly from the UI. Applications are embedded inside the Control Plane using secure iframe isolation.

The Control Plane is the single JWT issuer. Every application session is bootstrapped through it — applications never issue their own tokens.

1. Architecture Overview

Cognito / API Key
  ↓
POST /auth/exchange  or  POST /auth/token
  ↓
Control Plane JWT  (RS256, 15 min)
  ↓
User selects app in Control Plane UI
  ↓
POST /auth/apps/{app_id}/launch   (Bearer: CP JWT)
  ↓
Response: { "launch_url": "https://billing.example.com?code=CODE&app_id=APP_ID" }
  ↓
Control Plane loads iframe pointing to launch_url
  ↓
Application receives ?code=CODE&app_id=APP_ID query params
  ↓
POST /auth/apps/exchange-code   (unauthenticated, rate-limited)
  Body: { "code": "...", "app_id": "..." }
  ↓
Response: { "access_token": "<scoped JWT>", "refresh_token": "...", "token_type": "bearer" }
  ↓
Application establishes session using the scoped access token
  ↓
When access token nears expiry: POST /auth/refresh  (refresh token)
  ↓
New rotated access token + refresh token (no re-launch required)

2. Application Requirements

3. Security Requirements

Content Security Policy (required)

Content-Security-Policy: frame-ancestors https://control-plane.example.com;

Replace control-plane.example.com with the actual Control Plane domain.

X-Frame-Options: DENY
X-Frame-Options: SAMEORIGIN

HTTPS

Production application URLs must use https://. The Control Plane registration endpoint rejects non-HTTPS URLs for non-localhost addresses at registration time.

Recommended additional headers

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin

4. App Registration

Applications must be registered via the Control Plane API before they can be launched. Registration creates a pending record that is reviewed by a global:application_manager or global:admin before becoming active.

Request

POST /auth/apps
Authorization: Bearer <CP JWT>
Content-Type: application/json

{
  "name": "Billing",
  "slug": "billing",
  "description": "Billing and subscription management",
  "url": "https://billing.example.com",
  "icon": "💰",
  "app_type": "external",
  "roles": [
    {"name": "billing:admin",  "description": "Full billing access"},
    {"name": "billing:viewer", "description": "Read-only billing access"}
  ],
  "groups": [
    {"name": "billing-admins", "description": "Billing administrators", "roles": ["billing:admin"]}
  ],
  "default_permissions": [
    {"identity_name": "admin@example.com", "roles": ["billing:admin"]}
  ]
}

App type

The app_type field controls URL validation at registration time:

Naming rules (enforced at registration)

• The slug must be lowercase alphanumeric with optional hyphens (e.g. my-app). It must not start or end with a hyphen.
• All role names must be prefixed {slug}: (e.g. billing:admin).
• All group names must start with {slug} (e.g. billing-admins).
• Role names referenced inside group definitions must exist in the top-level roles list.
• Role/group names in default_permissions must exist in their respective lists.

Status lifecycle

On approval the Control Plane automatically provisions all roles and groups defined in the registration and applies default_permissions.

Updates are submitted via PATCH /auth/apps/{app_id}. The app remains launchable in its current approved state until the update is reviewed.

5. RBAC

The Control Plane uses Role-Based Access Control. Access to applications is governed by role assignments.

6. Launch Flow (step-by-step)

1. Authenticated user selects an app in the Control Plane UI.
2. Control Plane calls POST /auth/apps/{app_id}/launch with the user's Bearer JWT.
3. Server verifies the user holds at least one role for the app, then generates a one-time opaque launch code.
4. Server returns {"launch_url": "https://billing.example.com?code=CODE&app_id=APP_ID", "app_id": "..."}.
5. Control Plane loads an iframe pointing to launch_url.
6. The application page loads and reads the code and app_id query parameters.
7. Application immediately calls POST /auth/apps/exchange-code with {"code": "...", "app_id": "..."}.
8. Server validates the code (not expired, correct app_id, single-use) and deletes it atomically.
9. Server returns a TokenResponse: {"access_token": "<scoped JWT>", "refresh_token": "...", "token_type": "bearer"}.
10. Application stores both tokens (access token in memory or sessionStorage; refresh token in sessionStorage) and establishes its session.
11. Before the access token expires, the application calls POST /auth/refresh with the refresh token to receive a new rotated access token and refresh token — no user interaction or re-launch required.

7. Launch Code Properties

8. exchange-code Response & Scoped JWT

POST /auth/apps/exchange-code returns a TokenResponse identical in shape to the standard token endpoints:

{
  "access_token": "<scoped JWT>",
  "refresh_token": "<opaque token>",
  "token_type": "bearer"
}

Token lifetimes are not included in the response — the access token's exp claim encodes its expiry, and the refresh token's expiry is enforced server-side (a 401 is returned when it is expired or revoked).

The access token is a standard RS256 JWT issued by the Control Plane KMS key. Its roles claim contains only the roles the user holds that are defined by the specific application. The refresh token is app-scoped — it can only produce new access tokens carrying the same app_id and the user's current app-scoped roles (re-resolved on each refresh).

{
  "iss": "https://control-plane.example.com",
  "sub": "identity-uuid",
  "iat": 1712345600,
  "exp": 1712346500,
  "jti": "uuid",
  "roles": ["billing:admin"],
  "app_id": "app-uuid"
}

9. Token Verification

1. Fetch the JWKS document from GET /.well-known/jwks.json. Cache it for up to 1 hour.
2. Verify the RS256 signature using the matching kid.
3. Verify iss matches the expected Control Plane issuer.
4. Verify exp has not passed.
5. Verify app_id matches your application's registered ID.
6. Use the roles claim for in-app authorization decisions.

GET /.well-known/jwks.json

Response:
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "kms-key-id",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "..."
    }
  ]
}

10. API Endpoints Reference

11. Application Layout Guidelines

• Use a responsive layout — the iframe dimensions are controlled by the Control Plane and may change.
• Avoid fixed viewport assumptions or full-window overlays.
• Do not manipulate window.top, window.parent, or attempt to break out of the iframe.
• Do not override global browser navigation (e.g. history.pushState should stay within the app).

12. Security Best Practices

• Exchange the launch code immediately on page load — it expires after 5 minutes and is single-use.
• Store tokens in sessionStorage or memory, not localStorage (which persists across tabs and browser restarts).
• Do not bookmark or share launch URLs — the embedded ?code= value is consumed on first use and will return an error on replay.
• Validate app_id in the JWT claims matches your registered application ID before trusting the token.
• Use the refresh token to extend the session silently. The scoped access token is valid for 15 minutes. Call POST /auth/refresh before it expires to receive a new rotated access token and refresh token. Only prompt the user to re-launch if the refresh token is expired or the request returns 401.
• Refresh tokens rotate on every use. The previous refresh token is immediately revoked. Store only the most recently issued refresh token; discard the old one after a successful refresh.
• Rate limiting: the exchange-code endpoint is limited to 10 requests per minute per IP. Do not retry aggressively on failure.
• Never log or expose the raw launch code, access token, or refresh token in client-side error reporting or server logs.