Hello OP Integration with SUD OpenPaaS Example
This chapter uses helloOP-developer (the helloOP developer center) as a reference implementation of how a platform application (APP) can deliver the OAuth 2.0 authorization and existing-data pull capabilities described in Existing Data Synchronization Flow.
The abstract protocol is defined in Open APIs (Webhook). helloOP uses Spring Authorization Server standard OAuth 2.0 endpoints plus developer business APIs. Semantics align with the Webhook spec; paths and request shapes follow RFC 6749 / product conventions.
1. Example Positioning
| Abstract role (sync SOP) | helloOP counterpart |
|---|---|
| Platform APP = AS + RS | helloOP-developer-server |
| SUD OpenPaaS = OAuth2 Client | Third-party app registered in helloOP (oauth2_registered_client) |
| Game vendor (CP) | helloOP developer account (t_developer) |
cp_id | JWT uid claim (developer primary key) |
Business goal: vendor starts “bind helloOP account” on SUD OpenPaaS → browser completes helloOP login/consent → SUD exchanges token → pulls that developer’s subject and game existing data.
2. helloOP-developer Module Structure
helloOP-developer/
├── helloOP-developer-api/ # Feign / DTO
└── helloOP-developer-server/ # Spring Boot app
└── src/main/java/.../developer/
├── config/
│ └── SecurityConfig.java # Multi filter chains + OAuth2 AS
├── controller/
│ ├── auth/LoginController # POST /developer/login (console)
│ ├── developer/DeveloperController
│ │ # GET /developer/info (OpenPaaS pull)
│ ├── app/DeveloperAppController # POST /developer/app/create (register Client)
│ └── game/DeveloperGameController
│ # Game list / detail / qualification / ICP
└── service/2.1 Security Filter Chains
| Order | Path match | Auth | Purpose |
|---|---|---|---|
| 1 | /oauth2/** | OAuth2 protocol | Authorize, token, refresh, revoke |
| 2 | /developer/** | Bearer JWT (must include uid) | Developer APIs; OpenPaaS data pull |
| 3 | /external/**, /pink/** | Permit | Other external capabilities (out of scope) |
| 4 | Remaining | Form login | login.html; login page for Authorization Code |
Do not mix the two login paths:
| Item | AS form login (used for SUD bind) | Custom REST login |
|---|---|---|
| Entry | Browser hits /oauth2/authorize → redirect /login.html | POST /developer/login |
| Output | Session → continue authorize → authorization_code | Developer JWT directly |
| Use case | Third-party (SUD OpenPaaS) account bind | Developer console self-service |
SUD integration must use Authorization Code; do not replace it with POST /developer/login.
3. End-to-End Integration Flow
3.1 Phase 0: Register SUD as OAuth2 Client (One-time)
Performed by a helloOP developer admin (console or API):
POST /developer/loginto obtain a management JWT (only for creating the Client; unrelated to end-user bind).POST /developer/app/create:httpPOST /developer/app/create Authorization: Bearer {developer_mgmt_JWT} Content-Type: application/json { "clientName": "SUD OpenPaaS", "redirectUris": [ "https://{sud-op-host}/callback" ], "scopes": "read write" }Configure returned
clientId/clientSecret(plaintext shown once) into the SUD OpenPaaS backend. All later vendor binds reuse this pair.
Providing redirectUris enables authorization_code (and typically refresh_token).
3.2 Phase 1: User Authorization (Browser)
User Browser SUD OpenPaaS helloOP-developer
│ │ │
│ Click “Bind helloOP” │
│───────────────────→│ │
│ 302 redirect │ │
│←───────────────────│ │
│ Location: │
│ https://{helloOP}/oauth2/authorize │
│ ?response_type=code&client_id=... │
│ &redirect_uri=...&scope=read write&state=... │
│───────────────────────────────────────────────────────→│
│ │ Validate client│
│ │ Not logged in → /login.html
│ helloOP login page│ │
│←───────────────────────────────────────────────────────│
│ POST /oauth2/do-login (username + password form) │
│───────────────────────────────────────────────────────→│
│ │ Issue code │
│ 302 → redirect_uri?code=...&state=... │
│←───────────────────────────────────────────────────────│
│───────────────────→│ Verify state │3.3 Phase 2: Exchange Code for Token (Server-side)
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&redirect_uri=https://{sud}/callback
&client_id={clientId}
&client_secret={clientSecret}helloOP’s OAuth2TokenCustomizer writes uid (developer ID) into the access token. SUD may treat uid as the abstract protocol’s cp_id for account mapping.
3.4 Phase 3: Pull Existing Data
All pull APIs require:
Authorization: Bearer {access_token}The token must include uid. Tokens from client_credentials without uid cannot access /developer/**.
| Order | helloOP API | Description |
|---|---|---|
| 1 | GET /developer/info | Subject info; ID from token uid |
| 2 | GET /developer/game/list | Online game list (paginated) |
| 3 | GET /developer/game/basic-info?bundle_id= | Per-game basic info |
| 4 | GET /developer/game/qualification?bundle_id= | Per-game qualifications |
| 5 | GET /developer/game/icp-filing?bundle_id= | Per-game ICP filing |
Use bundle_id from the list as the key for detail/qualification/ICP calls.
3.5 Phase 4: Token Refresh
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={clientId}
&client_secret={clientSecret}On unbind, call POST /oauth2/revoke when needed.
4. Abstract Webhook ↔ helloOP Mapping
| Sync Webhook | helloOP implementation | Notes |
|---|---|---|
| oauth.authorize | GET /oauth2/authorize | Standard browser redirect; 302 back with code, not a JSON envelope |
| oauth.accessToken | POST /oauth2/token (authorization_code) | x-www-form-urlencoded; vendor id in JWT uid |
| oauth.refreshToken | POST /oauth2/token (refresh_token) | Same token endpoint |
| cp.queryDetail | GET /developer/info | Fields: id / subject_name / subject_type / uscc / username / status |
| cp.queryKYC | GET /developer/info | Same subject-level shape as info; richer subject/manager in game.queryICP |
| game.queryList | GET /developer/game/list | Pagination: page_no / page_size; items: bundle_id / name / version |
| game.queryDetail | GET /developer/game/basic-info?bundle_id= | Request key is bundle_id, not game_id |
| game.queryKYC | GET /developer/game/qualification?bundle_id= | Structured software_copyright / publication_number |
| game.queryICP | GET /developer/game/icp-filing?bundle_id= | Top-level license_no; enum fields as labels |
If an APP implements fully custom HTTPS Webhooks (JSON body + signature headers), keep the same semantics. helloOP chooses standard OAuth2 + REST GET for Spring Authorization Server compatibility.
5. Pull API Field Summary
5.1 Subject GET /developer/info
| Field | Description |
|---|---|
id | Third-party subject ID (uid / mapping cp_id) |
subject_name | Subject name |
subject_type | 0 individual, 1 enterprise |
uscc | Unified social credit code |
username | Login name |
status | 0 disabled, 1 enabled |
5.2 Game list GET /developer/game/list
| Field | Description |
|---|---|
list[].bundle_id | Package name (pull key) |
list[].name | Game name |
list[].version | Latest version |
total / page_no / page_size | Pagination |
Only online games (status=1) are returned.
Unified response envelope:
{
"ret_code": 0,
"ret_msg": "success",
"data": { },
"timestamp": 1719820800000
}6. End-to-End Sequence (helloOP)
7. Integration Checklist
APP (helloOP) side
- [ ] SUD Client registered with correct
redirect_uriwhitelist - [ ] Authorization Code login page authenticates developers
- [ ] access_token contains
uid;/developer/**rejects tokens withoutuid - [ ] Subject, game list, detail, qualification (and ICP) pull APIs available
- [ ]
refresh_tokensupported; optionalrevoke
SUD OpenPaaS side
- [ ] Store
client_id/client_secretsecurely - [ ] Random
stateon authorize; strict callback verification - [ ] Server-only code exchange; no secret in browser
- [ ] Map vendor via
uidand persist tokens - [ ] Paginate full game list; alert/retry on missing items
- [ ] Auto-refresh on expiry; re-auth when refresh fails
8. Related Docs
- Existing Data Synchronization Flow
- Open APIs
- helloOP engineering docs:
openpaas-developer-api.md/docs/sud-op-integration-flow.md
