Documentation

Bắt đầu

Authagonal cung cấp cho mỗi tenant một máy chủ OIDC tuân thủ đầy đủ tiêu chuẩn. Mỗi tenant có URL issuer riêng, tài liệu discovery và các điểm cuối token — không chia sẻ hạ tầng giữa các tenant. Bạn có thể từ số không đến luồng đăng nhập hoạt động trong chưa đầy 5 phút.

Tạo Tenant

Đăng ký tại authagonal.io và chọn một slug cho tenant. Slug trở thành tên miền issuer: {slug}.authagonal.io. Sau khi tạo tài khoản, xác minh địa chỉ email để kích hoạt tenant.

Chọn một slug duy nhất cho tenant trong quá trình đăng ký

Đăng ký Client

Điều hướng đến Ứng dụng trong thanh bên cổng và nhấp Tạo. Nhập clientId và clientName cho ứng dụng của bạn. Sau đó cấu hình ít nhất một URI chuyển hướng — đây là nơi người dùng được chuyển đến sau khi xác thực. Ví dụ: https://app.example.com/callback.

Đăng ký ứng dụng OAuth mới trong cổng

Đăng nhập đầu tiên

Cách nhanh nhất để tích hợp là với oidc-client-ts, một thư viện OIDC nhẹ cho ứng dụng JavaScript và TypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Nếu bạn muốn cách tiếp cận tối giản không cần thư viện, bạn có thể sử dụng luồng mã ủy quyền OAuth 2.0 tiêu chuẩn với fetch thuần:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

Trang đăng nhập mặc định cho tenant của bạn

Bảng điều khiển

Bảng điều khiển cổng cung cấp tổng quan thời gian thực về tenant. Nó hiển thị các chỉ số quan trọng nhất — tăng trưởng người dùng, hoạt động xác thực và điều hướng nhanh đến mọi tính năng trong cổng.

Tổng quan

Ở đầu bảng điều khiển, bạn sẽ thấy thông báo chào mừng cùng với tổng số người dùng hiện tại. Bên dưới, biểu đồ Người dùng hoạt động hàng ngày hiển thị lịch sử 7 ngày về người dùng duy nhất đã xác thực mỗi ngày, giúp bạn nắm nhanh xu hướng tương tác.

Màn hình chính bảng điều khiển với biểu đồ DAU và tổng quan hoạt động

Chỉ số hoạt động

Bảng chỉ số hoạt động hiển thị bốn thẻ thống kê tóm tắt các sự kiện xác thực chính:

• Đăng nhập thành công — tổng số luồng xác thực hoàn thành
• Đăng nhập thất bại — thông tin đăng nhập sai, tài khoản bị khóa hoặc bị từ chối bởi chính sách
• Người dùng hoạt động — người dùng duy nhất đã xác thực trong khoảng thời gian đã chọn
• Hoạt động SCIM — sự kiện cung cấp người dùng và nhóm từ các IdP đã kết nối

Sử dụng bộ lọc khoảng thời gian để chuyển đổi giữa 24 giờ, 3 ngày, 7 ngày và 30 ngày. Tất cả thẻ thống kê và biểu đồ cập nhật theo cửa sổ đã chọn.

Chỉ số hoạt động với khoảng thời gian có thể cấu hình

Điều hướng nhanh

Bên dưới bảng chỉ số, các thẻ điều hướng liên kết trực tiếp đến mọi tính năng chính: Ứng dụng, Người dùng, Nhóm, Vai trò, SSO, SCIM, Giao diện và Cài đặt. Mỗi thẻ hiển thị mô tả ngắn để thành viên mới nhanh chóng nắm bắt.

Ứng dụng

Các OAuth client đại diện cho ứng dụng xác thực người dùng qua tenant. Mỗi client có cấu hình riêng cho URI chuyển hướng, phạm vi, loại cấp quyền, thời hạn token và chính sách MFA.

Danh sách Client

Trang Ứng dụng hiển thị bảng tất cả client đã đăng ký. Mỗi hàng hiển thị clientId, tên hiển thị, các loại cấp quyền được phép dưới dạng huy hiệu màu và trạng thái PKCE. Nhấp vào bất kỳ hàng nào để mở trình chỉnh sửa cấu hình đầy đủ.

Danh sách client với huy hiệu loại cấp quyền và chỉ báo PKCE

Tạo Client

Nhấp Tạo Client để đăng ký ứng dụng mới. Bạn cần cung cấp hai trường:

• clientId — mã định danh duy nhất cho client (ví dụ: my-spa)
• clientName — tên hiển thị dễ đọc

Đăng ký ứng dụng OAuth mới

Xóa Client

Để xóa client, mở cấu hình client và nhấp nút Xóa Client ở cuối trang. Bạn sẽ được yêu cầu xác nhận trước khi client bị xóa vĩnh viễn. Tất cả phiên và token đang hoạt động cho client đã xóa sẽ bị vô hiệu hóa ngay lập tức.

Tham chiếu cấu hình Client

Mỗi client có bộ tùy chọn cấu hình toàn diện được tổ chức thành nhiều phần.

Cài đặt chung

URI

Các trường URI sử dụng nhập thẻ — nhập giá trị và nhấn Enter hoặc dấu phẩy để thêm. Nhấp X trên bất kỳ thẻ nào để xóa.

Trường nhập thẻ để cấu hình URI

Phạm vi & Loại cấp quyền

Thời hạn Token

Cấu hình thời hạn token theo từng client

URI đăng xuất

Client có thể đăng ký cả URI đăng xuất back-channel và front-channel. Cả hai đều tùy chọn — cấu hình loại phù hợp với cách ứng dụng của bạn xóa phiên.

Chính sách MFA

Mỗi client có thể ghi đè chính sách MFA toàn tenant bằng cài đặt riêng. Menu thả xuống chính sách MFA cung cấp ba tùy chọn:

Ghi đè chính sách MFA theo từng client

SSO doanh nghiệp

SSO doanh nghiệp cho phép khách hàng sử dụng nhà cung cấp danh tính riêng. Authagonal hỗ trợ cả liên kết SAML 2.0 và OIDC với định tuyến theo tên miền, để người dùng tự động được chuyển đến IdP chính xác dựa trên địa chỉ email.

Định tuyến SSO theo tên miền

Kết nối SAML 2.0

Để tạo kết nối SAML, điều hướng đến trang SSO và chọn tab SAML. Cung cấp các thông tin sau:

Khi bạn lưu kết nối, Authagonal tải tài liệu metadata và nhập chứng chỉ ký của IdP, URL điểm cuối SSO và định dạng mã định danh. Metadata được làm mới định kỳ để cập nhật xoay chứng chỉ.

Tạo kết nối SSO SAML 2.0

Kết nối OIDC

Để tạo kết nối liên kết OIDC, chọn tab OIDC và cung cấp:

Tạo kết nối liên kết OIDC

Định tuyến tên miền

Định tuyến tên miền tự động chuyển hướng người dùng đến nhà cung cấp danh tính chính xác dựa trên tên miền email. Khi người dùng nhập email trên trang đăng nhập, Authagonal kiểm tra phần tên miền (ví dụ: acme.com) có khớp với bất kỳ kết nối SSO nào đã cấu hình không. Nếu khớp, người dùng được chuyển hướng liền mạch đến IdP của tổ chức họ.

Định tuyến tên miền ánh xạ tên miền email đến nhà cung cấp danh tính

Cung cấp JIT

Theo mặc định, khi người dùng đăng nhập qua SSO lần đầu và chưa tồn tại trong tenant, Authagonal tự động tạo tài khoản (cung cấp Just-In-Time). Tính năng này có thể tắt cho từng kết nối bằng cách chọn Tắt cung cấp JIT khi tạo hoặc chỉnh sửa kết nối.

Khi cung cấp JIT bị tắt, chỉ người dùng đã được cung cấp trước — qua SCIM, trang Người dùng của cổng hoặc API — mới có thể đăng nhập qua kết nối đó. Người dùng không xác định nhận lỗi access_denied và được hướng dẫn liên hệ quản trị viên.

Người dùng

Trang Người dùng cho phép bạn quản lý tất cả người dùng cuối trong tenant. Bạn có thể tìm kiếm người dùng, xem chi tiết, tạo tài khoản mới và xem cách mỗi người dùng được cung cấp.

Tìm kiếm & Phân trang

Thanh tìm kiếm hỗ trợ lọc theo địa chỉ email hoặc ID người dùng. Tìm kiếm được debounce ở 300ms nên kết quả cập nhật khi bạn gõ mà không làm quá tải API. Kết quả được phân trang 50 người dùng mỗi trang — sử dụng điều khiển điều hướng ở cuối bảng để chuyển trang.

Bảng người dùng

Bảng người dùng hiển thị các cột sau cho mỗi người dùng:

Danh sách người dùng với thanh tìm kiếm và phân trang

Tạo người dùng

Nhấp Tạo người dùng để thêm người dùng cục bộ mới. Biểu mẫu yêu cầu:

Tạo người dùng cục bộ mới

Chi tiết người dùng

Nhấp vào bất kỳ hàng nào trong danh sách người dùng để mở trang chi tiết. Từ đó, bạn có thể chỉnh sửa hồ sơ, quản lý vai trò, đặt lại MFA, xem thuộc tính tùy chỉnh và xóa người dùng.

Hồ sơ

Chỉnh sửa email, họ/tên, điện thoại, công ty, ID bên ngoài và trạng thái hoạt động của người dùng. Thay đổi email phải giữ tính duy nhất trong tenant; API trả về email_in_use nếu đã được sử dụng.

Vai trò

Gán và gỡ vai trò được định nghĩa trên trang Vai trò. Thành viên vai trò xuất hiện trong ID token và access token khi client bật includeRolesInTokens.

Xác thực đa yếu tố

Xem mọi thông tin xác thực MFA đã đăng ký cho người dùng — ứng dụng xác thực (TOTP), WebAuthn/passkey và mã khôi phục — mỗi cái có dấu thời gian đăng ký và sử dụng gần nhất. Xóa thông tin xác thực riêng lẻ hoặc đặt lại tất cả MFA. Đặt lại buộc người dùng đăng ký lại khi đăng nhập tiếp theo.

Thuộc tính tùy chỉnh

Dữ liệu khóa/giá trị tùy ý gắn với người dùng. Khóa phải là duy nhất. Thuộc tính được phơi bày qua API hồ sơ người dùng và SCIM, và có thể được ánh xạ thành claim của access token bằng cách cấu hình userClaims của scope tùy chỉnh.

Xóa người dùng

Xóa vĩnh viễn người dùng và tất cả thông tin xác thực MFA của họ. Nhập email người dùng để xác nhận — không thể hoàn tác.

Nhóm

Nhóm cho phép bạn tổ chức người dùng và bao gồm thành viên nhóm trong token. Nhóm có thể được tạo thủ công trong cổng hoặc cung cấp tự động qua SCIM từ nhà cung cấp danh tính bên ngoài.

Danh sách nhóm

Trang Nhóm hiển thị tất cả nhóm trong tenant với thông tin sau:

Danh sách nhóm với chỉ báo nguồn

Tạo nhóm

Nhấp Tạo nhóm và nhập displayName cho nhóm. Tên nhóm nên mô tả rõ ràng và duy nhất trong tenant (ví dụ: "Engineering", "Billing Admins", "Beta Testers").

Chi tiết nhóm & Thành viên

Nhấp vào bất kỳ nhóm nào để mở xem chi tiết. Tại đây bạn có thể xem tất cả thành viên hiện tại và quản lý thành viên:

• Thêm thành viên — Nhập ID người dùng để thêm người dùng vào nhóm.
• Xóa thành viên — Nhấp nút xóa bên cạnh bất kỳ thành viên nào để xóa riêng lẻ.

Quản lý thành viên nhóm trong xem chi tiết

Nhóm trong Token

Khi includeGroupsInTokens được bật trên một client, ID token bao gồm claim groups chứa thành viên nhóm của người dùng. Mỗi mục bao gồm id và name của nhóm:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Vai trò

Vai trò hỗ trợ kiểm soát truy cập dựa trên vai trò (RBAC) trong ứng dụng. Định nghĩa vai trò trong Authagonal, gán cho người dùng và sử dụng claim roles trong token để thực thi ủy quyền trong logic ứng dụng.

Quản lý vai trò

Trang Vai trò hiển thị bảng tất cả vai trò đã định nghĩa với chỉnh sửa trực tiếp. Mỗi vai trò có:

Tạo vai trò

Nhấp Tạo vai trò và cung cấp tên và mô tả. Tên vai trò nên ngắn gọn và tuân theo quy ước đặt tên nhất quán trong ứng dụng (ví dụ: chữ thường với gạch ngang: billing-admin).

Chỉnh sửa trực tiếp

Vai trò hỗ trợ chỉnh sửa trực tiếp trong bảng. Nhấp biểu tượng bút chì trên bất kỳ vai trò nào để vào chế độ chỉnh sửa — các trường tên và mô tả trở nên chỉnh sửa được. Sửa đổi giá trị, sau đó nhấp biểu tượng dấu kiểm để lưu. Thay đổi có hiệu lực ngay lập tức.

Xóa vai trò

Nhấp biểu tượng xóa trên bất kỳ vai trò nào để xóa. Bạn sẽ được yêu cầu xác nhận trước khi vai trò bị xóa vĩnh viễn. Xóa vai trò không vô hiệu hóa hồi tố các token hiện có — vai trò sẽ vắng mặt trong token mới được phát hành sau khi xóa.

Chỉnh sửa trực tiếp vai trò trong bảng vai trò

Vai trò trong Token

Vai trò được gán cho người dùng được bao gồm dưới dạng claim roles trong ID token. Ứng dụng có thể đọc claim này để đưa ra quyết định ủy quyền:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "roles": ["admin", "billing-admin"]
}

Cung cấp SCIM

SCIM 2.0 (System for Cross-domain Identity Management) cho phép cung cấp người dùng và nhóm tự động từ các nhà cung cấp danh tính doanh nghiệp như Okta, Azure AD, OneLogin và JumpCloud. Khi được cấu hình, tài khoản người dùng và thành viên nhóm tự động được đồng bộ từ IdP upstream đến tenant Authagonal của bạn.

Đồng bộ vòng đời người dùng SCIM với cung cấp downstream

Các bước thiết lập

Làm theo các bước sau để bật cung cấp SCIM cho một client:

1. Chọn ứng dụng client — Chọn OAuth client mà cung cấp SCIM sẽ được liên kết.
2. Tạo token SCIM — Cung cấp mô tả và thời hạn tính bằng ngày, sau đó tạo token.
3. Sao chép token ngay — Giá trị token thô chỉ hiển thị một lần. Sao chép trước khi đóng hộp thoại.
4. Cấu hình IdP — Trong cài đặt SCIM của nhà cung cấp danh tính, nhập URL cơ sở và bearer token.
5. Kiểm tra đồng bộ người dùng — Kích hoạt đồng bộ thử từ IdP và xác minh người dùng xuất hiện trong cổng Authagonal.

URL cơ sở SCIM

Cấu hình nhà cung cấp danh tính với URL cơ sở sau:

https://{slug}.authagonal.io/scim/v2

Thay thế {slug} bằng slug tenant của bạn.

Trang thiết lập SCIM với tạo token

Quản lý Token

Token SCIM xác thực các yêu cầu cung cấp từ IdP. Bạn có thể quản lý nhiều token cho mỗi client:

Để thu hồi token, nhấp nút Thu hồi bên cạnh. Token bị thu hồi vẫn hiển thị trong danh sách cho mục đích kiểm toán nhưng ngay lập tức ngừng chấp nhận yêu cầu.

Quản lý token với chỉ báo token đang hoạt động và đã thu hồi

Kiểm tra kết nối

Xác minh tích hợp SCIM hoạt động bằng cách truy vấn điểm cuối ServiceProviderConfig:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Phản hồi thành công trả về tài liệu JSON mô tả các tính năng SCIM được hỗ trợ, bao gồm hoạt động hàng loạt, lọc và khả năng đổi mật khẩu.

Scope OAuth

Scope cho phép client yêu cầu các phần cụ thể của dữ liệu hoặc quyền của người dùng. Authagonal hỗ trợ cả scope OIDC chuẩn và scope tùy chỉnh bạn định nghĩa cho API của mình.

Scope tích hợp sẵn

Scope tùy chỉnh

Định nghĩa scope của riêng bạn trên trang Scope. Mỗi scope mô tả một quyền hoặc tài nguyên mà client có thể yêu cầu (ví dụ: billing.read, orders.write).

Claim tùy chỉnh trên token

Claim tùy chỉnh có hai phần. Nguồn là dữ liệu theo người dùng: mỗi AuthUser có một từ điển customAttributes mà bạn có thể nạp từ Portal (Users → người dùng → Custom Attributes), qua SCIM, hoặc qua hook provisioning TCC. Việc giải phóng theo từng scope: danh sách userClaims của mỗi scope nêu các khóa được phép rời máy chủ.

Khi một client yêu cầu các scope, Authagonal duyệt qua các scope đã cấp, hợp các danh sách userClaims của chúng và chỉ phát ra những khóa đó từ customAttributes của người dùng. Khóa không xác định bị âm thầm bỏ qua — một client không thể đọc một thuộc tính bằng cách đoán tên. Các claim OIDC chuẩn (sub, email, name, v.v.) tuân theo đặc tả và không chịu sự ràng buộc của whitelist.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Gán scope cho client

Thêm scope được phép trên tab Client → Scope & Grant. Client chỉ có thể yêu cầu những scope đã được cấp; scope không xác định sẽ bị từ chối với invalid_scope.

Giao diện

Tùy chỉnh giao diện trang đăng nhập của tenant. Cài đặt giao diện cho phép bạn phù hợp trải nghiệm xác thực với bản sắc thương hiệu sản phẩm — từ logo và màu sắc đến ghi đè CSS nâng cao.

Giao diện

Cài đặt giao diện với xem trước màu trực tiếp

Thông tin liên hệ

Bật/tắt trang đăng nhập

Kiểm soát các thành phần hiển thị trên trang đăng nhập tenant:

Ví dụ trang đăng nhập với giao diện tùy chỉnh

CSS tuỳ chỉnh

Để kiểm soát hoàn toàn giao diện trang đăng nhập, hãy cung cấp URL tệp CSS trong cài đặt thương hiệu. Tệp được tải sau các style mặc định nên luật của bạn có ưu tiên cao hơn.

Chế độ tối

Ứng dụng đăng nhập đi kèm với giao diện sáng, tối và theo hệ thống. Người dùng chọn từ công tắc trên trang đăng nhập; lựa chọn được giữ giữa các phiên. Khi ở chế độ system, SPA theo dõi prefers-color-scheme theo thời gian thực.

Giá trị sáng được khai báo tại :root; các ghi đè tối chỉ nằm trong .dark. Branding của tenant qua customCssUrl luôn thắng — màu sắc của bạn được giữ nguyên bất kể chủ đề người dùng.

Cài đặt

Cấu hình chính sách bảo mật toàn tenant, webhook và cài đặt môi trường. Các cài đặt này áp dụng toàn cục cho tất cả client trừ khi bị ghi đè ở cấp client.

Chính sách mật khẩu

Xác định yêu cầu độ phức tạp mật khẩu cho tất cả người dùng trong tenant:

Cấu hình chính sách mật khẩu

Chính sách MFA

Chính sách MFA toàn tenant đặt hành vi xác thực đa yếu tố mặc định. Các client riêng lẻ có thể ghi đè cài đặt này.

Phiên & Khóa tài khoản

Kiểm soát thời lượng phiên và hành vi khóa tài khoản:

Cấu hình phiên và khóa tài khoản

Webhook

Webhook cho phép phản ứng với các sự kiện xác thực theo thời gian thực. Hai sự kiện (onUserAuthenticated, onTokenIssued) có thể bắt buộc — mặc định chúng kích hoạt bất đồng bộ và không chặn người dùng, nhưng bạn có thể bật bắt buộc cho từng sự kiện để phản hồi không phải 2xx hoặc body {"allow": false} sẽ từ chối hành động. Các sự kiện còn lại là thông báo — luôn fire-and-forget, không bao giờ chặn.

Cài đặt webhook bổ sung:

Cấu hình sự kiện webhook

Xác minh webhook

Khi bất kỳ URL webhook nào được cấu hình, Authagonal tạo ra một khóa bí mật ký riêng cho từng tenant (một giá trị whsec_… hiển thị chỉ đọc tại Cài đặt → Webhook). Mỗi lần gửi đi đều mang một header X-Authagonal-Signature: t=<unix>,v1=<hex>, trong đó v1 là HMAC-SHA256(secret, "{t}.{body}") được tính trên body thô của yêu cầu. Hãy tính lại nó trên điểm cuối của bạn và so sánh theo thời gian hằng số để xác nhận rằng yêu cầu thực sự đến từ Authagonal và không bị giả mạo — và từ chối các lần gửi có t quá cũ để chặn tấn công phát lại.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Khung giờ bảo trì

Đặt khung giờ bảo trì ưa thích cho các hoạt động gián đoạn như xoay chứng chỉ và cập nhật hạ tầng. Chọn giờ UTC (0–23) — cổng cũng hiển thị thời gian tương đương theo múi giờ địa phương để thuận tiện.

Môi trường Sandbox

Môi trường sandbox là bản sao đầy đủ của tenant production, có sẵn tại URL riêng. Sử dụng để kiểm tra thay đổi cấu hình, tích hợp SSO và điểm cuối webhook mà không ảnh hưởng người dùng thực.

Sandbox có thể truy cập tại {slug}-sandbox.authagonal.io.

Điều khiển môi trường sandbox

Thanh toán

Quản lý đăng ký và thanh toán qua trang Thanh toán của cổng. Trang này cung cấp tổng quan về gói hiện tại và truy cập cổng thanh toán Stripe để quản lý phương thức thanh toán, hóa đơn và thay đổi gói.

Thông tin đăng ký

Trang thanh toán hiển thị chi tiết đăng ký hiện tại một cách nhanh chóng. Bạn sẽ thấy huy hiệu trạng thái cho biết trạng thái đăng ký — active, trialing, past_due, canceled hoặc unpaid — cùng với tên gói, kỳ thanh toán hiện tại (ngày bắt đầu và kết thúc) và liệu đăng ký có được đặt hủy vào cuối kỳ hiện tại hay không.

Quản lý đăng ký

Nhấp nút Quản lý đăng ký để mở cổng thanh toán Stripe trong cửa sổ mới. Từ đó bạn có thể cập nhật phương thức thanh toán, xem và tải hóa đơn, thay đổi gói hoặc hủy đăng ký.

Nếu chưa có đăng ký, nút Thiết lập thanh toán sẽ hiển thị thay thế, hướng dẫn bạn chọn gói và nhập thông tin thanh toán.

Trang thanh toán hiển thị chi tiết đăng ký hiện tại và cung cấp truy cập Stripe

Tên miền tùy chỉnh

Phục vụ trang xác thực từ tên miền riêng (ví dụ: auth.yourdomain.com) thay vì mặc định {slug}.authagonal.io. Tên miền tùy chỉnh mang lại trải nghiệm xác thực liền mạch, mang thương hiệu cho người dùng.

Thêm tên miền

Nhập hostname bạn muốn sử dụng trong biểu mẫu thêm tên miền (ví dụ: auth.yourdomain.com). Sau khi thêm, tên miền sẽ xuất hiện trong danh sách với trạng thái pending_verification.

Xác minh DNS

Tạo bản ghi CNAME trỏ tên miền đến {slug}.authagonal.io. Khi bản ghi DNS đã sẵn sàng, nhấp Xác minh để kiểm tra lan truyền DNS.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

Chứng chỉ TLS

Khi tên miền đã được xác minh, bạn cần chứng chỉ TLS để người dùng kết nối an toàn qua HTTPS. Authagonal hỗ trợ hai tùy chọn:

Tự động (cert-manager) — Authagonal cung cấp và gia hạn chứng chỉ TLS tự động bằng cert-manager. Đây là tùy chọn được khuyến nghị cho hầu hết người dùng. Không cần cấu hình thêm.

Mang chứng chỉ riêng (BYO) — Tải lên chứng chỉ và khóa riêng ở định dạng PEM. Tùy chọn này hữu ích nếu tổ chức yêu cầu chứng chỉ từ cơ quan chứng nhận cụ thể. Hạn chứng chỉ được theo dõi để bạn có thể gia hạn trước khi hết hạn.

Trạng thái tên miền

Mỗi tên miền hiển thị huy hiệu trạng thái cho biết trạng thái hiện tại: pending_verification (DNS chưa xác nhận), verified (DNS đã xác nhận, TLS đang chờ), active (hoạt động đầy đủ) hoặc failed (phát hiện lỗi cấu hình).

Danh sách tên miền hiển thị mỗi tên miền tùy chỉnh và trạng thái hiện tại

Tải lên chứng chỉ TLS và khóa riêng ở định dạng PEM

Cấu hình e-mail

Cấu hình cách tenant gửi e-mail giao dịch — xác minh, đặt lại mật khẩu và thông báo MFA. Chọn giữa người gửi chia sẻ mặc định, tên miền tuỳ chỉnh đã xác minh qua Resend, hoặc máy chủ SMTP của riêng bạn.

Nhà cung cấp e-mail

Danh tính người gửi

E-mail và tên người gửi được dùng chung cho mọi chế độ nhà cung cấp. E-mail người gửi là bắt buộc; nếu tên trống, sẽ lùi về tên của tenant.

Tên miền tuỳ chỉnh Resend

Xác minh tên miền gửi với Resend một lần, sau đó dùng làm địa chỉ From cho tenant. Các bản ghi DNS TXT (SPF, DKIM) được cung cấp ở trang Tên miền; Resend sẽ tự động xác thực.

SMTP tuỳ chỉnh

Mang máy chủ SMTP của riêng bạn — hữu ích cho relay nội bộ, nhà cung cấp không nằm trong Resend hoặc ghim theo quy định.

Tên miền gửi tuỳ chỉnh

Khi dùng nhà cung cấp Resend, bạn có thể đăng ký tên miền riêng để e-mail gửi từ thương hiệu của bạn (ví dụ noreply@acme.com) thay vì @authagonal.io.

1. Vào Cài đặt → E-mail và chọn nhà cung cấp Resend Custom Domain.
2. Nhập tên miền và nhấn Đăng ký.
3. Thêm các bản ghi DNS được hiển thị (DKIM, SPF và return path) vào DNS của tên miền.
4. Nhấn Kiểm tra xác minh — sau khi DNS lan truyền (thường 1–10 phút), trạng thái tên miền sẽ chuyển thành đã xác minh.

Kiểm thử

Dùng nút Gửi e-mail thử nghiệm trong Cài đặt → E-mail để xác minh cấu hình. Một e-mail thử nghiệm sẽ được gửi tới địa chỉ quản trị của bạn với cài đặt hiện đã lưu.

Nhật ký kiểm toán

Nhật ký kiểm toán cung cấp bản ghi chỉ đọc về tất cả hành động quản trị được thực hiện trên tenant. Mọi thay đổi qua cổng hoặc API đều được ghi lại với đầy đủ ngữ cảnh, cung cấp dấu vết hoàn chỉnh cho tuân thủ và khắc phục sự cố.

Các cột nhật ký

Hành động được theo dõi

Các hành động quản trị sau được ghi trong nhật ký kiểm toán:

Nhật ký kiểm toán cung cấp bản ghi đầy đủ về tất cả hành động quản trị

Sao lưu

Authagonal tự động sao lưu dữ liệu tenant của bạn theo lịch hàng giờ. Bản sao lưu bao gồm tất cả người dùng, nhóm, vai trò, client, kết nối SSO, token SCIM, thương hiệu và cài đặt. Bạn có thể xem lịch sử sao lưu và tải xuống bản sao lưu đầy đủ mới nhất từ trang Sao lưu.

Cách sao lưu hoạt động

• Bản sao lưu đầy đủ chạy mỗi ngày một lần, thu thập mọi bảng trong shard lưu trữ của tenant.
• Bản sao lưu tăng dần chạy hàng giờ, chỉ thu thập các hàng thay đổi kể từ lần sao lưu cuối cùng.
• Bản sao lưu được lưu trong Azure Blob Storage với cùng danh tính được quản lý mà tenant của bạn sử dụng.
• Các bản ghi đã xoá được theo dõi qua tombstone và được đưa vào bản sao lưu để đảm bảo tính đầy đủ cho kiểm tra.

Tải xuống bản sao lưu

Nhấn "Tải mới nhất" để lấy tệp ZIP chứa bản sao lưu đầy đủ mới nhất được ghép với tất cả các bản tăng dần sau đó. Mỗi bảng được xuất ra tệp JSONL (mỗi dòng là một đối tượng JSON).

Ứng dụng cung cấp

Ứng dụng cung cấp nhận thông báo webhook thời gian thực khi người dùng được tạo hoặc xác thực trong tenant. Điều này cho phép hệ thống downstream tự động thiết lập tài khoản, gán giấy phép hoặc đồng bộ dữ liệu người dùng mà không cần can thiệp thủ công.

Cách hoạt động

Khi sự kiện người dùng xảy ra (tạo hoặc xác thực), Authagonal gọi URL callback của ứng dụng cung cấp bằng mẫu TCC (Try/Confirm/Cancel). Cách tiếp cận ba giai đoạn này đảm bảo cung cấp đáng tin cậy qua nhiều hệ thống downstream:

Payload Webhook

Mỗi yêu cầu webhook bao gồm payload JSON với các trường sau:

Thêm ứng dụng cung cấp

Để thêm ứng dụng cung cấp, cung cấp tên, URL callback và khóa API tùy chọn. Khóa API được gửi dưới dạng Bearer token trong header Authorization của mỗi yêu cầu webhook, cho phép ứng dụng xác thực yêu cầu từ Authagonal.

Kiểm tra

Nhấp Kiểm tra bên cạnh bất kỳ ứng dụng cung cấp nào để gửi yêu cầu thử đến URL callback. Kết quả kiểm tra hiển thị mã trạng thái HTTP và nội dung phản hồi, giúp bạn xác minh ứng dụng nhận và xử lý webhook chính xác.

Kiểm tra ứng dụng cung cấp để xác minh gửi và xử lý webhook

Giới hạn gói

Số lượng ứng dụng cung cấp tối đa có thể cấu hình cho mỗi tenant, với giới hạn mặc định là 6. Giới hạn này có thể được điều chỉnh bởi quản trị viên nếu quy trình của bạn cần thêm mục tiêu cung cấp.

Nhóm quản trị

Trang Nhóm quản trị quản lý các quản trị viên cổng — những người có thể truy cập và cấu hình tenant qua cổng quản lý. Tất cả thành viên nhóm đều có quyền quản trị đầy đủ đối với mọi khía cạnh cấu hình tenant.

Danh sách quản trị viên

Danh sách quản trị viên hiển thị tên, địa chỉ email và ngày thêm của mỗi thành viên. Chỉ báo "Bạn" được hiển thị bên cạnh hàng của người dùng hiện tại để bạn dễ dàng nhận ra tài khoản của mình.

Mời quản trị viên

Để mời thành viên mới, cung cấp địa chỉ email, tên và mật khẩu tạm thời (tối thiểu 8 ký tự). Người được mời đăng nhập bằng mật khẩu tạm thời và nên đổi mật khẩu ngay lần đăng nhập đầu.

Trường mời

Lời mời quản trị viên tạo người dùng đã được cấp phát đầy đủ — không cần email vòng lại.

Xóa quản trị viên

Nhấp Xóa bên cạnh bất kỳ thành viên nào để thu hồi quyền truy cập. Hộp thoại xác nhận được hiển thị trước khi hoàn tất xóa. Bạn không thể tự xóa mình — luôn phải có ít nhất một quản trị viên trong nhóm.

Quản lý quản trị viên cổng từ trang Nhóm quản trị

Nhập & di chuyển

Di chuyển một hệ thống định danh hiện có vào tenant Authagonal của bạn. Hỗ trợ hai nguồn — Duende IdentityServer (một cơ sở dữ liệu SQL Server) và Auth0 (Management API). Mỗi nguồn chạy một bản xem trước chỉ đọc để bạn xem chính xác những gì sẽ được sao chép trước khi xác nhận.

Nhập từ Duende IdentityServer

Chuyển clients, scopes, người dùng và vai trò từ một cơ sở dữ liệu SQL Server Duende IdentityServer hiện có sang tenant Authagonal của bạn. Quá trình nhập chạy theo hai giai đoạn — xem trước và commit — để bạn xem xét những gì sẽ được sao chép trước khi có bất kỳ thay đổi nào.

Những gì được nhập

Trình nhập đọc ConfigurationDb của Duende và các bảng ASP.NET Identity rồi ghi các hàng đã ánh xạ vào tenant của bạn. Các thành phần ngắn hạn như persisted grants, device codes và khóa ký được bỏ qua.

Xem trước trước khi commit

Dán chuỗi kết nối ConfigurationDb / IdentityDb Duende của bạn và nhấn Chạy xem trước. Xem trước mở kết nối chỉ đọc và đếm từng hàng sẽ được nhập — không ghi gì cả.

• Số lượng đối tượng cho clients, scopes, người dùng, vai trò và phân công vai trò.
• Xung đột chủ sở hữu — quản trị viên tenant có <code>userId</code> hiện tại khác với <code>sub</code> từ Duende.
• Cảnh báo về bảng không xác định và cột không được ánh xạ để bạn biết dữ liệu nào sẽ bị bỏ.

Bảng xem trước với số liệu, xung đột và cảnh báo

Hash mật khẩu

Duende lưu mật khẩu bằng ASP.NET Identity V3 (PBKDF2). PasswordHasher của Authagonal xác minh trực tiếp định dạng đó và re-hash sang định dạng bản địa ở lần đăng nhập thành công đầu tiên — người dùng giữ nguyên mật khẩu cũ mà không cần quy trình đặt lại.

Luân chuyển userId chủ sở hữu

Nếu email của quản trị viên tenant khớp với người dùng trong cơ sở dữ liệu Duende, userId Authagonal của quản trị viên đó sẽ được xoay để trùng với sub từ Duende. Điều này giữ cho token và bản ghi kiểm toán nhất quán sau khi chuyển đổi. Xem trước liệt kê mọi xung đột trước khi commit.

Chạy quá trình nhập

Nhấn Bắt đầu nhập sau khi xem lại bản xem trước. Giai đoạn commit ghi clients, scopes, người dùng, vai trò và tham chiếu đăng nhập bên ngoài vào các store của tenant. Các hàng trùng clientId, scope name, email và role name bị bỏ qua — có thể chạy lại trình nhập an toàn.

Những gì không được nhập

• Persisted grants, device codes, session máy chủ — ngắn hạn, được tạo lại tự động.
• Khóa ký — Authagonal phát hành khóa riêng cho mỗi tenant.
• Cột và bảng tùy chỉnh — mọi thứ ngoài schema chuẩn của Duende sẽ hiện dưới dạng cảnh báo để bạn biết dữ liệu đó đã bị bỏ.
• Clients bị tắt — được nhập ở trạng thái tắt; bật lại từ trang Clients khi cần.

Nhập từ Auth0

Kết nối Authagonal với Management API của tenant Auth0 và mang theo các ứng dụng, API, vai trò, người dùng và kết nối doanh nghiệp của bạn. ID người dùng và ứng dụng được nhập sẽ được giữ nguyên, nên các tham chiếu sub và client_id hiện có vẫn phân giải được sau khi chuyển đổi.

Những gì bạn cần

Tạo một ứng dụng Machine-to-Machine trong Auth0 được ủy quyền cho Management API, với các scope đọc sau: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Dán domain, client ID và client secret của nó vào biểu mẫu nhập — chúng chỉ được dùng cho việc nhập.

Những gì được nhập

Mật khẩu

Management API của Auth0 không bao giờ trả về hash mật khẩu. Nếu bạn có bản xuất mật khẩu hàng loạt được bộ phận hỗ trợ của Auth0 trợ giúp (NDJSON), hãy cung cấp nó — các hash bcrypt được nhập nguyên vẹn và người dùng giữ nguyên mật khẩu mà không cần đặt lại. Tệp đó cũng chứa toàn bộ tập người dùng của bạn, gỡ bỏ giới hạn liệt kê 1.000 người dùng của API Auth0. Không có nó, người dùng được nhập dưới dạng hồ sơ và đặt mật khẩu mới ở lần đăng nhập đầu tiên.

Tham chiếu API

Mỗi tenant cung cấp một máy chủ OIDC tuân thủ tiêu chuẩn tại https://{slug}.authagonal.io. Tất cả điểm cuối tuân theo đặc tả OAuth 2.0 và OpenID Connect. Tham chiếu này bao gồm mọi điểm cuối mà ứng dụng của bạn có thể cần tương tác.

Luồng Authorization Code với PKCE

OIDC Discovery & JWKS

Tài liệu discovery cho phép thư viện OIDC client tự động cấu hình. Không cần xác thực cho cả hai điểm cuối.

GET /.well-known/openid-configuration

Trả về tài liệu cấu hình OpenID Provider. Phản hồi bao gồm tất cả metadata mà client cần để tương tác với tenant này.

GET /.well-known/openid-configuration/jwks

Trả về JSON Web Key Set dùng để xác minh chữ ký token. Phản hồi chứa mảng keys với các khóa công khai RSA, mỗi khóa bao gồm các trường kty, use, kid, alg, n và e.

curl https://acme.authagonal.io/.well-known/openid-configuration

Điểm cuối Authorization

GET /connect/authorize

Khởi tạo luồng mã ủy quyền. Người dùng phải có phiên đang hoạt động hoặc sẽ được chuyển hướng đến trang đăng nhập. Khi thành công, người dùng được chuyển hướng trở lại ứng dụng với mã ủy quyền.

Phản hồi thành công: Chuyển hướng 302 đến redirect_uri với tham số truy vấn code và state.

Phản hồi lỗi: Chuyển hướng 302 với tham số truy vấn error, error_description và state.

Pushed Authorization Requests (PAR)

RFC 9126. Thay vì đặt mọi tham số authorize trên URL, client của bạn POST chúng tới /connect/par với xác thực client thông thường và nhận lại một request_uri mờ đục, có thời gian sống ngắn. Trình duyệt sau đó truy cập /connect/authorize?client_id=...&request_uri=... — không có thông tin nào khác lọt vào lịch sử trình duyệt, log máy chủ hay header Referer, và máy chủ đã xác minh tính toàn vẹn của tham số dưới quyền xác thực client.

POST /connect/par

Xác thực client giống với /connect/token: HTTP Basic với client_id/client_secret, hoặc thông tin đăng nhập mã hóa trong form. Public client gửi không cần secret. Body chứa các tham số bạn vẫn gửi tới /connect/authorize; bản thân request_uri bị từ chối (nối chuỗi PAR bị cấm theo §2.1 của đặc tả). Trả về 201 Created.

Phản hồi

Ở lệnh tiếp theo GET /connect/authorize?client_id=…&request_uri=…, mọi tham số khác được lấy từ payload đã đẩy và mọi tham số query thừa bị bỏ qua. client_id ở lệnh authorize phải khớp với client đã đẩy yêu cầu. Sau khi được tiêu thụ (hoặc khi expires_in hết hạn), request_uri bị xóa khỏi kho lưu trữ.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Điểm cuối Token

POST /connect/token

Trao đổi thông tin xác thực lấy token. Yêu cầu phải sử dụng Content-Type: application/x-www-form-urlencoded. Xác thực client có thể thông qua HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) hoặc dưới dạng tham số trong phần thân biểu mẫu (client_id + client_secret).

Cấp quyền Authorization Code

Cấp quyền Refresh Token

Cấp quyền Client Credentials

Cấp quyền Device Code

Phản hồi token:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Điểm cuối UserInfo

GET /connect/userinfo

Trả về claims về người dùng đã xác thực. Yêu cầu access token hợp lệ với phạm vi openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token Introspection (RFC 7662)

POST /connect/introspect

Xác thực token và trả về metadata. Yêu cầu thông tin xác thực client (Basic auth hoặc tham số phần thân biểu mẫu).

Phản hồi token đang hoạt động:

Phản hồi token không hoạt động: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Thu hồi Token (RFC 7009)

POST /connect/revocation

Thu hồi token đã cấp trước đó. Yêu cầu thông tin xác thực client.

Điểm cuối luôn trả về 200 OK, ngay cả với token không hợp lệ hoặc đã bị thu hồi, theo đặc tả RFC 7009.

Ủy quyền Thiết bị (RFC 8628)

POST /connect/deviceauthorization

Khởi tạo luồng ủy quyền thiết bị cho các thiết bị hạn chế đầu vào (CLI, smart TV, thiết bị IoT). Thiết bị hiển thị mã cho người dùng, người dùng sau đó phê duyệt yêu cầu trên thiết bị khác có trình duyệt.

Phản hồi:

Luồng phê duyệt: Người dùng truy cập verification_uri, nhập user_code và phê duyệt yêu cầu. Trong khi đó, thiết bị polling điểm cuối token với device_code.

Mã lỗi polling:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Kết thúc Phiên / Đăng xuất

GET POST /connect/endsession

Đăng xuất phiên người dùng hiện tại, kích hoạt đăng xuất back-channel đến tất cả client có BackChannelLogoutUri đã đăng ký, và thu hồi tất cả quyền cấp.

Nếu post_logout_redirect_uri hợp lệ được cung cấp và khớp với URI đã đăng ký, người dùng nhận chuyển hướng 302. Ngược lại, phản hồi JSON xác nhận phiên đã kết thúc.

Tham chiếu SCIM 2.0 API

Authagonal hỗ trợ giao thức SCIM 2.0 cho cung cấp người dùng và nhóm tự động. Các nhà cung cấp danh tính như Okta, Azure AD và OneLogin có thể sử dụng API này để giữ tenant Authagonal đồng bộ với thư mục doanh nghiệp.

URL cơ sở: https://{slug}.authagonal.io/scim/v2

Xác thực: Tất cả yêu cầu cần Bearer token. Tạo token SCIM trong cổng tại Cài đặt > Cung cấp SCIM.

Header chung:

Các điểm cuối danh sách hỗ trợ phân trang qua tham số truy vấn startIndex (bắt đầu từ 1) và count (tối đa 200), và lọc qua tham số filter (ví dụ: userName eq "user@example.com").

Người dùng

GET /scim/v2/Users — Liệt kê người dùng với phân trang và lọc tùy chọn.

GET /scim/v2/Users/{id} — Lấy một người dùng theo ID người dùng Authagonal.

POST /scim/v2/Users — Tạo người dùng mới. Trả về 201 Created.

PUT /scim/v2/Users/{id} — Thay thế toàn bộ tài nguyên người dùng. Tất cả trường phải được cung cấp.

PATCH /scim/v2/Users/{id} — Cập nhật một phần bằng SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Xóa mềm người dùng (vô hiệu hóa tài khoản và thu hồi tất cả token). Trả về 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Nhóm

GET /scim/v2/Groups — Liệt kê tất cả nhóm với phân trang và lọc tùy chọn.

GET /scim/v2/Groups/{id} — Lấy một nhóm theo ID, bao gồm danh sách thành viên.

POST /scim/v2/Groups — Tạo nhóm mới. Trả về 201 Created.

PUT /scim/v2/Groups/{id} — Thay thế toàn bộ tài nguyên nhóm (bao gồm danh sách thành viên).

PATCH /scim/v2/Groups/{id} — Cập nhật một phần để thêm hoặc xóa thành viên nhóm.

DELETE /scim/v2/Groups/{id} — Xóa cứng nhóm. Trả về 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API (tự động hóa)

Portal API cho phép backend của riêng bạn tự động hóa mọi thao tác bạn có thể làm trong cổng — quản lý người dùng, client, nhóm, vai trò, scope, kết nối SSO và cài đặt — bằng thông tin xác thực máy-tới-máy. Đây chính là API mà giao diện cổng gọi.

URL gốc: https://portal-api.<your-domain>/api/v1. Yêu cầu xác thực bằng access token Bearer; tenant được lấy từ token, không phải từ URL.

Tạo thông tin xác thực API

Trong cổng, mở Clients → Create API credential, chọn một cấp truy cập và đặt tên. Authagonal tạo một client OAuth client_credentials được kết nối sẵn cho Portal API và trả về một client ID cùng secret.

Các cấp truy cập

Lấy token

Đổi thông tin xác thực lấy access token tại điểm cuối token của tenant quản trị của bạn — https://<your-tenant>.<your-domain>/connect/token — rồi gửi token dưới dạng header Bearer đến Portal API. Token có hiệu lực trong một giờ.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Điểm cuối

Tất cả các đường dẫn đều tương đối so với URL cơ sở và yêu cầu mã thông báo truy cập Bearer. Phạm vi (scope) bên cạnh mỗi nhóm là cấp truy cập tối thiểu mà thông tin xác thực cần. Các điểm cuối danh sách chấp nhận tham số truy vấn startIndex và count.

GET/api/v1/clients— Liệt kê các client OAuth.

GET/api/v1/clients/{id}— Lấy một client theo ID.

POST/api/v1/clients— Tạo một client. Trả về ID client và, đối với client bảo mật, một secret dùng một lần.

PUT/api/v1/clients/{id}— Cập nhật một client (redirect URI, loại grant, thời hạn token, yêu cầu PKCE/PAR).

DELETE/api/v1/clients/{id}— Xóa một client.

POST/api/v1/clients/api-credential— Tạo thông tin xác thực Portal API máy-với-máy.

GET/api/v1/users— Liệt kê người dùng. Hỗ trợ startIndex, count và search (tiền tố email / tên).

GET/api/v1/users/count— Tổng số người dùng của tenant.

GET/api/v1/users/stats/mfa— Thống kê đăng ký MFA.

GET/api/v1/users/{id}— Lấy một người dùng.

POST/api/v1/users— Tạo người dùng với email và mật khẩu.

PUT/api/v1/users/{id}— Cập nhật người dùng (hồ sơ, email, trạng thái bật/chặn).

DELETE/api/v1/users/{id}— Xóa một người dùng.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Liệt kê vai trò.

POST/api/v1/roles— Tạo vai trò.

DELETE/api/v1/roles/{id}— Xóa vai trò.

POST/api/v1/roles/assign— Gán vai trò cho người dùng.

POST/api/v1/roles/unassign— Gỡ vai trò khỏi người dùng.

GET/api/v1/groups— Liệt kê nhóm.

GET/api/v1/groups/{id}— Lấy một nhóm cùng các thành viên.

POST/api/v1/groups— Tạo nhóm.

POST/api/v1/groups/{id}/members— Thêm thành viên vào nhóm.

DELETE/api/v1/groups/{groupId}/members/{userId}— Gỡ một thành viên khỏi nhóm.

DELETE/api/v1/groups/{id}— Xóa nhóm.

GET/api/v1/group-role-mappings— Liệt kê ánh xạ nhóm-đến-vai-trò (vai trò được cấp khi phát hành token theo tư cách thành viên nhóm).

GET/api/v1/scopes— Liệt kê các scope API.

POST/api/v1/scopes— Tạo một scope.

DELETE/api/v1/scopes/{name}— Xóa một scope.

GET/api/v1/saml/connections— Liệt kê kết nối SAML.

POST/api/v1/saml/connections— Tạo kết nối SAML.

DELETE/api/v1/saml/connections/{id}— Xóa kết nối SAML.

GET/api/v1/oidc/connections— Liệt kê kết nối OIDC.

POST/api/v1/oidc/connections— Tạo kết nối OIDC.

DELETE/api/v1/oidc/connections/{id}— Xóa kết nối OIDC.

GET/api/v1/sso/domains— Liệt kê các tên miền được định tuyến đến kết nối SSO (home-realm discovery).

GET/api/v1/branding— Lấy thương hiệu của tenant (màu sắc, logo, ngôn ngữ được hỗ trợ).

PUT/api/v1/branding— Cập nhật thương hiệu của tenant.

GET/api/v1/settings— Lấy cài đặt tenant (webhook, đăng ký công khai, chính sách token).

PUT/api/v1/settings— Cập nhật cài đặt tenant.

POST/api/v1/settings/webhook-secret/regenerate— Xoay secret ký webhook.

POST/api/v1/settings/test-email— Gửi email thử nghiệm với cấu hình email hiện tại.

GET/api/v1/custom-domains— Liệt kê tên miền đăng nhập tùy chỉnh và trạng thái xác minh.

POST/api/v1/custom-domains— Thêm tên miền tùy chỉnh.

POST/api/v1/custom-domains/{domain}/verify— Kích hoạt xác minh DNS cho tên miền tùy chỉnh.

DELETE/api/v1/custom-domains/{domain}— Gỡ tên miền tùy chỉnh.

GET/api/v1/email/domains— Liệt kê tên miền email người gửi.

GET/api/v1/audit— Truy vấn nhật ký kiểm toán của tenant.

Ví dụ: tạo người dùng

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.com",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "ada@acme.com" }

Luồng xác thực

Luồng xác thực bao gồm cách người dùng cuối tương tác với tenant Authagonal — đăng nhập, đăng ký, đặt lại mật khẩu và thiết lập MFA. Các điểm cuối này được sử dụng bởi trang đăng nhập được lưu trữ và có thể được gọi trực tiếp nếu bạn đang xây dựng giao diện đăng nhập tùy chỉnh.

Đăng nhập

POST /api/auth/login

Xác thực người dùng bằng email và mật khẩu. Khi thành công, ký cookie phiên và trả về hồ sơ người dùng. Nếu MFA được cấu hình, phản hồi cho biết yếu tố thứ hai được yêu cầu trước khi phiên được thiết lập hoàn toàn.

Phần thân yêu cầu:

{
  "email": "user@example.com",
  "password": "correct-horse-battery-staple"
}

Phản hồi thành công:

Phản hồi yêu cầu MFA: Khi người dùng đã đăng ký MFA, phản hồi bao gồm mfaRequired: true cùng với challengeId và mảng methods liệt kê các phương thức MFA khả dụng.

Phản hồi yêu cầu thiết lập MFA: Khi tenant yêu cầu MFA nhưng người dùng chưa đăng ký, phản hồi bao gồm mfaSetupRequired: true với setupToken cho luồng đăng ký.

Phản hồi lỗi:

Kiểm tra SSO: Nếu tên miền email của người dùng đã cấu hình kết nối SSO, điểm cuối đăng nhập trả về sso_required với redirectUrl. Client nên chuyển hướng người dùng đến nhà cung cấp SSO.

Khóa tài khoản: Sau maxFailedAttempts lần đăng nhập thất bại liên tiếp, tài khoản bị khóa trong lockoutDurationMinutes. Cả hai giá trị đều có thể cấu hình trong cài đặt tenant.

Đăng ký

POST /api/auth/register

Tạo tài khoản người dùng mới. Email xác minh được gửi tự động — người dùng phải xác minh email trước khi đăng nhập.

Phần thân yêu cầu:

{
  "email": "newuser@example.com",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Thành công: 201 Created với userId của tài khoản mới.

Phản hồi lỗi:

Đặt lại mật khẩu

POST /api/auth/forgot-password

Yêu cầu email đặt lại mật khẩu. Điểm cuối luôn trả về phản hồi thành công bất kể email có tồn tại hay không, để ngăn chặn liệt kê email.

{
  "email": "user@example.com"
}

POST /api/auth/reset-password

Đặt lại mật khẩu người dùng bằng token từ liên kết email.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Tác dụng phụ của việc đặt lại mật khẩu thành công:

• Bộ đếm đăng nhập thất bại được đặt lại về không
• Tất cả refresh token hiện có bị thu hồi
• Dấu bảo mật mới được tạo (vô hiệu hóa tất cả phiên hiện có)

Thiết lập & Xác minh MFA

Authagonal hỗ trợ ba phương thức MFA: TOTP (ứng dụng xác thực), WebAuthn (khóa bảo mật và sinh trắc học) và mã khôi phục dùng một lần.

Thiết lập TOTP

POST /api/auth/mfa/totp/setup — Trả về URI dữ liệu mã QR và khóa nhập thủ công. Người dùng quét mã QR bằng ứng dụng xác thực (Google Authenticator, Authy, 1Password, v.v.), sau đó xác nhận đăng ký.

POST /api/auth/mfa/totp/confirm — Xác nhận đăng ký TOTP bằng cách xác thực mã 6 chữ số từ ứng dụng xác thực.

{
  "code": "123456"
}

Thiết lập WebAuthn

POST /api/auth/mfa/webauthn/setup — Trả về tùy chọn tạo thông tin xác thực cho WebAuthn API. Trình duyệt gọi navigator.credentials.create() với các tùy chọn này.

POST /api/auth/mfa/webauthn/confirm — Xác nhận đăng ký WebAuthn bằng cách gửi phản hồi chứng thực từ trình duyệt.

Mã khôi phục

POST /api/auth/mfa/recovery/generate — Tạo 10 mã khôi phục dùng một lần gồm 8 ký tự. Mỗi mã chỉ có thể sử dụng một lần để bỏ qua MFA.

Xác minh MFA

POST /api/auth/mfa/verify — Hoàn thành thử thách MFA sau khi đăng nhập bằng mật khẩu thành công.

Trạng thái MFA

GET /api/auth/mfa/status — Trả về các phương thức MFA hiện đã đăng ký của người dùng.

Luồng đăng nhập SSO

Authagonal hỗ trợ cả kết nối SSO dựa trên SAML 2.0 và OIDC. Định tuyến theo tên miền tự động phát hiện nhà cung cấp SSO nào sử dụng dựa trên địa chỉ email người dùng.

Kiểm tra SSO

GET /api/auth/sso-check?email=user@acme.com

Luồng SAML

Người dùng được chuyển hướng đến GET /saml/{connectionId}/login gửi SAML AuthnRequest đến nhà cung cấp danh tính. IdP xác thực người dùng và gửi phản hồi SAML trở lại điểm cuối Assertion Consumer Service (ACS). Authagonal xác thực assertion, tạo hoặc cập nhật người dùng và ký cookie phiên.

SAML metadata để cấu hình IdP có sẵn tại GET /saml/{connectionId}/metadata.

Luồng OIDC

Người dùng được chuyển hướng đến GET /oidc/{connectionId}/login chuyển hướng đến nhà cung cấp danh tính upstream với PKCE. Sau khi người dùng xác thực, callback tại /oidc/callback trao đổi mã ủy quyền, xác thực ID token và tạo hoặc cập nhật người dùng.

Cung cấp JIT: Cả luồng SAML và OIDC đều hỗ trợ cung cấp just-in-time. Nếu người dùng chưa tồn tại trong tenant, họ được tạo tự động từ claims của nhà cung cấp danh tính. Nếu đã tồn tại, thuộc tính hồ sơ được cập nhật để khớp với giá trị mới nhất từ nhà cung cấp.

Xây dựng giao diện đăng nhập tùy chỉnh

Thay thế các màn hình đăng nhập, đăng ký, đặt lại mật khẩu và MFA được lưu trữ sẵn của Authagonal bằng giao diện của riêng bạn, trong khi Authagonal vẫn xử lý việc xác thực, MFA, SSO, phiên và cấp phát token. Có hai hướng: dùng thư viện component React của chúng tôi, hoặc gọi trực tiếp API xác thực từ bất kỳ framework nào. Đây là tính năng tùy chọn — bật Custom login UI trong cài đặt tenant trước.

Điều kiện tiên quyết: một tên miền tùy chỉnh trên tên miền gốc của bạn

Phiên đăng nhập là cookie bên thứ nhất, vì vậy giao diện của bạn và máy chủ xác thực Authagonal phải dùng chung một tên miền đăng ký được. Trỏ một tên miền xác thực tùy chỉnh đến Authagonal trên cùng tên miền gốc mà ứng dụng của bạn chạy — ví dụ, xác thực tại login.acme.com, ứng dụng tại app.acme.com. Cài đặt Custom login UI vẫn bị tắt cho đến khi có một tên miền tùy chỉnh đang hoạt động.

Đồng thời thêm nguồn gốc của giao diện (ví dụ https://app.acme.com) vào Allowed CORS origins của OAuth client — cùng danh sách mà bạn đã đặt cho việc trao đổi token.

React: @authagonal/login

npm i @authagonal/login cung cấp logic xác thực và giao diện trong một gói duy nhất — chính gói mà trang đăng nhập được lưu trữ của Authagonal được xây dựng trên đó. Chọn mức độ phù hợp:

• Toàn bộ ứng dụng — đặt App vào và tạo giao diện qua thương hiệu.
• Ghép các trang — dùng LoginPage, MfaChallengePage, ResetPasswordPage… trong bố cục của riêng bạn.
• Thành phần cơ bản + logic — tự xây các màn hình của riêng bạn với AuthLayout/Button/Input và API client (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Mọi framework: gọi API xác thực

Không dùng React? Gọi trực tiếp các điểm cuối luồng xác thực (dưới /api/auth), rồi chuyển giao cho luồng OIDC chuẩn /connect/authorize. Gửi credentials: 'include' để cookie phiên được lưu lại.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"jane@acme.com","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Gói & Giới hạn

Authagonal cung cấp bốn cấp gói. Tất cả gói bao gồm mọi tính năng — sự khác biệt duy nhất là giới hạn Người dùng Hoạt động Hàng tháng (MAU) và giá phần vượt quá.

Cấp gói

Người dùng Hoạt động Hàng tháng (MAU)

Người dùng Hoạt động Hàng tháng là bất kỳ người dùng duy nhất nào xác thực thành công ít nhất một lần trong tháng thanh toán. Người dùng được cung cấp qua SCIM nhưng chưa đăng nhập không được tính vào tổng MAU.

Phần vượt quá — Nếu gói hỗ trợ phần vượt quá, người dùng vượt giới hạn MAU sẽ được tính theo mức giá mỗi người dùng trong bảng gói trên. Bạn có thể đặt giới hạn phần vượt quá để hạn chế chi tiêu tối đa cho kỳ thanh toán.

Thực thi — Nếu gói không hỗ trợ phần vượt quá (Starter), người dùng vượt giới hạn MAU không thể đăng nhập cho đến kỳ thanh toán tiếp theo hoặc cho đến khi bạn nâng cấp lên gói hỗ trợ phần vượt quá.