---
title: 單一登入
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure
description: 讓人員與服務使用來自您身分識別提供者的權杖呼叫您自行託管的 Claude Managed Agents 伺服器。
---

<Note>
  若要申請自行託管的 Claude Managed Agents 存取權，請聯絡您的 Anthropic 客戶團隊。
</Note>

根據預設，您的伺服器會接受一把共用金鑰，即[伺服器 API 金鑰](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted#the-three-credentials)。啟用單一登入後，每個人員或服務也能使用來自您 OpenID Connect (OIDC)「identity provider」（身分識別提供者）的權杖呼叫伺服器。伺服器會根據權杖中的群組為呼叫者指派角色。伺服器 API 金鑰仍可作為管理員憑證使用。

本頁面說明如何新增您的身分識別提供者、各角色可執行的操作，以及如何讓開發人員從終端機登入。

## 新增您的身分識別提供者

<Steps>
  <Step title="在您的身分識別提供者中註冊伺服器">
    將伺服器註冊為一個 API，並使用如 `api://cma-server` 的識別碼，然後讓用戶端為其請求權杖。
  </Step>

  <Step title="在設定檔中列出身分識別提供者">
    在[設定檔](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#where-settings-go)中的 `auth.issuers` 下新增一個項目：

    ```yaml
    auth:
      issuers:
        - name: okta
          issuer_url: https://login.example.com/oauth2/default
          audiences: [api://cma-server]
          roles:
            - group: cma-admins
              role: admin
            - group: "eng-*"
              role: developer
    ```

    * `name` 在記錄行中標示該簽發者，伺服器也會將它記錄為每項資源建立者的一部分。一旦有人建立了資源，就不要再變更它。
    * `issuer_url` 必須等於您權杖的 `iss` 宣告。
    * `audiences` 列出權杖的 `aud` 宣告可攜帶的值，例如第一個步驟中的識別碼。
    * `roles` 將群組對應至 `admin`、`developer` 或 `user`。最高的相符角色勝出。

    如需其他欄位，請參閱[簽發者項目](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#issuer-entries)。如果您的提供者是 Microsoft Entra ID，另請參閱 [Microsoft Entra ID](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure#microsoft-entra-id)。
  </Step>

  <Step title="重新啟動伺服器並檢查登入">
    重新啟動伺服器。呼叫者在任何接受伺服器 API 金鑰的路由上，都以 `Authorization: Bearer <token>` 傳送權杖。

    對於每個經權杖驗證的請求，伺服器都會記錄 `auth=oidc`、簽發者的 `name`，以及呼叫者的主體（`sub=`）。
  </Step>
</Steps>

### 如果登入失敗

| 回應                    | 原因                    | 伺服器的記錄行中包含            |
| --------------------- | --------------------- | --------------------- |
| `401`，與錯誤 API 金鑰的回應相同 | 權杖未通過檢查。記錄行中會說明原因。    | `oidc token`          |
| `403`                 | 權杖的群組未符合任何 `roles` 項目 | `token holds no role` |

### Microsoft Entra ID

Entra ID 在兩方面與其他提供者不同。這兩項設定都放在簽發者項目中：

* **人員：** Entra ID 會在每個用戶端應用程式中給同一個人不同的 `sub`，因此預設值會將同一個人記錄為多個建立者。請設定 `subject_claim: oid`。
* **群組：** 如果某人隸屬於許多群組，Entra ID 會在權杖中省略 `groups` 宣告。該人員因此不會符合任何 `roles` 項目。為避免此情況，請讓 Entra ID 只發出指派給該應用程式的群組。或者在 Entra ID 中將應用程式角色指派給人員，並設定 `groups_claim: roles`，讓伺服器讀取應用程式角色來取代群組。

## 各角色可執行的操作

| 角色                   | 代理、技能、工作階段、vault 與記憶體儲存區 | 環境                  |
| -------------------- | ------------------------ | ------------------- |
| `admin`，以及伺服器 API 金鑰 | 可檢視與變更所有項目               | 可建立、變更與刪除環境，並建立其金鑰  |
| `developer` 或 `user` | 只能檢視與變更該呼叫者所建立的項目        | 可列出、讀取環境，並在其中執行工作階段 |

`developer` 與 `user` 擁有相同的存取權限。具備其中任一角色的呼叫者：

* **無法看到由其他人建立的資源。** 該資源不會出現在清單中，而對其 ID 的請求所得到的回應，與對未知 ID 的請求相同。這包括在您啟用單一登入之前使用伺服器 API 金鑰建立的所有資源。
* **無法與其他呼叫者或群組共用資源**。

請將 `admin` 對應至確切的群組名稱。管理員也可以啟動使用任何使用者之 vault 的工作階段。因此請只將此角色授予您信任可存取每位使用者 MCP 權杖的群組。

## 讓開發人員從終端機登入

開發人員可以透過您的身分識別提供者登入，然後以自己的身分使用 `ant` CLI，而不需要伺服器 API 金鑰。前兩個步驟由您執行，第三個步驟由每位開發人員執行。

<Steps>
  <Step title="在您的身分識別提供者中註冊應用程式">
    註冊一個具備以下條件的原生（「public」）應用程式：

    * 不含用戶端密鑰
    * 搭配 PKCE 的授權碼授與
    * 重新導向 URI `http://127.0.0.1/callback`

    部分提供者需要使用[其他重新導向 URI](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure#other-redirect-uris) 之一。
  </Step>

  <Step title="將應用程式新增至簽發者項目">
    在簽發者項目中加入 `login_client_id` 與 `login_scopes`，然後重新啟動伺服器：

    ```yaml
    login_client_id: 0oa1b2c3d4e5f6g7h8i9
    login_scopes: [openid, cma-server.access]
    ```

    `login_scopes` 列出您的提供者為核發 `aud` 宣告位於簽發者項目 `audiences` 清單中的權杖所需的範圍。
  </Step>

  <Step title="登入">
    每位開發人員從解壓縮後的封存檔頂層執行登入：

    ```bash
    ./cma-server-admin login https://cma.example.com
    ```

    伺服器的 URL 必須是 `https://`，或是指向 `localhost`、`127.0.0.1` 或 `::1` 的 `http://`。若使用[其他重新導向 URI](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure#other-redirect-uris) 之一，請在指令中加入其旗標。

    此指令會在瀏覽器中開啟提供者的登入頁面，然後寫入一個名為 `cma-server` 的 `ant` CLI 設定檔。對任何 `ant` 指令傳入 `--profile cma-server`，或執行 `ant profile activate cma-server` 將該設定檔設為預設值。
  </Step>
</Steps>

權杖過期時，開發人員再次執行 `login` 即可。若要改由 `ant` CLI 更新權杖，請將 `offline_access` 加入 `login_scopes`。

### 其他重新導向 URI

| 提供者                   | 要註冊的重新導向 URI                                    | 開發人員在 `login` 指令中加入的旗標   |
| --------------------- | ----------------------------------------------- | ------------------------ |
| Microsoft Entra ID    | `http://localhost/callback`                     | `-listen localhost:0`    |
| 要求重新導向 URI 中包含連接埠的提供者 | 具固定連接埠的 URI，例如 `http://127.0.0.1:8123/callback` | `-listen 127.0.0.1:8123` |

若要列出其他旗標，請在 `login` 指令中加入 `-h`。

## 讓使用者登入您伺服器上的主控台

您伺服器上的主控台會透過您為[終端機登入](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal)所註冊的應用程式讓使用者登入。若要完成其設定，請參閱[設定登入](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/console#set-up-sign-in)。