OAuth Integration Guide

Sense Sphere cung cấp hệ thống OAuth cho phép các partner web systems tích hợp xác thực người dùng một cách liền mạch. Người dùng có thể đăng nhập vào Sense Sphere và quay lại hệ thống partner với auth token mà không cần tạo tài khoản riêng.

SenseSphere OAuth Flow (/auth/sensesphere-auth/)

Tổng quan

Flow cho phép partner redirect user đến trang đăng nhập của Sense Sphere, sau đó redirect ngược lại với auth token.

Endpoint: GET /auth/sensesphere-auth/?partner_key=xxx&redirect_uri=yyy

Các bước thực hiện

1. Partner redirect user

GET https://sensesphere.ai/auth/sensesphere-auth/
    ?partner_key={partner_key}
    &redirect_uri={encoded_redirect_uri}

• partner_key: Key nhận diện partner (từ Partner.partner_key)
• redirect_uri: URL callback của partner, phải được validate

2. Validate partner + redirect URI

Hệ thống kiểm tra:

• partner_key tồn tại trong database
• redirect_uri khớp với allowed_redirect_uris (JSON array) HOẶC nằm trong allowed_redirect_domain

Nếu không hợp lệ → hiển thị lỗi "partner_key or redirect_uri is not registered".

3. User authentication

Trường hợp đã đăng nhập:

• Auto-auth: tạo Partner Auth Token ngay lập tức
• Redirect về redirect_uri với query params: token, user_id, created=false

Trường hợp chưa đăng nhập:

• Hiển thị trang sensesphere_oauth_page.html với form login/signup
• User nhập thông tin hoặc tạo tài khoản mới
• Sau khi thành công → redirect về partner callback

Signup qua OAuth

Khi user chưa có tài khoản Sense Sphere, họ có thể đăng ký trực tiếp từ trang OAuth:

POST params:

• action_type: "signup"
• partner_key, redirect_uri
• email, username, first_name, last_name

Quy trình:

1. Pre-check email/username uniqueness
2. Atomic create user với set_unusable_password() (login chỉ qua OAuth token)
3. Auto-login và tạo Partner Auth Token
4. Redirect về partner callback với created=true

Login qua OAuth

POST params:

• action_type: "login"
• partner_key, redirect_uri
• username (hoặc email), password

Quy trình:

1. Authenticate với username/email + password
2. Auto-login và tạo Partner Auth Token
3. Redirect về partner callback với created=false

Callback URL format

{redirect_uri}?token={token}&user_id={user_uuid}&created={true|false}

• token: Partner Auth Token value (dùng cho các API calls tiếp theo)
• user_id: UUID của user
• created: "true" nếu đây là signup mới, "false" nếu đã có tài khoản

---

Google OAuth Login (/auth/google/)

Tổng quan

Hỗ trợ đăng nhập bằng tài khoản Google OAuth2. Có thể kết hợp với partner context để redirect về hệ thống partner sau khi login.

Endpoints:

• GET /auth/google/ — Bắt đầu flow, redirect đến Google consent screen
• Callback: GET /auth/google/callback/ — Xử lý response từ Google

Flow (không có partner)

1. User click "Login with Google" → GET /auth/google/?next=/dashboard/
2. Sense Sphere redirect đến Google OAuth consent screen với:
   - client_id, redirect_uri, scope=openid email profile
   - state nonce để chống CSRF
3. User approve trên Google → redirect về /auth/google/callback/?code=xxx&state=yyy
4. Sense Sphere exchange code cho access token tại https://oauth2.googleapis.com/token
5. Fetch user info từ https://www.googleapis.com/oauth2/v3/userinfo
6. Kiểm tra email verified → tìm hoặc tạo user account
7. Auto-login và redirect về next URL (hoặc /dashboard/)

Flow (có partner)

Thêm query params vào bước 1:

GET /auth/google/?partner_key=xxx&redirect_uri=yyy&next=/dashboard/

Sau khi login thành công:

• Tạo Partner Auth Token
• Redirect về redirect_uri với token, user_id, created (tương tự SenseSphere OAuth)

Auto-account creation

Khi user mới chưa có tài khoản Sense Sphere:

• username: derived từ email local-part (với collision handling)
• password: random secure token (secrets.token_urlsafe(24)) — không dùng để login
• first_name, last_name: lấy từ Google profile
• Account được tạo với create_user() → email verified check trước khi tạo

Error handling

Các lỗi có thể xảy ra:

• oauth_error=Google+login+is+not+configured — OAuth chưa được setup
• oauth_error=Invalid+authentication+state — State nonce mismatch (CSRF protection)
• oauth_error=You+cancelled+Google+login — User hủy trên Google
• oauth_error=No+authentication+code+received+from+Google. — Không nhận được code
• oauth_error=Cannot+authenticate+with+Google. — Token exchange failed
• oauth_error=Google+did+not+return+an+access+token. — Missing access token
• oauth_error=Could+not+retrieve+Google+account+information. — Userinfo fetch failed
• oauth_error=Google+account+email+is+not+verified. — Email không verified
• oauth_error=Account+has+been+disabled. — Account bị disable

---

Partner Configuration (Admin)

Để thiết lập OAuth cho partner, admin cần cấu hình trong Partner model:

Priority: allowed_redirect_uris được ưu tiên hơn allowed_redirect_domain khi cả hai đều có giá trị.

---

Security Considerations

1. Redirect URI validation: Partner key + redirect_uri được validate 2 lần — tại start point và callback point (defense in depth)
2. State nonce: Google OAuth sử dụng state parameter để chống CSRF attacks
3. Token rotation: Mỗi khi tạo token mới, old tokens tự động bị revoke
4. Rate limiting: OAuth callback endpoint bị rate limit 10/m per IP; login view 5/m per IP

---

Trang liên quan

• Partner API Reference — Các endpoints cho partner systems
• FAQ — Câu hỏi thường gặp