Managed Agents엔터프라이즈 구성

싱글 사인온

Copy page



사람과 서비스가 ID 공급자에서 발급한 토큰으로 자체 호스팅 Claude Managed Agents 서버를 호출할 수 있게 합니다.

기본적으로 서버는 하나의 공유 키인 서버 API 키를 받습니다. 싱글 사인온을 사용하면 각 사람이나 서비스가 OpenID Connect (OIDC) ID 공급자에서 발급한 토큰으로도 서버를 호출할 수 있습니다. 서버는 토큰에 포함된 그룹을 기반으로 호출자에게 역할을 부여합니다. 서버 API 키는 관리자 자격 증명으로 계속 작동합니다.

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

ID 공급자 추가

1. 1

   ID 공급자에 서버 등록

   서버를 api://cma-server과 같은 식별자를 가진 API로 등록하고, 클라이언트가 이에 대한 토큰을 요청하도록 하세요.

2. 2

   설정 파일에 ID 공급자 나열

   설정 파일의 auth.issuers 아래에 항목을 추가하세요.

   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에 매핑합니다. 일치하는 역할 중 가장 높은 역할이 적용됩니다.

   다른 필드는 발급자 항목을 참조하세요. 공급자가 Microsoft Entra ID인 경우 Microsoft Entra ID도 참조하세요.

3. 3

   서버를 재시작하고 로그인 확인

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

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

로그인이 실패하는 경우

Microsoft Entra ID

Entra ID는 두 가지 점에서 다른 공급자와 다릅니다. 두 설정 모두 발급자 항목에 들어갑니다.

• 사람: Entra ID는 클라이언트 애플리케이션마다 한 사람에게 서로 다른 sub를 부여하므로, 기본값을 사용하면 한 사람이 여러 생성자로 기록됩니다. subject_claim: oid를 설정하세요.
• 그룹: Entra ID는 사람이 많은 그룹에 속해 있으면 토큰에서 groups 클레임을 생략합니다. 그러면 해당 사람은 어떤 roles 항목과도 일치하지 않습니다. 이를 방지하려면 Entra ID가 애플리케이션에 할당된 그룹만 내보내도록 하세요. 또는 Entra ID에서 사람들에게 앱 역할을 할당하고, 서버가 그룹 대신 앱 역할을 읽도록 groups_claim: roles를 설정하세요.

각 역할의 권한

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

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

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

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

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

1. 1

   ID 공급자에 애플리케이션 등록

   다음을 갖춘 네이티브(“public”) 애플리케이션을 등록하세요.

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

   일부 공급자에는 기타 리디렉션 URI 중 하나가 필요합니다.

2. 2

   발급자 항목에 애플리케이션 추가

   발급자 항목에 login_client_id와 login_scopes를 추가하고 서버를 재시작하세요.

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

   

   login_scopes에는 aud 클레임이 발급자 항목의 audiences 목록에 있는 토큰을 발급하기 위해 공급자에 필요한 범위를 나열합니다.

3. 3

   로그인

   각 개발자가 압축을 푼 아카이브의 최상위 위치에서 로그인을 실행합니다.

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

   

   서버의 URL은 https://이거나, localhost, 127.0.0.1 또는 ::1에 대한 http://여야 합니다. 기타 리디렉션 URI 중 하나를 사용하는 경우 해당 플래그를 명령에 추가하세요.

   이 명령은 브라우저에서 공급자의 로그인 페이지를 연 다음, cma-server라는 이름의 ant CLI 프로필을 작성합니다. 모든 ant 명령에 --profile cma-server를 전달하거나, ant profile activate cma-server를 실행하여 이 프로필을 기본값으로 설정하세요.

토큰이 만료되면 개발자는 login을 다시 실행합니다. 대신 ant CLI가 토큰을 갱신하도록 하려면 login_scopes에 offline_access를 추가하세요.

기타 리디렉션 URI

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

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

서버의 콘솔은 터미널 로그인용으로 등록한 애플리케이션을 통해 사람들을 로그인시킵니다. 설정을 마치려면 로그인 설정을 참조하세요.