Skip to content

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 + RShelloOP-developer-server
SUD OpenPaaS = OAuth2 ClientThird-party app registered in helloOP (oauth2_registered_client)
Game vendor (CP)helloOP developer account (t_developer)
cp_idJWT 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 ​

text
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 ​

OrderPath matchAuthPurpose
1/oauth2/**OAuth2 protocolAuthorize, token, refresh, revoke
2/developer/**Bearer JWT (must include uid)Developer APIs; OpenPaaS data pull
3/external/**, /pink/**PermitOther external capabilities (out of scope)
4RemainingForm loginlogin.html; login page for Authorization Code

Do not mix the two login paths:

ItemAS form login (used for SUD bind)Custom REST login
EntryBrowser hits /oauth2/authorize → redirect /login.htmlPOST /developer/login
OutputSession → continue authorize → authorization_codeDeveloper JWT directly
Use caseThird-party (SUD OpenPaaS) account bindDeveloper 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):

  1. POST /developer/login to obtain a management JWT (only for creating the Client; unrelated to end-user bind).

  2. POST /developer/app/create:

    http
    POST /developer/app/create
    Authorization: Bearer {developer_mgmt_JWT}
    Content-Type: application/json
    
    {
      "clientName": "SUD OpenPaaS",
      "redirectUris": [
        "https://{sud-op-host}/callback"
      ],
      "scopes": "read write"
    }
  3. 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) ​

text
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) ​

http
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:

http
Authorization: Bearer {access_token}

The token must include uid. Tokens from client_credentials without uid cannot access /developer/**.

OrderhelloOP APIDescription
1GET /developer/infoSubject info; ID from token uid
2GET /developer/game/listOnline game list (paginated)
3GET /developer/game/basic-info?bundle_id=Per-game basic info
4GET /developer/game/qualification?bundle_id=Per-game qualifications
5GET /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 ​

http
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 WebhookhelloOP implementationNotes
oauth.authorizeGET /oauth2/authorizeStandard browser redirect; 302 back with code, not a JSON envelope
oauth.accessTokenPOST /oauth2/token (authorization_code)x-www-form-urlencoded; vendor id in JWT uid
oauth.refreshTokenPOST /oauth2/token (refresh_token)Same token endpoint
cp.queryDetailGET /developer/infoFields: id / subject_name / subject_type / uscc / username / status
cp.queryKYCGET /developer/infoSame subject-level shape as info; richer subject/manager in game.queryICP
game.queryListGET /developer/game/listPagination: page_no / page_size; items: bundle_id / name / version
game.queryDetailGET /developer/game/basic-info?bundle_id=Request key is bundle_id, not game_id
game.queryKYCGET /developer/game/qualification?bundle_id=Structured software_copyright / publication_number
game.queryICPGET /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 ​

FieldDescription
idThird-party subject ID (uid / mapping cp_id)
subject_nameSubject name
subject_type0 individual, 1 enterprise
usccUnified social credit code
usernameLogin name
status0 disabled, 1 enabled

5.2 Game list GET /developer/game/list ​

FieldDescription
list[].bundle_idPackage name (pull key)
list[].nameGame name
list[].versionLatest version
total / page_no / page_sizePagination

Only online games (status=1) are returned.

Unified response envelope:

json
{
  "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_uri whitelist
  • [ ] Authorization Code login page authenticates developers
  • [ ] access_token contains uid; /developer/** rejects tokens without uid
  • [ ] Subject, game list, detail, qualification (and ICP) pull APIs available
  • [ ] refresh_token supported; optional revoke

SUD OpenPaaS side ​

  • [ ] Store client_id / client_secret securely
  • [ ] Random state on authorize; strict callback verification
  • [ ] Server-only code exchange; no secret in browser
  • [ ] Map vendor via uid and persist tokens
  • [ ] Paginate full game list; alert/retry on missing items
  • [ ] Auto-refresh on expiry; re-auth when refresh fails