Tài liệu

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

Ngôn ngữ ưu tiên

Mỗi người dùng có một ngôn ngữ ưu tiên điều khiển cả giao diện được lưu trữ lẫn các e-mail giao dịch mà Authagonal gửi cho họ (xác minh, đặt lại mật khẩu, chào mừng và nhiều hơn nữa). Bạn có thể đặt ngôn ngữ này khi tạo người dùng và thay đổi bất cứ lúc nào từ trang chi tiết của người dùng. Nếu người dùng chưa đặt ngôn ngữ ưu tiên, Authagonal sẽ mặc định về tiếng Anh. Bộ chọn cung cấp tất cả các ngôn ngữ được hỗ trợ: tiếng Anh, tiếng Đức, tiếng Pháp, tiếng Tây Ban Nha, tiếng Bồ Đào Nha, tiếng Việt và tiếng Trung giản thể.

Đặt ngôn ngữ ưu tiên của người dùng trên trang chi tiết

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.

Tổ chức

Tổ chức mà người dùng này thuộc về. Đây là một định danh dạng văn bản tự do của riêng bạn, được phát ra dưới dạng claim org_id trên token của họ và trên /connect/userinfo với scope profile. Authagonal không bao giờ tự suy ra giá trị này: nó được đặt bởi ứng dụng cung cấp của bạn, bởi thông tin xác thực SCIM đã tạo ra người dùng, hoặc đặt thủ công tại đây.

Liên kết bên cạnh trường này liệt kê tất cả những ai dùng chung giá trị đó, và cùng bộ lọc ấy có sẵn trên API dưới dạng GET /api/v1/users?organizationId=. Hãy dùng nó để trả lời ai thuộc về một khách hàng cụ thể mà không phải phân trang toàn bộ thư mục.

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": "[email protected]",
  "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": "[email protected]",
  "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.

Những gì một thông tin xác thực có thể thấy

Một thông tin xác thực SCIM chỉ thấy những người dùng và nhóm do chính nó cung cấp. Việc đọc, cập nhật hay xóa một người dùng do connector khác tạo sẽ trả về 404, thao tác liệt kê chỉ trả về những gì của chính nó, và thành viên của một nhóm chỉ có thể là những người dùng do cùng connector đó cung cấp. Các tài khoản được tạo bằng bất kỳ cách nào khác, bởi quản trị viên, qua đăng ký tự phục vụ hay qua cung cấp just-in-time bằng SSO, hoàn toàn không nhìn thấy được đối với SCIM.

Ranh giới đó là theo client, không theo token. Hai thông tin xác thực được cấp trên cùng một client là một danh tính với hai secret, và mỗi cái đều có thể sửa những gì cái kia tạo ra. Hãy cấp cho các connector không tin cậy lẫn nhau mỗi bên một client riêng. externalId cũng có phạm vi như vậy, nên hai connector đều có thể dùng ext-001 cho hai người khác nhau mà không xung đột.

Hủy cung cấp

DELETE /scim/v2/Users/{id} vô hiệu hóa tài khoản và đánh dấu là đã xóa. Bản ghi vẫn được giữ lại, đúng như RFC 7644 cho phép, nhưng trả về 404 cho mọi thao tác sau đó và bị bỏ khỏi các danh sách. Các đăng ký MFA và thành viên nhóm của họ bị xóa, ánh xạ externalId được giải phóng, và mọi token đã cấp đều bị thu hồi, nên quyền truy cập chấm dứt ngay lập tức chứ không phải vào lần hết hạn token kế tiếp.

Nếu chính người đó sau này được tuyển lại và tạo lại, họ nhận một id người dùng mới. Định danh không bao giờ được tái sử dụng: id chính là subject trong mọi token bạn từng cấp, nên dùng lại nó sẽ âm thầm trao cho người mới vào toàn bộ lịch sử của người giữ trước đó tại mọi ứng dụng tin cậy id ấy.

Gắn thẻ tổ chức cho người dùng đã đồng bộ

SCIM không có cách nào để một connector cho biết nó đang đồng bộ khách hàng nào của bạn. SCIM lõi không định nghĩa thuộc tính tổ chức, nên một thao tác tạo người dùng thông thường chỉ cho bạn biết tên và email của người đó, không cho biết họ thuộc về ai. Nếu nhiều khách hàng cùng cung cấp người dùng vào tenant của bạn, người dùng của họ đến nơi mà không phân biệt được.

Chính thông tin xác thực trả lời câu hỏi đó, chứ không phải bản thân yêu cầu. Khi tạo một token SCIM, hãy đặt Tổ chức thành một định danh của riêng bạn. Mọi người dùng được cung cấp qua token đó đều được gắn thẻ này, và từ đó nó được phát ra dưới dạng claim org_id trên token của họ. Hãy cấp một thông tin xác thực cho mỗi khách hàng trên cùng một client, và người dùng đã đồng bộ của họ sẽ được quy thuộc chính xác mà không cần đăng ký riêng một client cho từng khách hàng. Để trống thì người dùng không được gắn thẻ, đúng như cách mọi thông tin xác thực hoạt động trước khi có tính năng này.

Thẻ được gắn khi người dùng được tạo và không bao giờ ở lần cập nhật sau, nên một lần đồng bộ tăng dần thông thường không thể âm thầm chuyển một tài khoản đã tồn tại sang tổ chức khác. Nếu bạn còn chạy một ứng dụng cung cấp, thẻ đặt tường minh trên thông tin xác thực sẽ thắng: phản hồi /try chỉ điền vào tổ chức nào vẫn còn trống.

Các schema được hỗ trợ

Chúng tôi triển khai các schema lõi User và Group của SCIM 2.0 (RFC 7643). Các thuộc tính người dùng được hỗ trợ là userName, name.givenName, name.familyName, displayName, emails, active, externalId và preferredLanguage / locale.

Phần mở rộng enterprise user không được triển khai, nên department, manager, employeeNumber, costCenter, division và organization được chấp nhận rồi bỏ qua chứ không được lưu, với cả create, replace lẫn PATCH. Cả Entra và Okta đều ánh xạ sẵn một số thuộc tính này, nên bạn không cần gỡ chúng khỏi bản ánh xạ thuộc tính của mình. Để quy một người dùng về một khách hàng của bạn, hãy đặt tổ chức trên thông tin xác thực SCIM: thuộc tính enterprise organization do nhà cung cấp danh tính của khách hàng khẳng định, và nó cố ý không trở thành org_id của họ.

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.

Đăng ký và truy cập

Ai được phép trở thành người dùng trong tenant của bạn, và họ đăng nhập được với những điều kiện nào.

Lưu giữ người dùng không hoạt động

Tùy chọn vô hiệu hóa rồi xóa những tài khoản đã không còn được dùng, để một thư mục không tích tụ mãi những danh tính ngủ đông. Cả hai đều tắt trừ khi bạn tự đặt, và việc xóa là vĩnh viễn.

Xuất nhật ký kiểm toán và sao lưu từ xa

Hai cách để lấy dữ liệu của bạn ra theo lịch thay vì theo từng yêu cầu. Xuất nhật ký kiểm toán đẩy mỗi ngày sự kiện kiểm toán đã hoàn tất tới một URL bạn chỉ định, có ký để bạn xác minh được rằng nó đến từ chúng tôi, dùng để nạp vào một SIEM hoặc một kho lưu trữ phục vụ tuân thủ. Sao lưu từ xa gửi bản sao của các bản sao lưu hằng ngày và hằng tuần tới một đích do bạn kiểm soát, không xác thực, xác thực basic hoặc dùng bearer token. Cả hai đều được cấu hình trong Cài đặt và thuộc về bạn để tự giữ, độc lập với các bản sao lưu mà chúng tôi lưu.

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.

E-mail bản địa hoá

E-mail giao dịch được gửi bằng ngôn ngữ ưu tiên của người nhận. Các e-mail xác minh, đặt lại mật khẩu, tài khoản đã tồn tại, chào mừng, thanh toán và lời mời quản trị viên đều có mẫu trong bảy ngôn ngữ: tiếng Anh, tiếng Đức, tiếng Pháp, tiếng Tây Ban Nha, tiếng Bồ Đào Nha, tiếng Việt và tiếng Trung giản thể. Khi không có mẫu cho ngôn ngữ của người nhận, e-mail sẽ mặc định về tiếng Anh.

Ngôn ngữ được xác định từ tuỳ chọn đã lưu của người nhận tại thời điểm gửi. Tuỳ chọn này có thể đến từ nhiều nơi:

• Đăng ký và tạo tài khoản — lấy từ ngôn ngữ người dùng đã chọn trên các màn hình đăng nhập được lưu trữ.
• Trang Người dùng trong portal — do quản trị viên đặt khi tạo hoặc chỉnh sửa người dùng.
• Cung cấp qua SCIM — ánh xạ từ preferredLanguage của IdP khi người dùng được đồng bộ qua SSO.
• Trang tài khoản tự phục vụ — do chính người dùng chọn tại /login/account.

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ụ [email protected]) 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 provisioning là dịch vụ của chính bạn, được Authagonal gọi mỗi khi một người dùng được tạo, để chúng có thể thiết lập tài khoản, gán license, quyết định người dùng thuộc tổ chức nào, hoặc từ chối hẳn việc đăng ký.

Cách hoạt động

Khi một người dùng được tạo, Authagonal gọi URL callback của ứng dụng provisioning của bạn theo mẫu TCC (Try/Confirm/Cancel). Mọi ứng dụng đều phải chấp nhận ở pha Try trước khi bất kỳ ứng dụng nào được commit, nhờ đó nhiều hệ thống phía sau có thể cùng đồng ý, hoặc một hệ thống có thể phủ quyết, mà không để lại những tài khoản tạo dở dang.

Khi nào provisioning chạy

Provisioning chạy trên mọi luồng tạo người dùng, không chỉ khi người dùng tự đăng ký. Các cặp ứng dụng và người dùng đã được provision sẽ bị bỏ qua, nên mỗi ứng dụng chỉ thấy mỗi người dùng một lần.

Yêu cầu Try

Authagonal POST JSON này tới <code>{callbackUrl}/try</code>. Các trường không có giá trị sẽ bị bỏ qua thay vì được gửi là null.

Người dùng đến qua SSO là trường hợp phổ biến đáng để tính trước: họ chưa có tổ chức, và federated_connection cho bạn biết họ đến từ khách hàng nào của bạn.

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

Phản hồi Try

Ứng dụng của bạn trả về 200 kèm một body JSON. Body này không chỉ là lời xác nhận đã nhận: đó là cách một ứng dụng phía sau gán tổ chức và các thuộc tính rồi cuối cùng xuất hiện trên token của người dùng.

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

Gắn người dùng với đúng tổ chức

Hãy quyết định tổ chức ở đây, tại một chỗ duy nhất, thay vì ở từng luồng tạo. Người dùng SSO mang theo federated_connection, thứ xác định kết nối đã xác thực họ và do đó xác định khách hàng, và vẫn đúng khi một khách hàng liên kết nhiều miền email. Người dùng được mời thì không có kết nối, nên hãy đối chiếu họ theo lời mời mà bạn đã phát hành. Cả hai luồng đều đi tới /try trước khi người dùng tồn tại, nên một đoạn logic duy nhất bao trọn cả hai và không có hai quy tắc để lệch nhau.

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

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ị

Hỗ trợ

Mở một yêu cầu hỗ trợ với đội ngũ Authagonal mà không cần rời khỏi portal. Mỗi yêu cầu là một cuộc trò chuyện theo luồng, nên bạn và đội ngũ của chúng tôi luôn nắm chung thông tin từ lúc báo cáo đầu tiên đến khi giải quyết xong.

Các yêu cầu của bạn

Trang hỗ trợ liệt kê mọi yêu cầu bạn đã tạo, hoạt động mới nhất lên đầu. Dùng huy hiệu trạng thái để biết ngay yêu cầu nào đang chờ bạn và yêu cầu nào đang chờ chúng tôi.

Các yêu cầu hỗ trợ của bạn với tiêu đề, trạng thái, mức ưu tiên và hoạt động gần nhất

• Mỗi hàng hiển thị tiêu đề, trạng thái hiện tại (đang mở, đang chờ, đã giải quyết hoặc đã đóng), mức ưu tiên và thời điểm của hoạt động gần nhất.
• Nhấn Yêu cầu mới để mở một yêu cầu, sau đó đặt tiêu đề, mức ưu tiên và tin nhắn đầu tiên của bạn.
• Huy hiệu trạng thái được mã hóa màu giúp dễ dàng quét qua danh sách để tìm những yêu cầu cần bạn chú ý.

Một luồng yêu cầu

Mở một yêu cầu sẽ hiển thị toàn bộ cuộc trò chuyện. Các phản hồi đăng theo thứ tự, và tin nhắn mới từ đội ngũ của chúng tôi xuất hiện mà không cần tải lại trang.

Một luồng yêu cầu giữa bạn và đội ngũ Authagonal

• Tin nhắn theo luồng giữa bạn và đội ngũ Authagonal được hiển thị theo thứ tự thời gian.
• Trả lời ngay tại chỗ và đính kèm tệp để chia sẻ log, ảnh chụp màn hình hoặc cấu hình.
• Luồng cập nhật trực tiếp, nên phản hồi từ đội ngũ của chúng tôi hiển thị ngay khi vừa được gửi.
• Nếu bạn trả lời email thông báo thay vào đó, tin nhắn của bạn được tự động ghép vào luồng.

Bộ phận hỗ trợ cho người dùng của bạn

Tách biệt với phần hỗ trợ mà bạn nhận từ chúng tôi, Authagonal có thể vận hành một bộ phận hỗ trợ cho người dùng cuối của bạn. Họ gửi yêu cầu từ các trang tài khoản trên máy chủ mang thương hiệu riêng của tenant bạn, và đội ngũ của bạn trả lời từ cổng.

Nó tồn tại vì những người không đăng nhập được cũng chính là những người không thể với tới một công cụ hỗ trợ đòi hỏi phải đăng nhập. Bộ phận hỗ trợ nằm ngay cạnh các màn hình đăng nhập, nên một người dùng bị khóa ngoài vẫn còn lối vào, và mọi yêu cầu đều đến nơi với sẵn liên kết tới một tài khoản có thật trong thư mục của bạn, thay vì tới bất kỳ địa chỉ nào đó mà ai đấy gõ vào.

Bật tính năng

Mở Cài đặt trong cổng và bật cổng hỗ trợ. Người dùng của bạn không thấy gì cho tới khi bạn làm điều đó.

Người dùng của bạn nhìn thấy gì

Người dùng đã đăng nhập có một khu vực hỗ trợ trong các trang tài khoản trên máy chủ tenant của bạn, mang thương hiệu của bạn. Họ có thể gửi một yêu cầu, xem lại mọi yêu cầu đã gửi và trả lời trong một luồng. Phản hồi từ đội ngũ của bạn cũng đến qua email, nên người dùng không phải liên tục vào kiểm tra.

Khi yêu cầu ẩn danh được bật, một người không đăng nhập được vẫn có thể gửi yêu cầu. Họ cung cấp một địa chỉ email và nội dung của mình, rồi nhận về một liên kết riêng tư dẫn tới cuộc trò chuyện. Liên kết đó là lối vào duy nhất, nên hãy coi nó như một thông tin xác thực: nó không thể đoán được, và bất kỳ ai giữ nó đều có thể đọc và trả lời đúng luồng đó.

Hộp thư của người vận hành

Đội ngũ của bạn trả lời từ Hộp thư hỗ trợ trong cổng. Đây là nơi tách biệt với các yêu cầu của chính bạn gửi cho chúng tôi, và nó dành cho vai trò tenant:support trở lên, nên bạn có thể cho một nhân viên hỗ trợ dùng bộ phận hỗ trợ mà không phải trao cho họ phần còn lại của cổng.

Người dùng viết bằng ngôn ngữ của họ

Một yêu cầu được lưu bằng chính ngôn ngữ mà người dùng đã viết, và mỗi người trong luồng đọc nó bằng ngôn ngữ của mình. Nhân viên hỗ trợ của bạn thấy tin nhắn đã dịch sang ngôn ngữ cổng của họ, người dùng thấy phản hồi của bạn đã dịch sang ngôn ngữ của họ, và văn bản gốc luôn được giữ kèm bên cạnh. Ngôn ngữ được nhận diện từ tin nhắn đầu tiên và gắn cố định vào yêu cầu. Bản dịch được tính một lần cho mỗi ngôn ngữ rồi dùng lại, nên một luồng dài không tự dịch lại từ đầu.

Múi giờ

Mỗi yêu cầu ghi lại múi giờ mà người dùng đã gửi nó đi. Sau đó mỗi tin nhắn hiển thị giờ địa phương của họ bên cạnh giờ của bạn, nên một phản hồi lúc 14:32 hiện đúng là 02:32 như nó thực sự đã diễn ra với người đang chờ. Không có gì được hiển thị khi múi giờ không xác định, chẳng hạn một yêu cầu đến qua email, hoặc khi nó trùng với múi giờ của bạn.

Webhook

Đặt một URL webhook hỗ trợ để nhận các sự kiện của yêu cầu ngay khi chúng xảy ra, dùng để phát cảnh báo hoặc phản chiếu yêu cầu sang hệ thống của riêng bạn. Payload được ký nên bạn có thể xác minh chúng đến từ chúng tôi.

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ò.
• Cảnh báo ghi đè khi tenant đích đã có clients, vai trò hoặc scopes trùng khớp.
• 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 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.

Đối chiếu User ID

Nếu một người dùng đã có trong tenant này có cùng email với một bản ghi sắp nhập, quá trình nhập sẽ xoay userId của tài khoản đó sang sub nguồn trước khi nhập, để các vai trò, đăng nhập và claims được nhập gắn vào tài khoản hiện có và các ứng dụng vốn đã tham chiếu người dùng qua sub nguồn của họ vẫn phân giải được sau khi chuyển đổi. Mật khẩu và hồ sơ hiện có của tài khoản được giữ nguyên; các vai trò nguồn được hợp nhất lên trên. Bản xem trước liệt kê mọi tài khoản sẽ được đối chiếu trước khi bạn 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 "[email protected]").

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": "[email protected]",
    "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ợ count, search (tiền tố email hoặc tên), organizationId để lọc theo một tổ chức, và after để phân trang bằng con trỏ.

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, organizationId).

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": "[email protected]",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

Màn hình đăng nhập

Đây là những màn hình được lưu trữ mà người dùng cuối của bạn nhìn thấy trên máy chủ auth của tenant. Authagonal cung cấp sẵn mọi màn hình để dùng ngay, nên bạn có được trải nghiệm đăng nhập hoàn chỉnh, an toàn mà không cần xây dựng bất kỳ giao diện nào. Trang này đi qua từng màn hình và chỉ ra những cài đặt portal nào điều khiển nó.

Đăng nhập

• Luồng hai bước, ưu tiên email: người dùng nhập email và nhấn Tiếp tục, sau đó trường mật khẩu xuất hiện.
• Các nút đăng nhập một lần "Tiếp tục với {provider}" xuất hiện tự động khi có kết nối SSO.
• Liên kết quên mật khẩu và tạo tài khoản, mỗi liên kết có thể hiển thị hoặc ẩn.
• Tùy chọn captcha Cloudflare Turnstile để ngăn chặn các nỗ lực đăng nhập tự động.

Được điều khiển trong phần quản trị portal

• Branding thiết lập logo, màu sắc, tên ứng dụng, email hỗ trợ và CSS tùy chỉnh.
• Hiển thị hoặc ẩn liên kết quên mật khẩu và đăng ký (Branding).
• Kết nối SSO thêm các nút đăng nhập mạng xã hội (trang SSO).
• Thời lượng phiên và ngưỡng khóa tài khoản (Cài đặt → Bảo mật).

Đăng ký

• Thu thập họ và tên (tùy chọn), email và một mật khẩu.
• Một danh sách kiểm tra chính sách mật khẩu trực tiếp cập nhật khi người dùng gõ, nên các yêu cầu được rõ ràng trước khi gửi.
• Tùy chọn captcha Cloudflare Turnstile.
• Một liên kết "Đăng nhập" cho người dùng đã có tài khoản.

Được điều khiển trong phần quản trị portal

• Hiển thị hoặc ẩn liên kết đăng ký (Branding).
• Chính sách mật khẩu của tenant điều khiển danh sách kiểm tra.
• Branding tạo kiểu cho toàn bộ màn hình.

Quên mật khẩu

• Người dùng nhập email của họ, sau đó thấy một xác nhận trung lập "hãy kiểm tra email của bạn".
• Màn hình không bao giờ tiết lộ liệu một tài khoản có tồn tại hay không, điều này vô hiệu hóa việc dò tìm liệt kê tài khoản.
• Một liên kết "Quay lại đăng nhập" đưa người dùng trở về màn hình đăng nhập.

Được điều khiển trong phần quản trị portal

• Hiển thị hoặc ẩn liên kết quên mật khẩu (Branding).
• Gửi email của tenant gửi đi thông điệp đặt lại.
• Branding tạo kiểu cho toàn bộ màn hình.

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

• Các trường mật khẩu mới và xác nhận mật khẩu với một danh sách kiểm tra yêu cầu theo từng quy tắc trực tiếp.
• Một trạng thái liên kết không hợp lệ hoặc đã hết hạn rõ ràng khi token đặt lại không còn hiệu lực.
• Một trạng thái thành công xác nhận mật khẩu đã được thay đổi.

Được điều khiển trong phần quản trị portal

• Chính sách mật khẩu của tenant điều khiển danh sách kiểm tra.
• Branding tạo kiểu cho toàn bộ màn hình.

Thử thách MFA

• Một bộ chuyển phương thức giữa ứng dụng xác thực, passkey và mã khôi phục.
• Một trường TOTP 6 chữ số tự động gửi khi nhập đủ các chữ số.
• Nhập mã khôi phục cho người dùng đã mất quyền truy cập vào ứng dụng xác thực của họ.
• Một nút passkey để xác minh dựa trên phần cứng.

Được điều khiển trong phần quản trị portal

• Chính sách MFA được thiết lập theo từng ứng dụng (Clients → Bảo mật).
• Bất kỳ người dùng nào đã đăng ký một yếu tố đều luôn bị thử thách, bất kể chính sách.

Thiết lập MFA

• Hiển thị trạng thái của các phương thức đã đăng ký để người dùng biết những gì đã được cấu hình.
• Thiết lập ứng dụng xác thực qua mã QR, một khóa nhập thủ công dự phòng và một bước xác nhận.
• Đăng ký passkey để xác thực dựa trên phần cứng.
• Tạo mã khôi phục để khôi phục tài khoản.
• Một tùy chọn bỏ qua khi MFA là tự phục vụ thay vì bắt buộc.

Được điều khiển trong phần quản trị portal

• Chính sách MFA được thiết lập theo từng ứng dụng; Bắt buộc buộc thiết lập khi đăng nhập (Clients → Bảo mật).
• Branding tạo kiểu cho toàn bộ màn hình.

Ủy quyền thiết bị

• Một trường nhập mã người dùng căn giữa cho mã hiển thị trên thiết bị.
• Một bước phê duyệt để ủy quyền thiết bị.
• Một màn hình chuyển tiếp đăng nhập khi người dùng chưa được xác thực.
• Một xác nhận đã phê duyệt khi thiết bị đã được ủy quyền.

Được điều khiển trong phần quản trị portal

• Bật device-code grant trên ứng dụng (Clients → Loại grant).
• Thiết lập thời lượng device-code (Clients → Token).

Đồng ý

• Hiển thị logo và tên của client đang yêu cầu.
• Một danh sách theo từng scope với nhãn thân thiện, dễ đọc cho mỗi quyền.
• Các nút Cho phép và Từ chối để cấp hoặc khước từ quyền truy cập.
• Một chân trang gợi ý đồng ý giải thích quyết định đó có ý nghĩa gì.

Được điều khiển trong phần quản trị portal

• Bật Yêu cầu đồng ý theo từng ứng dụng (Clients → Bảo mật).
• Logo, tên và URL đến từ chính metadata của ứng dụng.
• Branding tô vẽ thẻ đồng ý.

Ứng dụng đã kết nối (grant)

• Liệt kê mọi ứng dụng mà người dùng đã ủy quyền, cùng với tên, scope và ngày cấp của nó.
• Thu hồi quyền truy cập vào một ứng dụng, với một bước xác nhận trước khi có hiệu lực.
• Một trạng thái trống thân thiện khi người dùng chưa ủy quyền cho ứng dụng nào.

Được điều khiển trong phần quản trị portal

• Danh sách được điền bởi các ứng dụng yêu cầu đồng ý.
• Branding tạo kiểu cho toàn bộ màn hình.

Tài khoản

Một trang tài khoản tự phục vụ được lưu trữ tại /login/account, nơi người dùng đã đăng nhập quản lý hồ sơ và ngôn ngữ ưu tiên của riêng họ, không cần quyền truy cập portal.

• Chỉnh sửa họ và tên, công ty và điện thoại; địa chỉ e-mail hiển thị ở chế độ chỉ đọc.
• Chọn một ngôn ngữ ưu tiên trong số các ngôn ngữ được hỗ trợ; giao diện xem trước lựa chọn ngay lập tức và lưu lại khi nhấn lưu.
• Ngôn ngữ đã lưu điều khiển giao diện được lưu trữ của người dùng và ngôn ngữ của các e-mail giao dịch mà họ nhận được.

Được điều khiển trong phần quản trị portal

• Branding tạo kiểu cho toàn bộ màn hình.
• Cùng một ngôn ngữ ưu tiên cũng có thể được quản trị viên chỉnh sửa trên trang Người dùng của portal.

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": "[email protected]",
  "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": "[email protected]",
  "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. Đăng ký bằng email đã tồn tại cũng trả về 201: chúng tôi không bao giờ tiết lộ một email có tồn tại hay không (để ngăn việc dò tìm tài khoản), mà thay vào đó thông báo cho chủ tài khoản thực sự qua email.

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": "[email protected]"
}

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/[email protected]

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.

Backend-for-Frontend (BFF)

BFF giữ token OAuth hoàn toàn bên ngoài trình duyệt. Ứng dụng single-page (SPA) của bạn chỉ giữ duy nhất một cookie phiên httpOnly, còn một confidential client trên backend của chính bạn thực hiện luồng OpenID Connect và giữ token ở phía máy chủ.

Bất cứ thứ gì ứng dụng single-page đọc được thì cross-site scripting cũng lấy được, kể cả một access token trong bộ nhớ và một refresh token trong localStorage. Lưu token trong trình duyệt cũng buộc phải rút ngắn thời gian sống của chúng, vì một refresh token dài hạn nằm trong tầm với của script là một rủi ro thường trực. Tài liệu best current practice OAuth 2.0 for Browser-Based Apps của IETF khuyến nghị mô hình này chính vì lý do đó.

Đổi lại, bạn có một phiên sống sót qua việc tải lại trang mà không cần token nào lộ diện, việc làm mới token được xử lý sẵn ở phía máy chủ, thu hồi tức thì qua back-channel logout, và một proxy đã xác thực để API của bạn không bao giờ phải phân tích một token mà trình duyệt có thể đã can thiệp.

Tạo client

Trong cổng, mở Clients và chọn Tạo ứng dụng BFF. Nhập base URL mà ứng dụng của bạn được phục vụ từ đó, ví dụ https://app.acme.com, và Authagonal sẽ đăng ký sẵn cho bạn một confidential client được cấu hình đúng, thay vì để bạn tự ráp lấy:

Đấu nối vào backend của bạn

Hai runtime được hỗ trợ và hoạt động giống hệt nhau: Authagonal.Bff cho .NET và @authagonal/bff cho Node, gói sau có sẵn adapter cho Express và Next.js. Hãy trỏ gói bạn chọn tới đúng các giá trị mà cổng vừa cấp cho bạn.

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

Điểm cuối

Mặc định được gắn dưới /bff. Chúng phải được phục vụ từ cùng origin với SPA của bạn, vì cookie phiên là httpOnly và same-origin: hãy đặt chúng sau cùng một hostname thay vì trên một tên miền API riêng.

Từ trình duyệt

Mọi yêu cầu không phải điều hướng đều phải mang một header chống giả mạo cố định. Nó chống cross-site request forgery cùng với thuộc tính SameSite của cookie: một form post từ site khác không thể đặt header tùy chỉnh, nên yêu cầu thiếu header đó sẽ bị từ chối.

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

Hãy đăng nhập và đăng xuất bằng cách điều hướng, chứ không phải fetch: location.href = '/bff/login'. Các route đó trả lời bằng một chuyển hướng tới nhà cung cấp danh tính của bạn, và fetch không thể theo một chuỗi chuyển hướng như vậy một cách hữu ích.

Gọi API của bạn

BFF có thể chuyển tiếp API của bạn dưới base path của chính nó và gắn access token của phiên trên đường đi. Trình duyệt gửi một cookie, API của bạn nhận một bearer token và xác thực nó như bình thường, còn trang web thì không nhìn thấy và cũng không giả mạo được bất cứ điều gì về token đó. Hãy đăng ký một upstream và các yêu cầu tới /bff/api/** sẽ đến đó ở trạng thái đã xác thực. Để danh sách trống thì proxy bị tắt hoàn toàn.

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSockets

Một lần bắt tay WebSocket không thể mang header tùy chỉnh hay bearer token, nên cả header chống giả mạo lẫn proxy đều không giúp được gì. Hãy bật vé và SPA có thể gọi GET /bff/ws-ticket, đặt chiếc vé dùng một lần, sống ngắn đó lên URL kết nối, rồi để API của bạn đổi vé. Hãy phát vé ngay trước mỗi lần kết nối: vé bị xóa ở lần dùng đầu tiên và hết hạn sau vài giây.

Trao token cho trình duyệt, một cách có chủ đích

Toàn bộ ý nghĩa của một BFF là trình duyệt không giữ token nào, nên tính năng này phải tự bật và có phạm vi hẹp. Nó tồn tại cho đúng một trường hợp mà mô hình cookie không với tới được: một resource server nằm trên origin khác, chẳng hạn một ứng dụng bạn nhúng trong iframe, phải được gọi bằng bearer. Khi bật, GET /bff/token?resource=… trả về một token đã trao đổi: token của phiên được thu hẹp phạm vi xuống đúng một tài nguyên trong danh sách cho phép và gắn với những tham số ngữ cảnh có trong danh sách cho phép. Trình duyệt không bao giờ thấy token của chính phiên, và thứ nó nhận được thì sống ngắn và chỉ dành cho một audience. Một yêu cầu nêu tên tài nguyên ngoài danh sách cho phép sẽ bị từ chối, và đó chính là điều ngăn tính năng này trở thành một cỗ máy phát token đa dụng.

Phục vụ nhiều tenant từ một BFF

Đặt một tham số truy vấn tenant và một bản triển khai phục vụ được nhiều tenant: /bff/login?slug=acme chọn tenant, một resolver cung cấp authority và thông tin đăng nhập client của tenant đó, khóa đi theo cookie correlation vào trong phiên, và back-channel logout xác định tenant từ issuer của token. Resolver mặc định giữ hành vi đơn tenant giống hệt tới từng byte, nên bạn không phải trả giá gì cho tính năng này trừ khi dùng đến.

Những tùy chọn đáng biết

Danh sách đầy đủ. Gói Node phản chiếu các tùy chọn này ở dạng camelCase, nên BasePath là basePath và tương tự với các tên khác.

Điều hành cổng quản lý bằng một trợ lý AI

Kết nối một trợ lý AI với tenant của bạn và nhờ nó làm những việc mà bạn vẫn phải bấm chuột từng bước để làm: tìm một người dùng không đăng nhập được, kiểm tra xem họ còn yếu tố thứ hai hay không, mời ai đó, xem ai đang giữ vai trò quản trị.

Đây là một kết nối OAuth bình thường, không phải một khóa API. Mỗi người tự đăng nhập bằng danh tính của chính mình và phê duyệt quyền truy cập, nên một trợ lý làm được đúng những gì người đó làm được trong cổng quản lý, không hơn. Không có thứ gì mới được tạo ra để có thể rò rỉ, và thu hồi một trợ lý không đụng tới bất kỳ trợ lý nào khác.

Bật tính năng

Mở Cài đặt và bật quyền truy cập cho trợ lý AI. Trước khi bạn bật, tính năng này tắt, và trong lúc tắt thì endpoint không tồn tại chứ không chỉ đơn thuần từ chối. Sau khi bật, bảng cài đặt sẽ hiển thị URL để bạn dán vào client AI của mình:

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

Một trợ lý làm được những gì

Đúng những gì người đã kết nối nó làm được, quyết định theo từng lệnh gọi dựa trên chính token của họ. Một nhân viên tenant:support nhận được các công cụ chẩn đoán và công cụ hằng ngày; các công cụ quản trị không chỉ bị ẩn khỏi họ, mà còn bị từ chối nếu được gọi thẳng tên. Bất cứ thứ gì bị chặn bên trong cổng quản lý thì vẫn bị chặn: đổi địa chỉ email của một người dùng cần vai trò quản trị ở đó, và ở đây cũng cần.

Vì đây là một grant bình thường, bạn quản lý nó theo cách bình thường. Thu hồi nó và trợ lý ngừng hoạt động ngay lập tức chứ không phải đợi tới lần token hết hạn tiếp theo. Mọi việc một trợ lý làm đều được ghi vào nhật ký kiểm toán của bạn dưới tên người mà nó thay mặt, nên dấu vết vẫn đúng là dấu vết bạn vẫn đọc lâu nay.

Các công cụ

Hai mươi công cụ trong bản phát hành này. Client AI của bạn quyết định bật những công cụ nào, nên bạn có thể chỉ giao cho một trợ lý các công cụ đọc, nếu đó là tất cả những gì bạn muốn nó làm.

Những gì chưa có

Xóa người dùng, tạo hoặc sửa kết nối SSO, thanh toán, sao lưu và client secret đều vắng mặt trong bản phát hành này. Việc xóa thuộc về hàng đợi xóa dữ liệu của bạn chứ không phải nằm cạnh nó; một kết nối SSO lớn tới mức một lần sửa sai sẽ khóa cả lực lượng lao động ở bên ngoài, nên hiện tại chúng chỉ đọc; và một công cụ trả về client secret sẽ đặt bí mật đó vào bản ghi hội thoại của trợ lý. Hãy cho chúng tôi biết bạn muốn những mục nào trong số đó và theo thứ tự nào.

Xác thực máy chủ MCP

Nếu bạn công khai một máy chủ Model Context Protocol, Authagonal có thể là máy chủ ủy quyền đứng sau nó. Một trợ lý AI kết nối, người đứng sau nó đăng nhập và cấp quyền truy cập, còn máy chủ của bạn nhận được một bearer token bình thường mà bạn xác thực như với mọi API khác.

Cách làm thay thế là dán một khóa API vào cấu hình của trợ lý, tức là một thông tin xác thực không có người dùng nào đứng sau, không có hạn dùng, không có bước đồng ý và không có cách nào thu hồi một trình kết nối mà không phải xoay khóa cho tất cả mọi người. Làm theo kiểu OAuth nghĩa là grant thuộc về một người có tên cụ thể, hiện rõ trong nhật ký kiểm toán của bạn, và có thể bị thu hồi từ cổng quản lý mà không phải động tới bất cứ thứ gì khác.

Kết nối diễn ra thế nào

Toàn bộ quá trình trao đổi được dẫn dắt bởi discovery, nên một client tuân thủ chuẩn không cần cấu hình gì ngoài URL máy chủ của bạn.

Không có gì trong trình tự đó là riêng của Authagonal: đó là đặc tả ủy quyền của MCP, dựa trên RFC 9728 cho metadata tài nguyên, RFC 8414 để khám phá máy chủ ủy quyền, RFC 7591 để đăng ký và RFC 8707 để nêu tên tài nguyên. Một trình kết nối tuân theo đặc tả sẽ chạy được mà không cần xử lý riêng cho chúng tôi.

Cho phép trình kết nối tự đăng ký

Một trình kết nối mà bạn chưa từng gặp không thể dùng một client do bạn tạo bằng tay, nên nó đăng ký một client lúc chạy. Mặc định tính năng đó tắt. Hãy bật đăng ký client động trong Cài đặt và endpoint đăng ký sẽ xuất hiện trong tài liệu discovery của bạn; để tắt thì endpoint không được công bố và sẽ từ chối. Bật nó chỉ mở đăng ký cho riêng tenant của bạn, không bao giờ cho tenant của người khác.

Máy chủ MCP của bạn cần triển khai gì

Hai việc nhỏ, sau đó nó chỉ là một resource server bình thường. Đầu tiên, hãy công bố metadata tài nguyên được bảo vệ nêu tenant của bạn là máy chủ ủy quyền. Phục vụ nó ở đường dẫn well-known và, nếu endpoint MCP của bạn nằm trên một đường dẫn con, phục vụ cả ở dạng có hậu tố đường dẫn, vì client thử cả hai.

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

Thứ hai, khi một lệnh gọi đến mà không có token hợp lệ, hãy trả về 401 kèm header WWW-Authenticate trỏ tới metadata đó. Chính header đó biến một lần từ chối thành một kết nối: không có nó, client không có cách nào biết cần xác thực ở đâu, và đơn giản là thất bại.

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

Phạm vi, gói dịch vụ và thu hồi

Hãy định nghĩa một phạm vi cho API MCP của bạn, thêm nó vào các phạm vi đăng ký được phép, và nó sẽ xuất hiện trên màn hình đồng ý để người dùng thấy họ đang phê duyệt điều gì. Token mang theo vai trò của người dùng và các claim bạn đã cấu hình, nên máy chủ của bạn có thể quyết định chính người này được làm gì, thay vì đối xử với mọi trình kết nối như nhau.

Vì đây là một grant OAuth bình thường, việc thu hồi cũng diễn ra theo cách bình thường: tìm người dùng, thu hồi các phiên hoặc grant của họ, và trình kết nối ngừng hoạt động ngay lập tức chứ không phải đợi tới lần token hết hạn tiếp theo. Nhật ký kiểm toán ghi lại lần đăng ký, sự đồng ý và lần cấp token, nên bạn thấy được trợ lý nào đã xin gì và vào lúc nào.

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":"[email protected]","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á.