Liên kết danh tính khối lượng công việc

Liên kết danh tính khối lượng công việc cho phép hệ thống tự động hóa đáng tin cậy sử dụng Codex mà không cần lưu trữ personal access token hoặc một thông tin xác thực OpenAI dài hạn khác. Khối lượng công việc của bạn cung cấp một token danh tính ngắn hạn từ nhà cung cấp mà bạn đang vận hành. OpenAI xác minh token đó và trả về một access token ngắn hạn cho người dùng hoặc tài khoản dịch vụ trong workspace ChatGPT được quản lý của bạn.

Sử dụng danh tính khối lượng công việc cho các tiến trình Codex không có người giám sát trên nền tảng đám mây, Kubernetes, hệ thống CI và các môi trường khác có thể cấp token OIDC hoặc SPIFFE JWT-SVID. Để tìm hiểu mô hình tin cậy dùng chung và luồng OpenAI API riêng biệt, hãy xem tổng quan về danh tính khối lượng công việc.

Trước khi bắt đầu

Bạn cần:

• Quyền quản lý danh tính khối lượng công việc trong OpenAI Admin Portal.
• Một workspace ChatGPT được quản lý.
• Một người dùng hoặc tài khoản dịch vụ ChatGPT đang là thành viên hoạt động của workspace đó, hoặc quyền tạo một tài khoản trong quá trình thiết lập.
• Một token OIDC hoặc SPIFFE JWT-SVID mà bạn biết tổ chức phát hành, đối tượng nhận và các claim định danh.
• Một môi trường runtime có thể duy trì token đó ở trạng thái hiện hành trong một tệp được bảo vệ tại đường dẫn tuyệt đối.
• Codex 0.148.0 trở lên.
• Một chính sách xác thực Codex có hiệu lực cho phép xác thực ChatGPT và workspace được quy tắc liên kết chọn. Xem Thực thi phương thức đăng nhập hoặc workspace.

OpenAI không tạo principal hoặc tư cách thành viên workspace trong quá trình trao đổi token. Quản trị viên chọn hoặc tạo principal trước khi khối lượng công việc kết nối. Việc tạo người dùng là con người sẽ sử dụng một chỗ trong workspace và tuân theo các quy tắc thành viên của workspace đó.

Trên Windows nguyên bản, hãy sử dụng Windows sandbox nâng cao. Các chế độ Windows sandbox khác không thể bảo vệ tệp token danh tính khỏi những lệnh do mô hình kiểm soát.

Lấy token danh tính

Môi trường runtime của khối lượng công việc lấy và làm mới token danh tính thượng nguồn. Codex không thay mặt bạn gọi dịch vụ metadata đám mây hoặc thư viện máy khách của nhà cung cấp danh tính.

Làm theo hướng dẫn dành cho nhà cung cấp của bạn để cấu hình việc cấp token và kiểm tra một token mẫu:

• Microsoft Azure
• AWS
• Google Cloud
• Oracle Cloud Infrastructure
• GitHub Actions
• Kubernetes
• SPIFFE

Giải mã token mẫu trên máy cục bộ và ghi lại iss, aud, sub cùng mọi claim khác mà bạn dự định tin cậy. Việc giải mã không xác minh chữ ký. Không dán token production vào trang web hoặc ghi token vào nhật ký.

Kết nối khối lượng công việc

Quản trị viên tạo nhà cung cấp và quy tắc liên kết trước khi khởi động Codex.

1. Mở Workload identity trong OpenAI Admin Portal, rồi chọn Connect workload.
2. Tái sử dụng một nhà cung cấp đã được cấu hình cho Codex hoặc tạo nhà cung cấp mới. Các cấu hình đặt sẵn của nhà cung cấp sẽ điền những cài đặt phổ biến cho GitHub Actions, Microsoft Entra ID, Google Cloud, AWS, Kubernetes, SPIFFE và các nhà cung cấp OIDC tùy chỉnh.
3. Chọn Codex và workspace được quản lý mà khối lượng công việc có thể sử dụng.
4. Thêm những điều kiện hẹp nhất để định danh khối lượng công việc. Khớp theo subject, claim chính xác, điều kiện CEL hoặc tổ hợp các yếu tố này. Thêm các đối tượng nhận được chấp nhận để hạn chế những token mà quy tắc chấp nhận. Mọi trình so khớp đã cấu hình đều phải đạt.
5. Ánh xạ quy tắc đến một người dùng hoặc tài khoản dịch vụ ChatGPT hiện có, hoặc tạo một tài khoản trong quá trình thiết lập.
6. Xem lại nhà cung cấp, điều kiện, workspace, principal, phạm vi và thời hạn access token. Chọn Connect workload, rồi chọn Download config.

Tệp đã tải xuống chứa ID quy tắc liên kết không phải bí mật và đường dẫn nơi Codex sẽ đọc token danh tính. Tệp này không chứa thông tin xác thực.

Để tự động hóa quá trình thiết lập, hãy sử dụng Admin API cho danh tính khối lượng công việc. Để tìm hiểu hành vi và ví dụ của trình so khớp, hãy xem Tài liệu tham khảo về quy tắc liên kết.

Cấu hình tiến trình Codex

Tiến trình khởi động Codex cần hai biến danh tính khối lượng công việc sau:

export OPENAI_FEDERATION_RULE_ID="idpm_..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"

OPENAI_FEDERATION_RULE_ID không phải là bí mật. Tệp token mới là bí mật. Hãy sử dụng đường dẫn tuyệt đối trong một thư mục chuyên dụng, chẳng hạn như /var/run/secrets/openai.com, thuộc sở hữu của tài khoản khối lượng công việc với chế độ 0700. Chỉ các tiến trình máy chủ đáng tin cậy mới được ghi vào đó. Đặt thư mục bên ngoài kho lưu trữ và các đường dẫn khác mà công cụ Codex có thể truy cập. Không đưa thông tin xác thực vào nhật ký, lịch sử shell và hiện vật bản dựng.

Thêm thông tin quy kết kiểm tra

Khi các phiên bản runtime dùng chung một quy tắc liên kết, bạn có thể định danh từng phiên bản trong các sự kiện kiểm tra việc cấp token. Đặt biến OPENAI_WORKLOAD_IDENTITY_CONTEXT tùy chọn thành một đối tượng JSON được mã hóa dưới dạng chuỗi:

export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
  "instance_id": "runner-42",
  "display_name": "payments-prod",
  "labels": {
    "environment": "production",
    "region": "us-west-2"
  }
}'

Đối tượng bắt buộc có instance_id. Đối tượng cũng có thể chứa display_name và tối đa tám nhãn. Đối tượng đã mã hóa có thể có kích thước tối đa 1.024 byte. instance_id và display_name có thể dài tối đa 128 ký tự. Khóa nhãn có thể dài tối đa 64 ký tự và giá trị nhãn có thể dài tối đa 256 ký tự.

Mã định danh phải bắt đầu bằng một chữ cái hoặc chữ số ASCII. Sau đó, giá trị có thể chứa chữ cái, chữ số, ., _, :, /, @ và -. Khóa nhãn hỗ trợ chữ cái, chữ số, ., _ và -.

OpenAI xem ngữ cảnh này là thông tin quy kết kiểm tra do máy khách báo cáo, không phải danh tính khối lượng công việc đã được xác minh. Ngữ cảnh không ảnh hưởng đến việc xác thực, ủy quyền, so khớp quy tắc, phạm vi, giới hạn tốc độ, thu hồi, cổng tính năng hoặc chỉ số. Không đưa thông tin xác thực, bí mật, dữ liệu cá nhân, prompt, đầu ra của mô hình hoặc Nội dung Khách hàng khác vào đó.

Đối với ngữ cảnh hợp lệ, OpenAI tạo một ID quy kết ổn định có phạm vi giới hạn theo tenant, nhà cung cấp, quy tắc liên kết và instance_id. Để phục vụ quy kết, access token chứa ID nhưng không chứa ngữ cảnh. Sự kiện kiểm tra cấp token thành công chứa ID và ngữ cảnh đã chuẩn hóa. Ngữ cảnh vượt quá giới hạn hoặc vi phạm schema này sẽ khiến quá trình trao đổi thất bại với invalid_grant.

Codex đọc ngữ cảnh khi tiến trình khởi động và không chuyển ngữ cảnh, ID quy tắc hoặc đường dẫn tệp token đến shell, hook hay máy chủ MCP do mô hình kiểm soát. Khởi động lại Codex sau khi thay đổi ngữ cảnh.

Bảo vệ và luân chuyển tệp token

Đối với các bản triển khai Linux, macOS và WSL được quản lý, hãy thêm toàn bộ thư mục token vào permissions.filesystem.deny_read trong các yêu cầu được quản lý:

[permissions.filesystem]
deny_read = ["/var/run/secrets/openai.com"]

Điều này chặn các lệnh do mô hình kiểm soát đọc token đang hoạt động hoặc tệp thay thế tạm thời, trong khi tiến trình máy chủ Codex vẫn có thể sử dụng token để trao đổi. Đối với volume token được chiếu, hãy từ chối toàn bộ điểm gắn token và mọi đường dẫn đích nền hoặc đã phân giải bên ngoài điểm gắn đó. Chỉ chế độ tệp và việc loại bỏ biến môi trường không thể bảo vệ thông tin xác thực khỏi một tiến trình khác chạy dưới cùng người dùng. Trên Windows nguyên bản, hãy sử dụng sandbox nâng cao được mô tả ở trên.

Đối với nguồn token không chiếu tệp, hãy để một tiến trình máy chủ đáng tin cậy ghi mỗi tệp thay thế vào thư mục được bảo vệ đó rồi đổi tên tệp vào đúng vị trí. Thao tác đổi tên nguyên tử ngăn Codex đọc token chưa hoàn chỉnh. Ví dụ, hãy điều chỉnh script làm mới do máy chủ sở hữu này cho lệnh token của nhà cung cấp. Cấp phát thư mục trước khi chạy script:

set -eu
TOKEN_DIR="/var/run/secrets/openai.com"
TOKEN_FILE="$TOKEN_DIR/identity-token"
umask 077
TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
trap 'rm -f -- "$TOKEN_TEMP"' EXIT
trap 'exit 1' HUP INT TERM
your-identity-provider-command > "$TOKEN_TEMP"
test -s "$TOKEN_TEMP"
mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"

Chạy tiến trình làm mới bên ngoài mọi shell hoặc công cụ mà Codex có thể kiểm soát. Duy trì quy tắc từ chối đọc trong quá trình làm mới và dọn dẹp. Ngay cả khi việc buộc dừng để lại tệp tạm thời, tệp đó vẫn phải nằm trong thư mục bị từ chối. Không đưa cài đặt danh tính khối lượng công việc vào config.toml.

Xác minh kết nối

Nạp môi trường đã tải xuống và kiểm tra phương thức xác thực được chọn:

. ./workload-identity-idpm_example.env
codex login status

Trong PowerShell:

$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
codex login status

Khi kiểm tra thành công, hệ thống sẽ in Logged in using workload identity. Điều này xác nhận Codex đã trao đổi token thông qua quy tắc liên kết được cấu hình. Lệnh không in workspace, principal hoặc quy tắc đã phân giải. Hãy xác nhận các giá trị đó trong Admin Portal trước khi khởi động khối lượng công việc. Nếu Codex báo cáo một phương thức xác thực khác, hai biến WIF bắt buộc chưa được truyền đến tiến trình.

Nếu nhà cung cấp sử dụng Prevent assertion replay và assertion có claim jti, lần kiểm tra này sẽ sử dụng jti đó. Hãy ghi assertion mới được cấp với một jti mới trước khi khởi động một tiến trình Codex khác.

Chạy một yêu cầu nhỏ từ cùng môi trường:

codex exec "Reply with only: workload identity is working"

Codex trao đổi token thượng nguồn và lưu access token OpenAI trong bộ nhớ. Codex không ghi thông tin xác thực nào vào auth.json, keyring hệ thống hoặc config.toml.

Duy trì token ở trạng thái hiện hành

Làm mới tệp token danh tính trước khi token thượng nguồn hết hạn. Codex đọc lại tệp khi cần một access token OpenAI khác. Token OpenAI hết hạn tại thời điểm sớm hơn giữa thời điểm hết hạn của token thượng nguồn và thời hạn của quy tắc liên kết, và không bao giờ tồn tại lâu hơn một giờ.

Khi quản trị viên bật tính năng bảo vệ chống phát lại, mỗi JWT thượng nguồn phải có một jti duy nhất. Hãy ghi một assertion mới được cấp với jti mới trước mỗi lần trao đổi, bao gồm cả những lần làm mới trong một tiến trình chạy dài hạn. Các assertion không có jti sẽ không được bảo vệ chống phát lại.

Codex dùng chung một phiên trao đổi trong bộ nhớ trong mỗi tiến trình máy chủ. Các yêu cầu đồng thời trong tiến trình đó tái sử dụng một access token OpenAI hợp lệ và dùng chung một lần làm mới khi token hết hạn. Các tiến trình riêng biệt thực hiện những lần trao đổi riêng biệt, vì vậy chúng cần các assertion mà nhà cung cấp cho phép sử dụng.

Thứ tự ưu tiên thông tin xác thực

Hai biến danh tính khối lượng công việc bắt buộc được ưu tiên hơn mọi nguồn thông tin xác thực khác:

1. Nếu có OPENAI_FEDERATION_RULE_ID hoặc OPENAI_IDENTITY_TOKEN_FILE, Codex sẽ chọn danh tính khối lượng công việc.
2. Nếu chỉ có một biến bắt buộc, Codex sẽ trả về lỗi. Codex không chuyển sang dùng API key, access token hoặc thông tin đăng nhập đã lưu.
3. Chỉ riêng OPENAI_WORKLOAD_IDENTITY_CONTEXT không chọn danh tính khối lượng công việc.
4. Khi không có biến WIF bắt buộc nào, Codex áp dụng các quy tắc thông tin xác thực thông thường cho bề mặt đó. Đối với các bề mặt cho phép xác thực bằng API key, CODEX_API_KEY được ưu tiên trên codex exec, codex review, TypeScript SDK và codex exec-server --remote. Các bề mặt khác có thể sử dụng CODEX_ACCESS_TOKEN hoặc thông tin đăng nhập đã lưu.

Tùy chọn apiKey của SDK trở thành CODEX_API_KEY, nhưng WIF vẫn được ưu tiên khi có bất kỳ biến WIF bắt buộc nào. Hãy bỏ tùy chọn này khi sử dụng WIF để khối lượng công việc không mang theo thông tin xác thực dài hạn không được sử dụng.

Để di chuyển một khối lượng công việc hiện có mà không bị gián đoạn, hãy cấu hình WIF trong khi thông tin xác thực hiện tại vẫn khả dụng. Khởi động một tiến trình mới với cả hai biến WIF bắt buộc; WIF được ưu tiên ngay cả khi thông tin xác thực cũ vẫn còn. Sau khi khối lượng công việc hoạt động thành công với WIF, hãy xóa thông tin xác thực cũ khỏi runtime và kho bí mật, rồi thu hồi thông tin đó. Trước khi thu hồi, bạn có thể quay lại bằng cách xóa cả hai biến WIF bắt buộc và khởi động một tiến trình mới.

Các bề mặt Codex được hỗ trợ

Cấu hình danh tính khối lượng công việc trên máy sở hữu tiến trình Codex.

Máy khách app-server và exec-server từ xa không bao giờ gửi token danh tính thượng nguồn qua giao thức của chúng.

Thay đổi hoặc xóa quyền truy cập

Các thay đổi đối với subject, đối tượng nhận, claim, điều kiện CEL, phạm vi hoặc thời hạn token của quy tắc sẽ áp dụng cho những lần trao đổi mới. Token được cấp trước khi thay đổi có thể vẫn hợp lệ cho đến khi hết thời hạn.

Vô hiệu hóa nhà cung cấp hoặc quy tắc để dừng quyền truy cập ngay lập tức. Việc vô hiệu hóa chặn các lần trao đổi mới và thu hồi access token OpenAI đã được cấp thông qua tài nguyên đó. Lưu trữ có cùng tác dụng đối với quyền truy cập và không thể hoàn tác. Việc thay đổi độ tin cậy của nhà cung cấp cũng thu hồi các token đã cấp trước khi độ tin cậy mới có hiệu lực.

Kiểm tra các thay đổi

Việc tạo, cập nhật và lưu trữ nhà cung cấp cũng như quy tắc liên kết sẽ tạo ra các sự kiện kiểm tra. Sử dụng Compliance API và hướng dẫn về sự kiện kiểm tra để xuất những sự kiện mà workspace của bạn hỗ trợ. Đối chiếu chúng với nhật ký cấp token của nhà cung cấp danh tính và không ghi assertion thượng nguồn hoặc access token OpenAI vào bất kỳ hệ thống nào.

Khi tiến trình cung cấp OPENAI_WORKLOAD_IDENTITY_CONTEXT, các sự kiện kiểm tra cấp token thành công cũng chứa ID quy kết ổn định và ngữ cảnh đã chuẩn hóa được mô tả ở trên.

Khắc phục sự cố

Để biết chi tiết về việc xác minh nhà cung cấp, các giới hạn và CEL, hãy xem tài liệu tham khảo về quy tắc liên kết.