---
title: 싱글 사인온
url: https://platform.claude.com/docs/ko/managed-agents/self-hosted/configure
description: 사람과 서비스가 ID 공급자에서 발급한 토큰으로 자체 호스팅 Claude Managed Agents 서버를 호출할 수 있게 합니다.
---

<Note>
  자체 호스팅 Claude Managed Agents에 대한 접근 권한을 요청하려면 Anthropic 계정 팀에 문의하세요.
</Note>

기본적으로 서버는 하나의 공유 키인 [서버 API 키](https://platform.claude.com/docs/ko/managed-agents/self-hosted#the-three-credentials)를 받습니다. 싱글 사인온을 사용하면 각 사람이나 서비스가 OpenID Connect (OIDC) ID 공급자에서 발급한 토큰으로도 서버를 호출할 수 있습니다. 서버는 토큰에 포함된 그룹을 기반으로 호출자에게 역할을 부여합니다. 서버 API 키는 관리자 자격 증명으로 계속 작동합니다.

이 페이지에서는 ID 공급자를 추가하는 방법, 각 역할의 권한, 그리고 개발자가 터미널에서 로그인하도록 허용하는 방법을 보여 줍니다.

## ID 공급자 추가

<Steps>
  <Step title="ID 공급자에 서버 등록">
    서버를 `api://cma-server`과 같은 식별자를 가진 API로 등록하고, 클라이언트가 이에 대한 토큰을 요청하도록 하세요.
  </Step>

  <Step title="설정 파일에 ID 공급자 나열">
    [설정 파일](https://platform.claude.com/docs/ko/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/ko/managed-agents/self-hosted/configuration-reference#issuer-entries)을 참조하세요. 공급자가 Microsoft Entra ID인 경우 [Microsoft Entra ID](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configure#microsoft-entra-id)도 참조하세요.
  </Step>

  <Step title="서버를 재시작하고 로그인 확인">
    서버를 재시작하세요. 호출자는 서버 API 키를 허용하는 모든 경로에서 토큰을 `Authorization: Bearer <token>`으로 보냅니다.

    토큰으로 인증된 모든 요청에 대해 서버는 `auth=oidc`, 발급자의 `name`, 호출자의 subject(`sub=`)를 로그에 기록합니다.
  </Step>
</Steps>

### 로그인이 실패하는 경우

| 응답                   | 원인                                | 서버 로그 줄에 포함되는 내용      |
| -------------------- | --------------------------------- | --------------------- |
| 잘못된 API 키와 동일한 `401` | 토큰이 검사에 실패했습니다. 로그 줄에 원인이 있습니다.   | `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`를 설정하세요.

## 각 역할의 권한

| 역할                    | 에이전트, 스킬, 세션, 볼트 및 메모리 스토어 | 환경                        |
| --------------------- | -------------------------- | ------------------------- |
| `admin` 및 서버 API 키    | 모든 항목을 조회하고 변경             | 환경을 생성, 변경, 삭제하고 환경 키를 생성 |
| `developer` 또는 `user` | 해당 호출자가 생성한 항목만 조회하고 변경    | 환경을 나열하고, 읽고, 환경에서 세션을 실행 |

`developer`와 `user`는 동일한 접근 권한을 가집니다. 두 역할 중 하나를 가진 호출자는 다음과 같습니다.

* **다른 사람이 생성한 리소스를 볼 수 없습니다.** 해당 리소스는 목록에 나타나지 않으며, 그 ID에 대한 요청은 알 수 없는 ID에 대한 요청과 동일한 응답을 받습니다. 여기에는 싱글 사인온을 켜기 전에 서버 API 키로 생성한 모든 리소스가 포함됩니다.
* **리소스를 다른 호출자나 그룹과 공유할 수 없습니다.**

`admin`은 정확한 그룹 이름에 매핑하세요. 관리자는 모든 사용자의 볼트를 사용하는 세션을 시작할 수도 있습니다. 따라서 모든 사용자의 MCP 토큰을 맡길 수 있는 그룹에만 이 역할을 부여하세요.

## 개발자가 터미널에서 로그인하도록 허용

개발자는 ID 공급자를 통해 로그인한 다음, 서버 API 키 없이 자신의 ID로 `ant` CLI를 사용할 수 있습니다. 처음 두 단계는 관리자가 수행하고, 세 번째 단계는 각 개발자가 수행합니다.

<Steps>
  <Step title="ID 공급자에 애플리케이션 등록">
    다음을 갖춘 네이티브(“public”) 애플리케이션을 등록하세요.

    * 클라이언트 시크릿 없음
    * PKCE를 사용하는 인증 코드 그랜트
    * 리디렉션 URI `http://127.0.0.1/callback`

    일부 공급자에는 [기타 리디렉션 URI](https://platform.claude.com/docs/ko/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/ko/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가 토큰을 갱신하도록 하려면 `login_scopes`에 `offline_access`를 추가하세요.

### 기타 리디렉션 URI

| 공급자                    | 등록할 리디렉션 URI                                       | 개발자가 `login` 명령에 추가하는 플래그 |
| ---------------------- | -------------------------------------------------- | ------------------------- |
| Microsoft Entra ID     | `http://localhost/callback`                        | `-listen localhost:0`     |
| 리디렉션 URI에 포트를 요구하는 공급자 | `http://127.0.0.1:8123/callback`과 같이 고정 포트를 가진 URI | `-listen 127.0.0.1:8123`  |

다른 플래그를 나열하려면 `login` 명령에 `-h`를 추가하세요.

## 사람들이 서버의 콘솔에 로그인하도록 허용

서버의 콘솔은 [터미널 로그인](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal)용으로 등록한 애플리케이션을 통해 사람들을 로그인시킵니다. 설정을 마치려면 [로그인 설정](https://platform.claude.com/docs/ko/managed-agents/self-hosted/console#set-up-sign-in)을 참조하세요.