外部驗證與電子郵件 - Netstamp 說明文件

設定通用 OIDC、Google、GitHub、SMTP、密碼重設與電子郵件驗證。

Netstamp 除了本機密碼，也支援通用 OpenID Connect、Google OpenID Connect 與 GitHub OAuth。外部身分提供者可用於登入、敏感操作前的近期身分確認，以及將外部身分連結到既有帳號。

先設定公開來源網址

啟用身分提供者前，先設定有效的 HTTPS 來源網址：

dotenv

BACKEND_BASE_URL=https://netstamp.example.com
PUBLIC_WEB_BASE_URL=https://netstamp.example.com

再到身分提供者註冊相符的回呼網址：

Provider	Callback URL
Generic OIDC	`https://netstamp.example.com/api/v1/auth/external/oidc/callback`
Google	`https://netstamp.example.com/api/v1/auth/external/google/callback`
GitHub	`https://netstamp.example.com/api/v1/auth/external/github/callback`

Generic OIDC

dotenv

AUTH_OIDC_ENABLED=true
AUTH_OIDC_ISSUER_URL=https://id.example.com
AUTH_OIDC_CLIENT_ID=netstamp
AUTH_OIDC_CLIENT_SECRET=<client secret>
AUTH_OIDC_DISPLAY_NAME=Company SSO
AUTH_OIDC_JIT_PROVISIONING_ENABLED=false

Issuer 必須提供有效的 OIDC discovery metadata。只有在該身分提供者接受的所有身分都可以建立 Netstamp 帳號時，才應啟用即時帳號建立（JIT provisioning）。

Google

dotenv

AUTH_GOOGLE_ENABLED=true
AUTH_GOOGLE_CLIENT_ID=<client id>
AUTH_GOOGLE_CLIENT_SECRET=<client secret>
AUTH_GOOGLE_DISPLAY_NAME=Google
AUTH_GOOGLE_JIT_PROVISIONING_ENABLED=false
AUTH_GOOGLE_ALLOWED_HOSTED_DOMAINS=example.com,subsidiary.example

AUTH_GOOGLE_ALLOWED_HOSTED_DOMAINS 是以逗號分隔的 hosted-domain claim 允許清單。只有在 Google 應用程式接受一般個人帳號，而且所有 Workspace 帳號都符合政策時，才應將它留空。

GitHub

dotenv

AUTH_GITHUB_ENABLED=true
AUTH_GITHUB_CLIENT_ID=<client id>
AUTH_GITHUB_CLIENT_SECRET=<client secret>
AUTH_GITHUB_DISPLAY_NAME=GitHub
AUTH_GITHUB_JIT_PROVISIONING_ENABLED=false
AUTH_GITHUB_ALLOW_SIGNUP=true

AUTH_GITHUB_ALLOW_SIGNUP 決定 GitHub 授權流程是否可以提供建立 GitHub 帳號的選項。是否能建立 Netstamp 帳號，則另外由 JIT 帳號建立設定與執行個體的註冊政策決定。

既有使用者與 JIT 帳號建立

初次設定時，先維持 JIT 帳號建立功能關閉。以第一位系統管理員登入，到帳號設定 → 登入方式連結外部身分；變更本機密碼或註冊政策前，先用無痕視窗實際測試外部登入。

JIT 帳號建立功能關閉時，尚未出現過的外部身分不能建立帳號；將該身分連結到既有使用者後，仍可正常登入。

SMTP

電子郵件通知、密碼重設與電子郵件驗證都需要 SMTP。可從系統管理 → 系統設定輸入，或使用下列環境變數作為備援值：

dotenv

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=netstamp
SMTP_PASSWORD=<smtp password>
[email protected]
SMTP_TLS_MODE=starttls
SMTP_TIMEOUT=10s

支援的 TLS 模式為 starttls、implicit 與 none。只有連線位於可信任的私有網路，而且已有其他傳輸層保護時，才可使用 none。

系統管理介面會將設定存入資料庫，並使用 SYSTEM_SETTINGS_ENCRYPTION_KEY 加密機密值。資料庫中的設定優先於環境變數備援值；請固定使用同一把加密金鑰，並妥善備份。

測試完整流程

在系統管理儲存 SMTP 設定。
到警示 → 通知建立 Email 通知並傳送測試訊息。
使用可拋棄的帳號請求密碼重設信。
若已要求驗證電子郵件，註冊一個可拋棄帳號並開啟驗證連結。
在登出後的無痕視窗逐一測試每個外部身分提供者。

在確認有另一條可用的復原途徑前，不要停用系統管理員最後一種仍可登入的驗證方式。