[Proposal][Devportal] Standalone Key Manager Support for DevPortal

[Piumal1999]

Problem

The developer portal currently relies on the bijira control plane (CP) for all key management operations: OAuth2 client registration, token generation, API key issuance, and subscription lifecycle. Therefore the devportal cannot function independently without the control plane.

Example:

• OAuth2 key generation for an application: currently this creates or retrieves an application in Control Plane, creates subscriptions if needed, and then generates keys through Control Plane endpoints.
• OAuth2 client mapping: currently this maps an existing client ID to the application through Control Plane.
• OAuth2 access token generation: currently this generates tokens through Control Plane token-related endpoints.
• OAuth2 key revoke and cleanup: currently this revokes key mappings through Control Plane.
• API key generation: currently this generates API keys through Control Plane endpoints.
• API key revoke and regenerate: currently this revokes or regenerates API keys through Control Plane endpoints.

This coupling makes standalone deployments difficult because key operations depend on Control Plane. Standalone DevPortal users require the ability to use their own key managers with minimal setup and without a runtime dependency on Control Plane.

Solution

Provide the ability to custom-configure a key manager and execute key-related operations through it, without a runtime dependency on Control Plane. In standalone mode, DevPortal should use a configured key manager with minimal setup, while in Control Plane mode it should continue to work as before.

First-time devportal setup experience should be like:

• The setup should be simple and guided.
• A preconfigured profile (for example Asgardeo) should be available to reduce manual input in initial setup.
• The user should only provide minimum required details such as tokenUrl and clientId.
• After configuration, the user should be able to do the key-related operation.

Goals

• Allow the portal to run fully standalone with a single KM configured via config.json
• No change in behavior for CP-connected deployments (full backward compatibility)
• Credentials generated in standalone mode are owned and stored by the portal itself

---

Design

Modes of Operation

Mode	Config	Key management handled by
CP mode	controlPlane.enabled: true	Control plane (existing behavior)
Standalone mode	controlPlane.enabled: false, keyManager.enabled: true	Configured KM directly

---

Configuration

A new keyManager block is added to config.json (or config.toml in future):

"keyManager": {
  "enabled": true,
  "type": "WSO2IS",
  "name": "MyKM",
  "dcrEndpoint": "https://km.example.com/oauth2/register",
  "tokenEndpoint": "https://km.example.com/oauth2/token",
  "revokeEndpoint": "https://km.example.com/oauth2/revoke",
  "introspectEndpoint": "https://km.example.com/oauth2/introspect",
  "disableCertValidation": false,
  "pathToCertificate": "./resources/security/client-truststore.pem",
  "credentials": {
    "adminUsername": "admin",
    "adminPassword": "admin"
  }
}

---

Implementation Stage 1: OAuth2 Keys

What changes

In standalone mode, the portal handles OAuth2 client registration and token operations by talking directly to the KM using standard protocols.
Generated credentials (client ID, encrypted client secret, scopes, grant types) are stored in the portal's own database rather than the control plane.

User flows

Generate OAuth2 credentials for an application

1. User navigates to their application in the portal and clicks Generate Keys
2. User selects key type (Production / Sandbox), grant types, scopes, and optionally a callback URL
3. Portal registers a new OAuth client with the KM via DCR
4. KM returns client_id and client_secret
5. Portal stores the credentials and displays client_id and client_secret to the user
   • The client_secret is shown once — the user must copy it at this point
   • We can decide whether to store sclient secret or not.
6. The application's key status becomes Active

Generate an access token

1. User opens their application's credentials panel and clicks Generate Token (and provide the client secret if it is not stored in db)
2. User optionally specifies scopes and validity period
3. Portal calls the KM token endpoint (client_credentials grant) using the stored credentials
4. KM returns an access token
5. Portal displays the token to the user for use in API calls

Update OAuth2 credentials (scopes / grant types / callback URL)

1. User edits their application's key configuration (adds a scope, changes grant type, updates redirect URI)
2. Portal calls the KM to update the registered client
3. Portal updates the stored metadata
4. Updated configuration is reflected immediately in the portal UI

Revoke OAuth2 credentials

1. User clicks Revoke on their application's key
2. Portal calls the KM to deregister the OAuth client
3. Portal marks the key as Revoked in its database

[Piumal1999]

Database Changes

New table: DP_APPLICATION_KEYS

Stores KM-generated credentials locally. (In CP mode these live in the control plane. in standalone mode the portal owns them).

Column	Description
KEY_ID	Primary key. Serves as the keyMappingId returned to clients and used in subsequent token/revoke/update calls.
APP_ID	FK → DP_APPLICATION. The application that owns these credentials. Cascade-deletes when the app is deleted.
ORG_ID	Tenant scoping — all queries filter by org.
TOKEN_TYPE	OAUTH (Stage 1) or API_KEY (Stage 2). Differentiates row purpose so both key types share the table.
KEY_TYPE	PRODUCTION or SANDBOX.
KEY_MANAGER	Name of the KM that issued the credential (from config.keyManager.name). Enables future multi-KM support.
CLIENT_ID	OAuth client_id issued by the KM via DCR.
CLIENT_SECRET_ENC	OAuth client_secret encrypted with AES-256-GCM. Decrypted in memory only for server-side token generation. Not needed if the portal does not perform server-side token generation (display-once flow).
SCOPES	Space-separated OAuth scopes granted to this client.
GRANT_TYPES	Space-separated OAuth grant types the client is registered for.
CALLBACK_URL	Redirect URI registered with the KM for authorization_code flow.
ADDITIONAL_PROPS	KM-specific extra fields from DCR (stored as JSONB for round-trip fidelity).
STATUS	ACTIVE or REVOKED.
CREATED_AT / UPDATED_AT	Audit timestamps.

No changes to existing tables (Stage 1)

DP_APPLICATION, DP_APP_KEY_MAPPING, DP_API_SUBSCRIPTION, and all other existing tables are unchanged. CP_APP_REF in DP_APP_KEY_MAPPING is kept as-is — in standalone mode the portal can write the local APP_ID into it as a self-reference.

---

REST API Changes

The portal's external REST API surface is unchanged — all existing endpoints keep the same paths, methods, and request/response shapes. The difference is in how the portal fulfills them internally.