> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO

> 조직의 SAML 2.0 IdP를 연동해 멤버 로그인을 간편하게 관리해요.

조직에서 사용하는 IdP(Identity Provider)를 VESSL Cloud와 연동하면 SSO(Single Sign-On)로 멤버 관리를 간편하게 할 수 있어요. 연동을 마치면 멤버들이 이미 쓰고 있는 IdP 계정으로 VESSL Cloud에 로그인할 수 있어요.

## 시작하기 전에

VESSL Cloud는 SAML(Security Assertion Markup Language) 2.0 프로토콜을 지원하는 IdP라면 모두 연동할 수 있어요. 많이 쓰는 IdP는 다음과 같아요.

* [Microsoft Entra](https://www.microsoft.com/en-us/security/business/microsoft-entra) (구 Azure Active Directory)
* [AWS IAM Identity Center](https://aws.amazon.com/iam/identity-center/)
* [Okta](https://okta.com)

시작하기 전에 다음을 확인해 주세요.

* 조직 관리자여야 해요. SAML SSO는 관리자만 설정할 수 있어요.
* 조직에 SAML SSO가 활성화돼 있어야 해요. <strong>Settings</strong>에 **SAML SSO** 메뉴가 안 보이면 [support@vessl.ai](mailto:support@vessl.ai)로 문의해 주세요.

<Note>
  - ACS(Assertion Consumer Service) 엔드포인트는 HTTP-POST 바인딩만 지원해요.
  - IdP에서 시작하는 SSO(IdP-initiated SSO)와 SLO(Single Logout)는 지원하지 않아요.
</Note>

## SP 설정 확인하기

사이드바에서 <strong>Settings</strong>를 선택한 다음, **Organization** 메뉴에서 <strong>SAML SSO</strong>를 선택하세요.

<Frame>
  <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/vessl-saml-sso-settings.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=acbb68a92eb6084e09eb7d38c90867a2" alt="SP Configuration URL과 Add SAML SSO 버튼이 있는 SAML SSO 설정 페이지" width="1920" height="590" data-path="images/saml-sso/vessl-saml-sso-settings.png" />
</Frame>

**SP Configuration** 섹션에 IdP 등록에 필요한 SP(Service Provider) URL 두 개가 표시돼요. 두 URL은 조직마다 다르니 이 페이지에서 직접 복사해서 사용하세요.

* **VESSL Cloud's metadata**: SAML Entity ID이자 메타데이터 URL이에요. 이 URL을 열면 메타데이터 XML 원문을 확인할 수 있는데, 일부 IdP는 설정 과정에서 이 XML을 요구해요.
* **SAML ACS URL**: IdP가 보내는 SAML 응답을 받는 엔드포인트예요.

## IdP 설정하기

사용하는 IdP에 맞는 설정 방법을 선택하세요.

<Tabs>
  <Tab title="Microsoft Entra">
    <Steps>
      <Step title="Microsoft Entra에 로그인하기">
        [Microsoft Entra 관리 센터](https://entra.microsoft.com)에 로그인하세요.
      </Step>

      <Step title="VESSL Cloud 애플리케이션 만들기">
        검색창에서 <strong>Enterprise applications</strong>를 찾아 이동하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/entra-enterprise-apps.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=171075f0408cd20c217d5786a7e233a3" alt="Microsoft Entra 검색창에서 Enterprise applications를 찾는 화면" width="709" height="281" data-path="images/saml-sso/entra-enterprise-apps.png" />
        </Frame>

        <strong>+ New Application</strong>을 클릭한 뒤 <strong>+ Create your own application</strong>을 선택하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/entra-create-application.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=38ab53c85c334a8230d437c1dd2ae0b0" alt="Enterprise applications 페이지에서 New application 버튼이 강조된 화면" width="612" height="256" data-path="images/saml-sso/entra-create-application.png" />
        </Frame>

        애플리케이션 이름에 `VESSL Cloud`처럼 알아보기 쉬운 이름을 입력하고, <strong>Non-gallery</strong> 애플리케이션을 선택한 뒤 <strong>Create</strong>를 클릭하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/entra-name-app.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=a714f19c6a31083824725b55dfc05306" alt="Non-gallery 옵션이 선택된 애플리케이션 생성 패널" width="576" height="499" data-path="images/saml-sso/entra-name-app.png" />
        </Frame>
      </Step>

      <Step title="사용자 추가하기">
        애플리케이션을 만들면 **Overview** 페이지로 이동해요. <strong>1. Assign users and groups</strong>를 클릭한 뒤 <strong>+ Add user</strong>를 선택하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/entra-assign-users.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=a24c527f57ca3733c0b8216da480dae4" alt="사용자 할당 단계가 표시된 Entra 애플리케이션 Overview 페이지" width="780" height="412" data-path="images/saml-sso/entra-assign-users.png" />
        </Frame>

        VESSL Cloud를 사용할 사용자를 추가하고 <strong>Assign</strong>을 클릭하세요.
      </Step>

      <Step title="SAML SSO 설정하기">
        **Overview** 페이지로 돌아가 <strong>2. Set up single sign-on</strong>을 클릭하고, 로그인 방식으로 <strong>SAML</strong>을 선택하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/entra-select-saml.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=70935a10dfe22ec09769c08e2160e51d" alt="SAML이 강조된 Single sign-on 방식 선택 페이지" width="751" height="448" data-path="images/saml-sso/entra-select-saml.png" />
        </Frame>

        **Basic SAML Configuration**(Section 1)에서 <strong>Identifier (Entity ID)</strong>에는 **VESSL Cloud's metadata** URL을, <strong>Reply URL</strong>에는 <strong>SAML ACS URL</strong>을 입력하세요. [SP 설정 확인하기](#sp-설정-확인하기)에서 복사한 값을 쓰면 돼요. 입력을 마치면 <strong>Save</strong>를 클릭하세요.
      </Step>

      <Step title="메타데이터 URL 복사하기">
        Section 3에서 <strong>App Federation Metadata URL</strong>을 복사하세요. 다음 섹션에서 VESSL Cloud에 붙여 넣을 값이에요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/entra-metadata-url.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=70cc0ed9f7455cc6035110568e3c5c0a" alt="App Federation Metadata URL이 표시된 SAML certificates 섹션" width="764" height="273" data-path="images/saml-sso/entra-metadata-url.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="AWS IAM Identity Center">
    <Steps>
      <Step title="Applications 열기">
        AWS 콘솔에서 **IAM Identity Center** → <strong>Applications</strong>로 이동한 뒤 <strong>Add application</strong>을 클릭하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/aws-add-application.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=0ddb0a3ce958489e324c05eaedd347f9" alt="Add application 버튼이 있는 IAM Identity Center 애플리케이션 페이지" width="1517" height="484" data-path="images/saml-sso/aws-add-application.png" />
        </Frame>
      </Step>

      <Step title="애플리케이션 유형 선택하기">
        <strong>I have an application I want to set up</strong>을 선택하고 <strong>SAML 2.0</strong>을 선택하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/aws-choose-saml.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=cbe67bdff19d224dad35a9275e805465" alt="SAML 2.0이 선택된 애플리케이션 유형 선택 화면" width="1517" height="1065" data-path="images/saml-sso/aws-choose-saml.png" />
        </Frame>
      </Step>

      <Step title="애플리케이션 설정하기">
        설정 페이지에서 <strong>Display name</strong>에 `VESSL Cloud`처럼 알아보기 쉬운 이름을 입력하세요. <strong>IAM Identity Center SAML metadata file</strong>은 <strong>Download</strong>를 눌러 내려받아 두세요. 나중에 VESSL Cloud에 붙여 넣을 파일이에요.

        <strong>Application metadata</strong>에서 <strong>Manually type your metadata values</strong>를 선택하고, [SP 설정 확인하기](#sp-설정-확인하기)에서 복사한 URL로 아래 필드를 채워 주세요.

        | 필드                        | 값                              |
        | ------------------------- | ------------------------------ |
        | Application ACS URL       | **SAML ACS URL**               |
        | Application SAML audience | **VESSL Cloud's metadata** URL |

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/aws-configure-app.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=b69831c3464f6bea6b95a0f5369ad2ec" alt="Display name과 메타데이터 섹션이 있는 애플리케이션 설정 페이지" width="1517" height="966" data-path="images/saml-sso/aws-configure-app.png" />
        </Frame>
      </Step>

      <Step title="속성 매핑 편집 열기">
        애플리케이션 상세 페이지에서 **Actions** → <strong>Edit attribute mappings</strong>로 이동하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/aws-edit-attribute-mappings.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=bb6c6d293eaf179141614e4af674bb26" alt="Edit attribute mappings가 선택된 Actions 메뉴" width="981" height="455" data-path="images/saml-sso/aws-edit-attribute-mappings.png" />
        </Frame>

        속성 매핑을 다음과 같이 입력하세요.

        | User attribute | Maps to this string value | Format    |
        | -------------- | ------------------------- | --------- |
        | `Subject`      | `${user:email}`           | transient |
        | `email`        | `${user:email}`           | basic     |
        | `username`     | `${user:email}`           | basic     |

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/aws-attribute-mappings.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=b1979bf2521b75fea9e78fc3e0648e36" alt="Subject, email, username 행이 입력된 속성 매핑 테이블" width="1004" height="455" data-path="images/saml-sso/aws-attribute-mappings.png" />
        </Frame>
      </Step>
    </Steps>

    <Tip>
      IdP 설정을 마친 뒤 VESSL Cloud에서 <strong>IdP User ID</strong>에는 <code>username</code>을, <strong>IdP User email attribute</strong>에는 <code>email</code>을 입력하세요. [IdP 속성 이름 확인하기](#idp-속성-이름-확인하기)에서 자세히 확인할 수 있어요.
    </Tip>
  </Tab>

  <Tab title="Okta">
    <Steps>
      <Step title="Okta에 로그인하기">
        관리자 계정으로 Okta 조직에 로그인하세요.
      </Step>

      <Step title="VESSL Cloud 애플리케이션 만들기">
        관리 콘솔에서 **Applications** → <strong>Applications</strong>로 이동한 뒤 <strong>Create App Integration</strong>을 클릭하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/okta-create-app-integration.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=f47086ed17f1c1508f3f1bba743ad11e" alt="Create App Integration 버튼이 있는 Okta 애플리케이션 페이지" width="746" height="306" data-path="images/saml-sso/okta-create-app-integration.png" />
        </Frame>

        로그인 방식으로 <strong>SAML 2.0</strong>을 선택하고 <strong>Next</strong>를 클릭하세요. 앱 이름에 `VESSL Cloud`처럼 알아보기 쉬운 이름을 입력하고 <strong>Next</strong>를 클릭하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/okta-app-name.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=048c3c7de2e654c3370e960f70780805" alt="SAML 2.0 옵션이 선택된 Okta 앱 통합 마법사" width="783" height="559" data-path="images/saml-sso/okta-app-name.png" />
        </Frame>
      </Step>

      <Step title="SAML SSO 설정하기">
        [SP 설정 확인하기](#sp-설정-확인하기)에서 복사한 URL로 필수 필드를 채워 주세요.

        | 필드                          | 값                              |
        | --------------------------- | ------------------------------ |
        | Single sign-on URL          | **SAML ACS URL**               |
        | Audience URI (SP Entity ID) | **VESSL Cloud's metadata** URL |

        <strong>Attribute Statements</strong>에서 다음 속성을 설정하세요.

        | Name         | Name format   | Value        |
        | ------------ | ------------- | ------------ |
        | `user.email` | `Unspecified` | `user.email` |
        | `user.login` | `Unspecified` | `user.login` |

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/okta-attribute-statements.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=d23f3d133766ca1cbe279bef83b0e76d" alt="user.email과 user.login 행이 입력된 Okta Attribute Statements 테이블" width="740" height="341" data-path="images/saml-sso/okta-attribute-statements.png" />
        </Frame>

        <strong>Next</strong>를 클릭한 뒤 <strong>Finish</strong>를 클릭해 애플리케이션을 만드세요.
      </Step>

      <Step title="사용자 추가하기">
        앱 설정 페이지에서 <strong>Assignments</strong>로 이동하세요. **Assign** → <strong>Assign to People</strong>을 선택해 VESSL Cloud를 사용할 사용자를 추가하세요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/okta-assign-users.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=b082e1a8622a6f43b3e9adff175a50b0" alt="Assign to People 옵션이 표시된 Okta Assignments 탭" width="833" height="357" data-path="images/saml-sso/okta-assign-users.png" />
        </Frame>
      </Step>

      <Step title="메타데이터 URL 복사하기">
        **Sign On** 탭으로 이동해 **SAML 2.0** 섹션에서 <strong>Metadata URL</strong>을 복사하세요. 다음 섹션에서 VESSL Cloud에 붙여 넣을 값이에요.

        <Frame>
          <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/okta-metadata-url.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=96e2136998414d6a397b6132776507ac" alt="SAML 메타데이터 URL이 표시된 Okta Sign On 탭" width="703" height="515" data-path="images/saml-sso/okta-metadata-url.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="커스텀 IdP">
    <Steps>
      <Step title="필수 정보 입력하기">
        IdP 관리 콘솔에 접속해 [SP 설정 확인하기](#sp-설정-확인하기)에서 복사한 URL로 VESSL Cloud를 등록하세요.
      </Step>

      <Step title="메타데이터 URL 또는 XML 복사하기">
        설정을 마친 뒤 IdP가 제공하는 메타데이터 URL이나 XML을 복사하세요. 다음 섹션에서 VESSL Cloud에 붙여 넣을 값이에요.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## VESSL Cloud 설정하기

IdP 설정을 마쳤다면 IdP의 메타데이터를 VESSL Cloud에 등록하세요.

<Steps>
  <Step title="SAML SSO 설정 열기">
    사이드바에서 <strong>Settings</strong>를 선택한 다음, **Organization** 메뉴에서 <strong>SAML SSO</strong>를 선택하세요.
  </Step>

  <Step title="SAML SSO 추가하기">
    **IdP Configuration** 섹션에서 <strong>Add SAML SSO</strong>를 클릭하세요.
  </Step>

  <Step title="IdP 메타데이터 입력하기">
    <strong>Metadata XML</strong>에서 <strong>XML</strong>을 선택해 메타데이터 XML을 붙여 넣거나, <strong>URL</strong>을 선택해 IdP에서 복사한 메타데이터 URL을 입력하세요.

    <Frame>
      <img src="https://mintcdn.com/dora/gX3T8CXa13Bm4fHt/images/saml-sso/vessl-add-saml-sso.png?fit=max&auto=format&n=gX3T8CXa13Bm4fHt&q=85&s=b56340f85cb6002bd992a8f869a13063" alt="Metadata XML, IdP User ID, IdP User email attribute 입력란이 있는 IdP Configuration 폼" width="960" height="515" data-path="images/saml-sso/vessl-add-saml-sso.png" />
    </Frame>
  </Step>

  <Step title="속성 이름 입력하기">
    <strong>IdP User ID</strong>와 <strong>IdP User email attribute</strong>에 IdP가 SAML 응답에서 사용하는 속성 이름을 입력하세요. 올바른 값은 IdP마다 다르니 [IdP 속성 이름 확인하기](#idp-속성-이름-확인하기)를 참고해 주세요.
  </Step>

  <Step title="저장하기">
    <strong>Save</strong>를 클릭하세요. 설정이 완료되면 확인 메시지가 표시돼요. 저장할 때 `Failed to configure SAML SSO` 오류와 함께 `invalid IdP metadata` 메시지가 표시되면 메타데이터를 해석하지 못한 거예요. 메타데이터 XML 전체를 붙여 넣었는지, 메타데이터 URL이 정확한지 확인하고 다시 시도해 주세요.
  </Step>
</Steps>

<Warning>
  저장하는 순간부터 조직에 SAML SSO가 강제로 적용돼요. 멤버는 IdP를 통해 로그인해야 조직에 접근할 수 있고, 다른 방법으로 로그인한 세션은 조직에 접근할 수 없게 돼요. 설정을 저장한 본인의 세션은 자동으로 SSO 세션으로 전환되므로 로그아웃되지 않아요.
</Warning>

## SAML SSO로 로그인하기

설정을 마치면 멤버는 IdP를 통해 조직에 로그인해요.

<Steps>
  <Step title="SSO 로그인 시작하기">
    VESSL Cloud 로그인 페이지에서 <strong>Continue with SAML SSO</strong>를 클릭하세요.
  </Step>

  <Step title="조직 이름 입력하기">
    <strong>Organization name</strong>에 조직 이름을 입력하고 제출하세요. IdP 로그인 화면으로 이동해요.
  </Step>

  <Step title="IdP에서 인증하기">
    IdP에서 로그인을 마치면 조직 화면으로 돌아와요.
  </Step>
</Steps>

SSO로 로그인할 때 조직 멤버 여부에 따라 처리 방식이 달라요.

* VESSL Cloud 계정이 없는 사용자는 첫 SSO 로그인 때 계정이 자동으로 만들어지고 조직에 추가돼요.
* 이미 조직 멤버인 사용자는 그대로 로그인돼요.
* VESSL Cloud 계정은 있지만 조직 멤버가 아닌 사용자는 SSO로 로그인할 수 없어요. 먼저 [멤버 초대](/ko/admin/teams/invite-member)에서 초대해 주세요.

<Tip>
  CLI에서도 SSO로 로그인할 수 있어요. `vesslctl auth login`은 기본으로 브라우저에서 로그인을 진행하므로, 로그인 페이지에서 SAML SSO를 이용하면 돼요.
</Tip>

## IdP 속성 이름 확인하기

IdP는 SAML 응답의 속성(attribute)으로 사용자 ID와 이메일을 전달해요. VESSL Cloud는 <strong>IdP User ID</strong>와 <strong>IdP User email attribute</strong>에 입력한 속성 이름으로 이 값을 찾기 때문에, IdP 설정과 정확히 일치해야 해요.

사용하는 IdP에 맞는 값을 참고하세요.

<Tabs>
  <Tab title="Microsoft Entra">
    | 필드                       | 속성 이름                                                                |
    | ------------------------ | -------------------------------------------------------------------- |
    | IdP User ID              | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`         |
    | IdP User email attribute | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
  </Tab>

  <Tab title="AWS IAM Identity Center">
    | 필드                       | 속성 이름      |
    | ------------------------ | ---------- |
    | IdP User ID              | `username` |
    | IdP User email attribute | `email`    |
  </Tab>

  <Tab title="Okta">
    아래 값은 이 페이지의 Okta 설정 가이드를 따랐을 때 기준이에요. 커스텀 설정을 사용한다면 그에 맞게 조정하세요.

    | 필드                       | 속성 이름        |
    | ------------------------ | ------------ |
    | IdP User ID              | `user.login` |
    | IdP User email attribute | `user.email` |
  </Tab>

  <Tab title="커스텀 IdP">
    IdP 문서에서 사용자 ID와 이메일에 해당하는 속성 이름을 확인하세요. 필요하면 IdP 관리자에게 설정을 문의해 주세요.
  </Tab>
</Tabs>

## 함께 보기

* [조직 개요](/ko/admin/organization/overview)
* [멤버 초대](/ko/admin/teams/invite-member)