Chuyển tới nội dung chính

Bài 1 — Lần đầu đăng nhập

Trang này hướng dẫn đăng nhập lần đầu sau khi deploy và cấp quyền owner khởi tạo, để bạn có quyền quản trị trước khi tạo Space và mời team.

Đối tượng: quản trị viên hệ thống, ngay sau deploy đầu tiên. Bối cảnh: database mới hoàn toàn. Phân quyền fail-closed nên chưa ai có quyền gì, kể cả bạn. Thời gian: ~10 phút.

Vì sao bạn bị 403 — luồng danh tính​

Mọi request đi qua 4 tầng phân giải danh tính theo thứ tự ưu tiên cứng (không tầng nào vượt tầng trước):

Điểm mấu chốt: role không bao giờ đến từ header (server cố tình bỏ qua x-forwarded-role để chặn tự nâng quyền). Database mới = chưa ai là member của Space nào = 403 khắp nơi. Bài này khắc phục bằng cách grant owner đầu tiên từ phía server.

Các bước​

  1. Mở https://agentjira.yourcompany.com. Cloudflare Access yêu cầu đăng nhập SSO.
  2. Sau khi qua SSO, bạn vào được UI nhưng danh sách Space trống và mọi hành động trả 403 — đúng như thiết kế, chưa phải lỗi.
  3. Trên server, đặt email của bạn vào biến bootstrap (/opt/agentjira/.env):
AGENTBOARD_BOOTSTRAP_OWNERS=lead@yourcompany.com
  1. Restart server và xác nhận grant:
docker compose -f docker-compose.prod.yml up -d agentjira_server
docker compose -f docker-compose.prod.yml logs agentjira_server | grep '\[rbac\]'
# → [rbac] applied 1 bootstrap owner grant(s) from AGENTBOARD_BOOTSTRAP_OWNERS
  1. Refresh UI → bạn là owner trên mọi Space đang tồn tại.

Server chỉ grant cho Space chưa có member nào (Space đã có người quản trị thì bỏ qua), nên lệnh này idempotent — chạy lại không nhân đôi quyền.

Xác minh​

curl http://<host>/api/me | jq .
# → { "actor": { "id": "human:lead@yourcompany.com", "type": "human",
#                "email": "lead@yourcompany.com", "role": "member" } }
# (role ở đây là role mặc định của actor; quyền thật theo từng Space xem ở Bài 2)

curl http://<host>/api/projects | jq 'length'
# → số Space bạn thấy được (không còn 0)
  • Thấy log [rbac] applied … bootstrap owner grant(s). Không thấy log mà vẫn 403? Server chỉ log khi grant được > 0 — kiểm tra tiếp: logs ... | grep '\[rbac\]' có dòng Space(s) have no members and are therefore inaccessible nghĩa là email bootstrap không khớp email SSO của bạn (sai chính tả / khác domain) — sửa .env và restart lại.
  • GET /api/me trả type: human + đúng email; GET /api/projects không rỗng.

Khác biệt theo môi trường​

Làm đúng 5 bước trên. Lệnh grant idempotent — vừa là đường khởi tạo lần đầu, vừa là đường break-glass khi mất hết admin sau này.

Bài tiếp theo: Bài 2 — Tạo Space đầu tiên.

Gặp lỗi? Xử lý sự cố — mẫu 403 sau bootstrap, SSO không qua, log [rbac] vắng mặt.

Đi tiếp: Bài 2 — Tạo Space đầu tiên · Phân quyền Board

Cập nhật lần cuối vào