# ต่อแอปเดิมเข้า SSO กรมส่งเสริมการเกษตร

เอกสารนี้ให้ AI อ่านแล้วแก้แอปที่มีอยู่แล้ว ไม่ใช่สร้างแอปใหม่
ไฟล์นี้ไม่มีรหัสผ่าน ไม่มี client_secret และไม่มีข้อมูลส่วนบุคคล
Issuer ทุกเส้นทาง: `https://sso.doae.go.th`
คู่มือสำหรับคน: `https://sso.doae.go.th/overview`
ติดต่อ: helpdesk@doae.go.th · ศูนย์เทคโนโลยีสารสนเทศและการสื่อสาร กรมส่งเสริมการเกษตร

## สำหรับ AI — อ่านก่อนลงมือ

1. เลือกเส้นทางเดียวจากตารางด้านล่าง แล้วทำให้ครบตามส่วนนั้นเท่านั้น
2. **2FA เป็น first-class:** งานยังไม่เสร็จถ้ายังเข้าแอปด้วยรหัสผ่านอย่างเดียวได้
3. แอป**ห้าม**สร้างหน้า TOTP/OTP ของตัวเอง — หน้า 2FA อยู่ที่ `sso.doae.go.th` เท่านั้น
4. ถ้ายังไม่มี `client_id` / `client_secret` ให้หยุด ถามเจ้าของแอป อย่าแต่งค่า อย่าใส่ secret ในไฟล์ที่ commit
5. เรียก API ของ SSO จาก**เซิร์ฟเวอร์แอปเท่านั้น** ห้ามใส่ `client_secret` ในเบราว์เซอร์
6. ตัวอย่าง Step-up ที่ดูพฤติกรรมได้: `https://step-up-php-test.doae.go.th` (และ laravel / express / nextjs) — ห้ามนำ secret ของ demo ไปใช้จริง

## กฎแรก: 2FA เป็น first-class ทั้งสองเส้นทาง

| | SSO เต็มรูปแบบ | Step-up |
|---|---|---|
| ปัจจัยที่ 1 | เข้าบัญชีกรมบนหน้า SSO | ชื่อผู้ใช้ + รหัสผ่านของแอป |
| ปัจจัยที่ 2 (บังคับ) | TOTP หรือรหัสเมลบนหน้า SSO | TOTP หรือรหัสเมลบนหน้า SSO หลังรหัสผ่านแอปผ่าน |
| ใครทำหน้า 2FA | SSO เท่านั้น | SSO เท่านั้น |
| เมื่อไหร่ถือว่าเข้าได้ | ได้ `code` กลับมาที่ callback แล้วแลก token สำเร็จ | ได้คำตอบ token หลังผ่าน OTP บน SSO แล้วเท่านั้น |

ห้าม

- มีทางเข้าแอปด้วยรหัสผ่านอย่างเดียว
- สร้าง bypass / feature flag / โหมด dev ที่ปิด 2FA
- ถือว่า “ต่อ OAuth แล้วจบ” โดยไม่ผ่านหน้า 2FA ของ SSO
- ข้าม step-up หลังรหัสผ่านแอปผ่าน
- สร้างหน้า TOTP ในแอปปลายทาง

## ก่อนลงมือ

1. อ่านวิธีเข้าสู่ระบบเดิมของแอป: route, session, ตารางผู้ใช้, จุดตรวจรหัสผ่าน
2. เลือกเส้นทาง — ถ้าเข้าทั้งสองเงื่อนไข ให้หยุดแล้วถามคน ไม่เดาเอง
3. ถ้ายังไม่มี credential ให้หยุดตามส่วนท้ายเอกสาร
4. แทรก SSO ตามลำดับด้านล่าง คงการตรวจสิทธิ์เดิมของแอปไว้ และคงกฎ 2FA ไว้ทุกจุด

| สภาพแอป | เส้นทาง |
|---|---|
| ไม่มีหน้าเข้าสู่ระบบของตัวเอง คนเข้าด้วยบัญชีกรมอย่างเดียว | SSO เต็มรูปแบบ |
| มีชื่อผู้ใช้และรหัสผ่านของแอปอยู่แล้ว แอปเก็บ session และสิทธิ์เอง | Step-up |

ใช้คนละ `client_id`

- client ที่ขึ้นต้น `otp_` ใช้ได้เฉพาะ `/api/otp/link/*` และ `/api/otp/step-up/*`
- client ของ SSO เต็มรูปแบบใช้ได้เฉพาะ `/oauth/*` และ `/api/auth/*`
- ห้ามสลับกัน

## ความปลอดภัยที่ใช้ทั้งสองเส้นทาง

- **2FA first-class:** ปัจจัยที่ 2 ของ SSO เป็นขั้นบังคับ ไม่ใช่ทางเลือก
- เรียก SSO จากเซิร์ฟเวอร์ของแอปเท่านั้น ตรวจใบรับรอง TLS ตามปกติ อย่าปิดการตรวจ
- เก็บ `client_secret` ในตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ ห้ามใส่ในเบราว์เซอร์ แอปมือถือ สคริปต์ที่ผู้ใช้ดาวน์โหลด หรือไฟล์ที่ commit
- สร้าง `state` อย่างน้อย 16 ไบต์จากตัวสุ่มทางคริปโต เก็บใน session ฝั่งเซิร์ฟเวอร์ ใช้ครั้งเดียว แล้วลบทิ้ง เทียบให้ตรงทั้งสตริง ถ้าไม่ตรงให้ตอบ 403 และห้ามแลก `code`
- ประกอบ `redirect_uri` จากค่าที่ตั้งไว้ในสภาพแวดล้อม ห้ามใช้ `Host`, `X-Forwarded-Host`, หรือพารามิเตอร์ที่มากับคำขอ
- `redirect_uri` บน production ต้องเป็น `https` บน `doae.go.th` หรือ `*.doae.go.th` มี path จริง และตรงกับค่าที่ลงทะเบียนทุกตัวอักษร รวมถึง `/` ท้าย path (localhost ใช้ได้เฉพาะตอนพัฒนา)
- ก่อนส่งเบราว์เซอร์ออกจากแอป ตรวจว่าปลายทางเป็น `https://sso.doae.go.th` เท่านั้น ห้ามใช้โดเมนที่ผู้ใช้ส่งมา และห้ามเชื่อ `otp_url` ถ้า host ไม่ใช่ `sso.doae.go.th`
- cookie ของ session แอปต้องเป็น `Secure`, `HttpOnly` และ `SameSite=Lax` หลังเข้าสู่ระบบสำเร็จให้เปลี่ยน session id ใหม่
- อย่าบันทึก `client_secret`, `code`, `access_token`, `refresh_token` ลง log
- ถ้า secret หลุด ให้หยุดใช้งานค่านั้น แล้วให้เจ้าของแอปสร้าง secret ใหม่ทันที
- ห้ามใช้ implicit flow, ห้ามใส่ token ใน query string, ห้ามเรียก path `/oauth2/*`

---

## SSO เต็มรูปแบบ

ได้ `access_token` แล้วดึงข้อมูลผู้ใช้ — OAuth 2.0 Authorization Code + OpenID Connect

### 2FA ในเส้นนี้ (first-class)

1. แอปส่งผู้ใช้ไป `GET /oauth/authorize` เท่านั้น — ยังไม่สร้าง session สมบูรณ์
2. ผู้ใช้เข้าบัญชีกรมแล้วทำ 2FA บนหน้า SSO (TOTP หรือรหัสเมล)
3. SSO ออก `code` หลังผ่าน 2FA แล้วเท่านั้น — แอปปลายทาง**ไม่ต้อง**สร้างหน้า 2FA และ**ไม่ต้อง**ถอด JWT เพื่อดู `amr`
4. แอปแลก `code` → token → userinfo ที่ callback แล้วค่อยสร้าง session
5. ห้ามปิด / ข้าม / ทำ bypass 2FA

สมัครที่เมนูนำแอปเข้า SSO หลังเข้าบัญชีกรม  
Redirect เช่น `https://<แอป>/auth/callback`  
Scope: `openid profile email`

ผู้ใช้ต้องมีอีเมล `@doae.go.th` — ถ้ายังไม่มี SSO จะปฏิเสธด้วย `doae_email_required`

### วิธีที่แนะนำ: ใช้ library OpenID Connect มาตรฐาน

SSO รองรับ OIDC ครบ (discovery, `id_token` RS256, `nonce`, PKCE S256, `refresh_token` grant, RP-Initiated และ Back-Channel Logout)
ถ้าภาษาที่ใช้มี library OIDC ให้ใช้ library แทนการเขียนเอง แล้วตั้งค่าแค่นี้

```
issuer        = https://sso.doae.go.th
client_id     = <SSO_CLIENT_ID>
client_secret = <SSO_CLIENT_SECRET>   (client_secret_post หรือ client_secret_basic)
redirect_uri  = <SSO_REDIRECT_URI>
scope         = openid profile email
```

ตัวอย่าง: Node `openid-client` / Auth.js (provider type `oidc`), Python Authlib, Spring Security OAuth2 Client, .NET `AddOpenIdConnect`, PHP `jumbojett/openid-connect-php`
library จะตรวจ `state`, `nonce`, PKCE และลายเซ็น `id_token` ให้เอง — ยังต้องทำข้อ 7 (ออกจากระบบ) ตามด้านล่าง
ถ้าไม่มี library ให้ทำตามลำดับด้านล่างทีละขั้น

### ตัวแปรฝั่งเซิร์ฟเวอร์

```
SSO_ISSUER=https://sso.doae.go.th
SSO_CLIENT_ID=<จากเมนูนำแอปเข้า SSO>
SSO_CLIENT_SECRET=<แสดงครั้งเดียวตอนสร้าง>
SSO_REDIRECT_URI=https://<แอป>/auth/callback
SSO_SCOPES=openid profile email
```

### ลำดับการต่อ

1. ที่ปุ่มเข้าสู่ระบบ สร้าง `state` เก็บใน session แล้วส่งเบราว์เซอร์ไป

```
GET https://sso.doae.go.th/oauth/authorize
  ?client_id=<SSO_CLIENT_ID>
  &redirect_uri=<SSO_REDIRECT_URI>
  &response_type=code
  &scope=openid profile email
  &state=<ค่าใน session>
```

ใช้ `response_type=code` เท่านั้น

2. เปิด `GET /auth/callback`
   - `error=access_denied` → ล้าง state บอกผู้ใช้ว่ายกเลิก ห้ามแลก token ห้ามสร้าง session
   - `state` ไม่ตรง session → ตอบ 403
   - `code` ใช้ได้ครั้งเดียว หมดอายุ 5 นาที
   - ได้ `code` → ค่อยแลก token

3. แลก token ที่เซิร์ฟเวอร์ — `redirect_uri` ต้องเป็นค่าเดียวกับตอน authorize

```
POST https://sso.doae.go.th/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&redirect_uri=<SSO_REDIRECT_URI>
&client_id=<SSO_CLIENT_ID>
&client_secret=<SSO_CLIENT_SECRET>
```

คำตอบมี `access_token`, `refresh_token`, `token_type` = `Bearer`, `expires_in` ≈ 86400 และ `id_token` (เมื่อ scope มี `openid`)  
เก็บ refresh token ฝั่งเซิร์ฟเวอร์ผูกกับ session นี้ ห้ามส่งให้เบราว์เซอร์  
`id_token` เป็น JWT RS256 (`iss`, `sub`, `aud`, `exp`, `nonce` ถ้าส่งมา, `sid`, `amr`, `email`, `name`) ตรวจด้วย JWKS — ถ้าไม่ได้ใช้ library จะข้ามแล้วใช้ userinfo ตามข้อ 4 ก็ได้  
ถ้าส่ง `nonce` และ/หรือ `code_challenge` (+ `code_challenge_method=S256`) ตอน authorize ต้องส่ง `code_verifier` ตอนแลก token และตรวจ `nonce` ใน `id_token`

4. ดึงโปรไฟล์ — อย่าถอดหรือตรวจลายเซ็น `access_token` เอง ให้เรียก userinfo แทน (ข้อยกเว้นเดียวคือ `logout_token` ในข้อ 7.2 ที่ตรวจด้วยกุญแจสาธารณะจาก JWKS)

```
GET https://sso.doae.go.th/oauth/userinfo
Authorization: Bearer <access_token>
```

ใช้ `sub` เป็นรหัสผู้ใช้ในแอป ห้ามใช้ email เป็นคีย์หลัก  
เก็บ `sid` จาก userinfo ไว้คู่กับ session ของแอป (เช่นคอลัมน์ `sso_sid`) — ใช้ตอน SSO สั่งออกจากระบบ ดูข้อ 7  
ฟิลด์แสดงผลได้: `email`, `full_name`, `preferred_username`, `organization_id`, `organization_name`, `province`, `admin_level`  
`role` และ `admin_level` เป็นสิทธิ์ใน SSO ไม่ใช่สิทธิ์ของแอป — ถ้าแอปมีตารางสิทธิ์เอง ให้คงตารางนั้นไว้

5. เปลี่ยน session id แล้วสร้าง session ของแอป (จุดนี้เท่านั้นที่ถือว่าเข้าสู่ระบบสมบูรณ์)
6. เมื่อ access token หมดอายุ ให้ต่ออายุที่เซิร์ฟเวอร์ แล้วเก็บ refresh token ตัวใหม่แทนตัวเก่า (ตัวเก่าใช้ซ้ำไม่ได้)

```
POST https://sso.doae.go.th/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<ค่าที่เก็บฝั่งเซิร์ฟเวอร์>
&client_id=<SSO_CLIENT_ID>
&client_secret=<SSO_CLIENT_SECRET>
```

คำตอบ: `access_token`, `refresh_token`, `token_type`, `expires_in`, `id_token`  
Access token ≈ 24 ชั่วโมง · Refresh token ≈ 365 วัน  
(แอปเดิมที่ใช้ `POST /api/auth/refresh` ยังใช้ได้)

7. ออกจากระบบ — ทำให้ครบทั้งสองทิศ

**7.1 ผู้ใช้กดออกจากแอป (RP-Initiated Logout)**

ล้าง session ของแอปก่อน แล้วส่งเบราว์เซอร์ไป

```
GET https://sso.doae.go.th/oauth/logout
  ?client_id=<SSO_CLIENT_ID>
  &post_logout_redirect_uri=https://<แอป>/
  &state=<ไม่บังคับ>
```

- SSO ออกจากระบบในเบราว์เซอร์ และเพิกถอน token ของทุกแอปที่เข้าผ่าน login ครั้งนั้น แล้วพากลับ
- `post_logout_redirect_uri` ต้องเป็น https บน host เดียวกับ Redirect URI ที่ลงทะเบียน ไม่ตรงจะได้ 400

**7.2 SSO สั่งแอปออก (Back-Channel Logout 1.0) — ต้องทำ**

เมื่อผู้ใช้ออกจากระบบที่แอปอื่น เว็บ SSO ยกเลิก session หรือลบอุปกรณ์ใน DOAE ID — SSO จะ POST มาที่ Back-channel logout URL ของแอป

ตั้ง URL: เจ้าของแอปตั้งที่ `https://sso.doae.go.th` → นำแอปเข้า SSO (ตอนลงทะเบียน หรือปุ่มออกจากระบบในแถวของแอป) — https บน `*.doae.go.th` มี path เช่น `https://<แอป>/oidc/backchannel-logout`
ถ้า AI ตั้งเองไม่ได้ ให้บอกเจ้าของแอปว่าต้องตั้ง URL นี้

คำขอที่แอปจะได้รับ

```
POST https://<แอป>/oidc/backchannel-logout
Content-Type: application/x-www-form-urlencoded

logout_token=<JWT>
```

`logout_token` header: `alg` = `RS256`, `typ` = `logout+jwt`, `kid`  
payload

```json
{
  "iss": "https://sso.doae.go.th",
  "aud": "<SSO_CLIENT_ID>",
  "iat": 1767000000,
  "exp": 1767000120,
  "jti": "<uuid>",
  "sub": "<sub ของผู้ใช้>",
  "sid": "<sid เดียวกับใน userinfo>",
  "events": { "http://schemas.openid.net/event/backchannel-logout": {} }
}
```

endpoint ต้องทำตามลำดับ

1. รับเฉพาะ `POST` ไม่ต้องมี session ไม่ต้อง login ยกเว้น CSRF สำหรับ path นี้ ห้าม redirect
2. ตรวจลายเซ็น RS256 ด้วยกุญแจ `kty` = `RSA` ที่ `kid` ตรงกันจาก `https://sso.doae.go.th/.well-known/jwks.json` (cache ได้ ถ้าไม่เจอ `kid` ให้โหลดใหม่หนึ่งครั้ง) — ห้ามรับ `alg` อื่น ห้ามใช้กุญแจ `oct`
3. ตรวจ `iss` = `https://sso.doae.go.th`, `aud` = `SSO_CLIENT_ID`, `exp` ยังไม่หมด, มี `events["http://schemas.openid.net/event/backchannel-logout"]`, และ**ต้องไม่มี** `nonce` — ไม่ผ่านให้ตอบ `400`
4. ใช้ `jti` กันประมวลผลซ้ำ (SSO ส่งซ้ำได้สูงสุด 3 ครั้งถ้าไม่ได้ 200)
5. ลบทุก session ของแอปที่ `sso_sid` = `sid` (ถ้าไม่มี `sid` ให้ลบทุก session ของ `sub`) และลบ refresh token ที่ผูกไว้
6. ตอบ `200` ตัวเปล่า

ตัวอย่าง Laravel (`composer require firebase/php-jwt`)

```php
use Firebase\JWT\JWT;
use Firebase\JWT\JWK;

Route::post('/oidc/backchannel-logout', function (Request $r) {
    $jwks = Cache::remember('sso_jwks', 3600, fn () =>
        Http::get('https://sso.doae.go.th/.well-known/jwks.json')->json());
    $rsa = ['keys' => array_values(array_filter($jwks['keys'], fn ($k) => $k['kty'] === 'RSA'))];

    try {
        $c = JWT::decode($r->input('logout_token'), JWK::parseKeySet($rsa));
    } catch (\Throwable $e) {
        return response('', 400);
    }

    $event = 'http://schemas.openid.net/event/backchannel-logout';
    if ($c->iss !== 'https://sso.doae.go.th' || $c->aud !== env('SSO_CLIENT_ID')
        || !isset($c->events->{$event}) || isset($c->nonce)) {
        return response('', 400);
    }
    if (!Cache::add('sso_logout_jti:' . $c->jti, 1, 600)) {
        return response('', 200);
    }

    DB::table('sessions')->where('sso_sid', $c->sid)->delete();
    return response('', 200);
});
```

ตัวอย่าง Node.js / Express (`npm i jose`)

```js
import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://sso.doae.go.th/.well-known/jwks.json'));
const EVENT = 'http://schemas.openid.net/event/backchannel-logout';
const seen = new Map();

app.post('/oidc/backchannel-logout', express.urlencoded({ extended: false }), async (req, res) => {
  try {
    const { payload: c } = await jwtVerify(req.body.logout_token, JWKS, {
      issuer: 'https://sso.doae.go.th',
      audience: process.env.SSO_CLIENT_ID,
      algorithms: ['RS256'],
      typ: 'logout+jwt',
    });
    if (!c.events?.[EVENT] || 'nonce' in c) return res.sendStatus(400);
    if (seen.has(c.jti)) return res.sendStatus(200);
    seen.set(c.jti, Date.now());
    await deleteSessionsBySsoSid(c.sid);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});
```

**7.3 ทางสำรอง** — ถ้ายังทำ 7.2 ไม่ได้ ให้เรียก `GET /oauth/userinfo` ด้วย access token ของ session เป็นระยะ (ทุก 1–5 นาที หรือทุก request สำคัญ) ได้ `401` ให้ล้าง session ของแอปทันที

Discovery: `GET https://sso.doae.go.th/.well-known/openid-configuration` (มี `end_session_endpoint`, `backchannel_logout_supported`)

### ข้อผิดพลาด

| error | สาเหตุ | สิ่งที่แอปทำ |
|---|---|---|
| `invalid_client` | client id หรือ secret ไม่ตรง | หยุด ตรวจค่าใน env ห้ามลองสุ่ม |
| `invalid_redirect_uri` | URI ไม่ตรงที่ลงทะเบียน | แก้ให้ตรงทุกตัวอักษร รวม scheme และ path |
| `invalid_grant` | code หมดอายุหรือใช้แล้ว | เริ่ม authorize ใหม่ |
| `invalid_scope` | scope ไม่ได้รับอนุญาต | ใช้ `openid profile email` |
| `access_denied` | ผู้ใช้ยกเลิก (รวมตอน 2FA) | ล้าง state กลับหน้าเดิม ห้ามสร้าง session |
| `doae_email_required` | ยังไม่มีเมล `@doae.go.th` | บอกผู้ใช้ให้ไปเปิด/เชื่อมเมลที่ SSO ก่อน |

### เสร็จเมื่อ (SSO เต็มรูปแบบ)

1. ไม่มีทางเข้าแอปด้วยรหัสผ่านอย่างเดียว — 2FA อยู่ที่ SSO
2. แอปไม่มีหน้า TOTP/OTP ของตัวเอง และไม่มี flag ปิด 2FA
3. ปุ่มเข้าสู่ระบบไป `/oauth/authorize` และกลับที่ `/auth/callback`
4. แลก token ที่เซิร์ฟเวอร์ และตรวจ `state` ก่อนแลก
5. แอปจำผู้ใช้ด้วย `sub` และเก็บ refresh token ฝั่งเซิร์ฟเวอร์
6. `client_secret` ไม่อยู่ในโค้ดฝั่งเบราว์เซอร์
7. session ของแอปเก็บ `sid` จาก userinfo
8. ปุ่มออกจากระบบล้าง session แล้วไป `/oauth/logout` พร้อม `client_id` และ `post_logout_redirect_uri`
9. มี endpoint Back-channel logout ที่ตรวจลายเซ็น RS256 + `iss` / `aud` / `events` / ไม่มี `nonce` แล้วลบ session ตาม `sid` ตอบ 200 — และแจ้งเจ้าของแอปให้ตั้ง URL ที่ SSO
10. ทดสอบ: login เข้าแอป → ไป `https://sso.doae.go.th/?tab=sessions` กดยกเลิก session นั้น → แอปต้องหลุดภายในไม่กี่วินาที

---

## Step-up

ใช้เมื่อแอปมีบัญชีและรหัสผ่านอยู่แล้ว  
ผลคือการยืนยันใช้ครั้งเดียว — **ไม่มี** `access_token`

### 2FA ในเส้นนี้ (first-class)

1. คงหน้าตรวจชื่อผู้ใช้และรหัสผ่านของแอปไว้ (ปัจจัยที่ 1)
2. หลังรหัสผ่านผ่าน **ต้อง** เรียก step-up ทันที — เก็บสถานะ `pending_2fa` ห้ามให้สิทธิ์ใช้งาน
3. ผู้ใช้ยืนยันบนหน้า SSO ผ่าน `otp_url` (TOTP หรือรหัสเมล) — นี่คือปัจจัยที่ 2
4. แอปแลก `code` ที่เซิร์ฟเวอร์ แล้วสร้าง session เฉพาะเมื่อตรวจผ่านตามด้านล่าง
5. ห้ามจบที่รหัสผ่านแอปอย่างเดียว และห้ามสร้างหน้า TOTP ในแอป

สมัครที่ `https://sso.doae.go.th/integration/apply` หลังเข้าบัญชีกรม  
ได้ `client_id` ที่ขึ้นต้น `otp_` และ `client_secret` ทันที  
ลงทะเบียนสอง callback ห้ามใช้ path เดียวกัน

- `https://<แอป>/auth/sso-link/callback` — ผูกบัญชีครั้งแรก
- `https://<แอป>/auth/sso-otp/callback` — ยืนยันครั้งถัดไป

โดเมนทดสอบ: `step-up-php-test`, `step-up-laravel-test`, `step-up-express-test`, `step-up-nextjs-test` ใต้ `.doae.go.th`

### ตัวแปรฝั่งเซิร์ฟเวอร์

```
SSO_API=https://sso.doae.go.th
SSO_CLIENT_ID=otp_<ระบบ>
SSO_CLIENT_SECRET=<แสดงครั้งเดียวตอนสมัคร>
APP_ORIGIN=https://<แอป>
```

`APP_ORIGIN` ต้องตั้งคงที่ ห้ามประกอบจากคำขอที่เข้ามา

### ลำดับการแทรก

คงหน้าตรวจชื่อผู้ใช้และรหัสผ่านไว้ เรียก SSO หลังตรวจผ่านแล้วเท่านั้น  
`local_user_id` ต้องมาจากผู้ใช้ที่เพิ่งตรวจผ่านใน session ห้ามรับจาก query หรือฟอร์มที่เบราว์เซอร์ส่งซ้ำ

1. สุ่ม `state` เก็บใน session พร้อม `local_user_id` — ยังไม่ถือว่าเข้าสู่ระบบสมบูรณ์

```
POST https://sso.doae.go.th/api/otp/step-up/start
Content-Type: application/json

{
  "client_id": "<SSO_CLIENT_ID>",
  "client_secret": "<SSO_CLIENT_SECRET>",
  "local_user_id": "<รหัสผู้ใช้ในแอป>",
  "redirect_uri": "<APP_ORIGIN>/auth/sso-otp/callback",
  "state": "<ค่าใน session>"
}
```

- `200` ได้ `otp_url` และ `expires_in` (300 วินาที) — ตรวจว่า host เป็น `sso.doae.go.th` แล้วค่อย redirect
- `409` และ `error` = `not_linked` → เรียกเส้นผูกด้วย `state` เดิม ห้ามสุ่ม state ใหม่

```
POST https://sso.doae.go.th/api/otp/link/start
Content-Type: application/json

{
  "client_id": "<SSO_CLIENT_ID>",
  "client_secret": "<SSO_CLIENT_SECRET>",
  "local_user_id": "<รหัสผู้ใช้ในแอป>",
  "redirect_uri": "<APP_ORIGIN>/auth/sso-link/callback",
  "state": "<ค่าเดียวกับใน session>"
}
```

เก็บใน session ว่าครั้งนี้เป็น `step_up` หรือ `link` แล้วส่งไป `otp_url`

2. เปิดสอง route
   - `GET /auth/sso-link/callback`
   - `GET /auth/sso-otp/callback`

   สำเร็จ: `?code=...&state=...`  
   ยกเลิก: `?error=access_denied&state=...` → ล้างรายการที่ค้าง ห้ามแลก code ห้ามสร้าง session  
   `state` ไม่ตรง หรือชนิด callback ไม่ตรง session → ตอบ 403 ห้ามแลก code

3. แลก code ที่เซิร์ฟเวอร์ครั้งเดียว — `redirect_uri` ต้องตรงกับตอน start ของเส้นนั้น

**ผูกบัญชี (ครั้งแรก):**

```
POST https://sso.doae.go.th/api/otp/link/token
Content-Type: application/json

{
  "client_id": "<SSO_CLIENT_ID>",
  "client_secret": "<SSO_CLIENT_SECRET>",
  "code": "<จาก query>",
  "redirect_uri": "<APP_ORIGIN>/auth/sso-link/callback"
}
```

คำตอบมี `sso_user_id`, `email`, `full_name`, `already_linked` — **ไม่มี** `access_token` และ**ไม่มี** `amr`  
บันทึกคู่ `local_user_id` ↔ `sso_user_id` ในฐานของแอป  
ถ้าได้ `conflict` → บัญชีถูกผูกกับอีกฝ่ายแล้ว ห้ามเขียนทับ ให้หยุดแล้วบอกผู้ใช้  

ผู้ใช้ผ่าน OTP บน SSO มาแล้วตอน link — หลังแลกสำเร็จและบันทึกคู่แล้ว **เปลี่ยน session id แล้วสร้าง session ได้** (เหมือนตัวอย่าง demo)  
ห้ามสร้าง session จากรหัสผ่านอย่างเดียวโดยไม่ผ่าน callback นี้

**ยืนยันครั้งถัดไป (step-up):**

```
POST https://sso.doae.go.th/api/otp/step-up/token
Content-Type: application/json

{
  "client_id": "<SSO_CLIENT_ID>",
  "client_secret": "<SSO_CLIENT_SECRET>",
  "code": "<จาก query>",
  "redirect_uri": "<APP_ORIGIN>/auth/sso-otp/callback"
}
```

คำตอบมี `ok`, `sso_user_id`, `local_user_id`, `amr` — ไม่มี `access_token`  

`amr` จริงจาก SSO เป็นเช่น `["pwd","totp"]` หรือ `["pwd","email"]`  
ก่อนสร้าง session ต้องตรวจครบ

- `ok` เป็นจริง
- `local_user_id` ตรงกับคนที่เพิ่งผ่านรหัสผ่าน
- `sso_user_id` ตรงกับคู่ที่บันทึกไว้ของ `local_user_id` นั้น
- `amr` มีอย่างน้อยหนึ่งค่าในชุดนี้: `totp` หรือ `email` — ถ้ามีแค่ `pwd` หรือว่าง ให้ปฏิเสธ อย่าสร้าง session

จากนั้นเปลี่ยน session id แล้วล้าง `state` ที่ค้าง  
อีเมลที่เชื่อได้คืออีเมลในคำตอบของ token (เส้น link) ห้ามเชื่อค่าที่ติดมากับ URL

### ข้อผิดพลาด

| error | สถานะ | สิ่งที่แอปทำ |
|---|---|---|
| `not_linked` | 409 | เรียก `/api/otp/link/start` ด้วยผู้ใช้และ state เดิม |
| `invalid_client` | 401 | หยุด ตรวจ client id และ secret |
| `invalid_redirect_uri` | 400 | ทำให้ URI ตรงกับที่ลงทะเบียน |
| `invalid_code` | 400 | code ใช้แล้วหรือหมดอายุ เริ่ม start ใหม่ ห้ามส่ง code เดิมซ้ำ |
| `conflict` | 409 | บัญชีถูกผูกกับอีกฝ่ายแล้ว ห้ามเขียนทับ |
| `expired` | 410 | เริ่ม start ใหม่ |
| `rate_limited` | 429 | บอกผู้ใช้ให้รอ ห้ามวนเรียก start ซ้ำ |
| `too_many_attempts` | 429 | บอกผู้ใช้ให้เริ่มใหม่ ห้ามวนเรียก |
| `access_denied` | ที่ callback | ผู้ใช้ยกเลิกตอน 2FA — ล้างรายการที่ค้าง ห้ามสร้าง session |
| `doae_email_required` | — | บัญชีกรมยังไม่มีเมล `@doae.go.th` — บอกให้ไปเปิดที่ SSO |

### เสร็จเมื่อ (Step-up)

1. ไม่มีทางเข้าแอปด้วยรหัสผ่านอย่างเดียว — หลังรหัสผ่านต้องไป SSO ทุกครั้ง
2. session สมบูรณ์เกิดหลัง callback แลก code สำเร็จเท่านั้น
3. เส้น step-up ตรวจ `amr` มี `totp` หรือ `email` ก่อนสร้าง session
4. แอปไม่มีหน้า TOTP/OTP ของตัวเอง และไม่มี flag ปิด 2FA
5. บัญชีที่ยังไม่ผูกเจอ `not_linked` แล้วไปเส้น link ได้
6. ทั้งสอง callback ตรวจ `state` แล้วแลก code ที่เซิร์ฟเวอร์
7. แอปเก็บคู่ `local_user_id` ↔ `sso_user_id` และไม่คาดหวัง Bearer token
8. กรณี `conflict` ไม่มีการเปลี่ยนคู่บัญชีเดิม

---

## เมื่อยังไม่มี credential

หยุด แล้วบอกเจ้าของแอปให้สมัครเอง

- SSO เต็มรูปแบบ: เข้า `https://sso.doae.go.th` แล้วเปิดเมนูนำแอปเข้า SSO
- Step-up: เข้าบัญชีกรมก่อน แล้วเปิด `https://sso.doae.go.th/integration/apply`

secret แสดงครั้งเดียว ใส่ใน env ของเซิร์ฟเวอร์แอปนั้น ห้ามเขียนกลับมาในเอกสารนี้หรือในที่เก็บโค้ด
