SSO(Single sign-on)

조직 마스터와 어드민은 SAML 2.0을 이용한 SSO (Single sign-on)을 활성화하고 SSO를 구성할 수 있습니다. SSO를 활성화 또는 비활성화하려면 관리자 콘솔 페이지를 열어야 합니다. 코어 메뉴 최하단에 있는 관리자 콘솔 항목을 클릭한 다음, SAML 구성 탭을 클릭하세요. 이때 관리자 콘솔은 웹 브라우저로 열립니다.

SAML 2.0 표준

Swit은 ID provider (IdP)의 계정 정보를 이용해 회원가입 및 로그인할 수 있도록 Single Sign-On (SSO)를 제공합니다. SSO는 IdP에서 단일 로그인으로 여러 SP에 액세스할 수 있는 개념으로, SSO를 통해 Swit을 이용하는 사용자들의 편의가 향상되며, 암호 재사용 및 암호 분실에 따른 위험도 줄어들어 조직 보안이 강화됩니다. 또한, 조직의 관리자는 멤버들의 계정과 접근 권한 등을 한 곳에서 집중적으로 관리할 수 있어 관리의 단순화를 통해 업무 효율성이 증대되는 효과를 볼 수 있습니다.

TIP

IdP(Identity Provider)는 사용자의 신원 정보를 제공, 저장 및 관리하는 시스템으로, Google Workspace와 Microsoft Entra ID (Azure Active Directory), Okta 등이 있습니다. SSO를 사용하는 조직에서는 로그인 시 아래와 같은 화면이 제공되며, 여기서 SSO로 계속하기 버튼을 클릭하면 연결된 IdP로의 로그인 화면으로 이어집니다.

Swit SSO 구성하기

SSO를 사용하려면 먼저 IdP에서 구성을 마친 후 Swit 관리자 콘솔에서 구성을 이어가세요.

IdP에서 구성하기

IdP에서 SSO를 구성하는 방법은 다음과 같습니다. Microsoft Entra ID (Azure Active Directory)와 Google Workspace, Okta의 경우 여기를 참고하세요.

SSO를 설정할 IdP에 접속합니다.
각 IdP의 매뉴얼을 참조하여 SAML 앱을 생성합니다.
Entity ID, Reply(ASC) URL 입력란에 아래와 같이 입력합니다. 각 레이블 명칭은 IdP별로 상이할 수 있습니다.
- Entity ID: https://<<ORG_DOMAIN_NAME>>.swit.io
- Reply URL: https://saml.swit.io/saml/acs
IdP에서 Swit에 연동하고자 하는 정보의 속성값을 매핑(mapping)합니다.
Swit 조직에 참여시킬 사용자들을 SAML 앱에 추가합니다.
- SAML 앱에 포함된 사용자들만 SSO를 통해 Swit 조직에 가입 및 로그인할 수 있습니다.
- 혹은 대부분의 IdP에서 모든 사용자가 SSO를 사용하게 하는 옵션을 제공하고 있는데, 이 옵션을 사용하면 개별 SAML 앱에 사용자들을 추가할 필요가 없습니다.

Swit(SP)에서 구성하기

Swit SSO를 구성하는 방법은 다음과 같습니다.

관리자 콘솔에 진입하여 SAML 구성을 선택합니다.
SAML을 이용한 single sign-on 활성화를 선택합니다.
관리자 콘솔의 아래 세 가지 항목을 IdP에서 복사하여 붙여 넣습니다. - SAML 2.0 Endpoint (HTTP) - IdP 발급자(Entity ID) - SAML 서명 인증서
페이지 내 추가 설정 옵션을 지정한 다음, 저장 버튼을 클릭합니다. 이때 해당 관리자의 IdP 계정으로의 인증을 거치게 되므로, IdP 측 SAML 앱에 관리자의 계정을 미리 추가해두어야 합니다.

Swit에 SSO 가능한 매핑 속성

Swit에서 사용하는 사용자 속성 명칭은 아래와 같으며, IdP의 각 속성과 매핑할 수 있습니다.

표시 이름
- Full name이 단일 속성인 경우: username
- 성과 이름이 구분된 경우: firstname + lastname
Swit에서 사용할 인터페이스 언어: language
연락처: tel
커스텀 필드: custom:<<CUSTOM_FIELD_ID>>

SSO 시 Swit 계정 매칭 기준

각 멤버가 SSO를 시도할 때, 아래의 우선순위에 따라 계정 매칭이 이루어집니다.

1순위: 해당 IdP 계정과 이미 연결된 Swit 계정이 있다면 해당 계정으로 로그인됩니다.
2순위: 위의 조건을 충족하는 Swit 계정이 없다면 이메일을 기준으로 Swit 계정이 매칭됩니다.
3순위: 매칭되는 계정이 아예 없다면 신규 계정이 생성됩니다.

SSO 구성 시 발생 가능한 에러 타입

1150: 입력한 SSO URL이 유효하지 않습니다. 다시 입력하십시오.
1151: SAML 응답에서 발급된 유효 IdP가 없습니다. 다시 입력하십시오.
1152: 인증서를 확인할 수 없습니다. 다시 입력하십시오.
1153: 비활성 상태이므로 계정에 액세스할 수 없습니다.
1157: 잘못된 SSO 사용자 이름(User Name)입니다.
1158: 잘못된 SSO 이름 아이디(Name Id)입니다.

각 멤버의 IdP 계정 연동하기

각 멤버가 SSO를 사용하려면 IdP 측 계정과 Swit 계정을 서로 연결해주어야 합니다. SAML 구성 최초 설정 또는 구성 변경 시 조직의 모든 멤버에게 SSO 연결 요청 메일이 전송되며, 각 멤버별로 최초 SSO 시도 시 자동으로 연결됩니다.

SSO 연결 메일 개별 발송

멤버가 현재 연결된 IdP 계정을 다른 계정으로 변경하려면 조직 관리자가 SSO 연결 메일을 발송해 주어야 합니다. SSO 연결 메일을 보내는 방법은 다음과 같습니다.

관리자 콘솔 > 멤버십 > 멤버 및 팀 항목을 선택합니다.
새로운 이메일 주소로 계정을 연결할 멤버를 목록에서 찾고, 우측의 더 보기 버튼을 클릭하여 SSO 연결 메일 보내기를 클릭합니다.

IdP별 연동 예시 보기

아래는 Microsoft Entra ID (Azure Active Directory)와 Google Workspace, Okta의 SSO 연동 예시입니다. SSO를 구성하고자 하는 IdP에 따라 연동 예시를 참고하세요.

Microsoft Entra ID (Azure Active Directory)

Microsoft Entra ID (Azure Active Directory)의 Potal에 접속하여 로그인한 다음, Azure Active Directory를 클릭합니다.
Enterprise applications 메뉴를 클릭한 다음 All applications를 선택합니다.
+ New application 버튼을 클릭한 다음 Swit을 검색하여 추가합니다.
Single sign-on 탭에서 SAML 버튼을 클릭합니다.
1번 영역의 Basic SAML Configuration에서 아래 항목에 맞게 입력합니다.
- Identifier (Entity ID): https://<<ORG_DOMAIN_NAME>>.swit.io
- Reply URL: https://saml.swit.io/saml/acs
1번 영역의 필수 입력란이 채워지면 2번 영역의 Edit 아이콘이 활성화됩니다. 2번의 User Attributes & Claims 우측 연필 아이콘을 클릭한 다음, 매핑(Mapping) 필수 정보를 참고하여 아래와 같이 Swit 측 사용자 속성과 매핑합니다.
- Unique User Identifier (Name ID) ↔ user.userprincipalname [nameid-format:emailAddress] (고정값)
- username ↔ user.displayname (필수 사항)
- per ↔ user.preferredlanguage (선택 사항)
- tel ↔ user.telephonenumber (선택 사항)
TIP

Azure AD Gallery에서 설치한 앱을 사용하는 경우 위와 같은 매핑 정보가 미리 설정되어 있습니다. 추가로 변경을 원하는 부분만 변경하면 됩니다.
모든 설정을 마친 후 Save 버튼을 클릭합니다.
SAML 활성이 완료되면 아래의 값들을 Swit SSO 구성 페이지에 붙여 넣습니다.
- Set up(4번 영역) > Login URL
- Set up(4번 영역) > Azure AD Identifier
- SAML Certificates(3번 영역) > Certificate (Base64)
왼쪽 패널에서 Users and groups 항목을 선택한 후 Swit 조직에 참여시킬 사용자들을 추가합니다.

Google Workspace

Google Workspace에서 SSO를 구성하는 방법은 다음과 같습니다.

Google Admin에 접속한 후, Apps 메뉴를 클릭합니다.
Web and mobile apps를 클릭합니다.
Add app을 열어 드롭다운 메뉴에서 Add custom SAML app을 클릭합니다.
App details 항목에서 필수 사항인 App name을 입력합니다. 선택 사항인 Description과 App icon도 필요 시 설정합니다. 설정을 마쳤으면 CONTINUE 버튼을 클릭합니다.
IdP인 Google Workspace에서 제공하는 SSO URL, entity ID, 그리고 certificate 정보가 표시됩니다. 각 정보를 복사한 다음 Swit 관리자 콘솔 > SAML 구성 경로로 진입하여 각각 SAML 2.0 Endpoint (HTTP), IdP 발급자(Entity ID), SAML 서명 인증서에 붙여 넣은 후 CONTINUE 버튼을 클릭합니다.
Service provider details 영역에서 ACS URL과 Entity ID에 아래 내용을 붙여 넣습니다.
- ACS URL: https://saml.swit.io/saml/acs
- Entity ID: https://<<ORG_DOMAIN_NAME>>.swit.io
Attribute 페이지에서 ADD MAPPING 버튼을 클릭하여 Swit 연동에 매핑(Mapping) 필수 정보를 입력합니다.
- Basic Information > Primary Email ↔ useremail
- Basic Information > First Name ↔ firstname
- Basic Information > Last Name ↔ lastname
위 매핑값을 모두 설정한 다음 FINISH 버튼을 클릭하면 Google 계정으로 SAML 활성이 완료됩니다.
Service provider details 페이지를 열어 Name ID 영역에서 다음과 같이 설정해야 SSO 구성이 가능합니다.
- Name ID format: PERSISTENT
- Name ID: Basic Information > Primary email
User access 영역에서 Swit 조직에 입장을 허용할 그룹을 선택합니다. ON for everyone을 선택하면 모든 사용자에게 액세스가 허용됩니다.

Okta

Okta directory서 SSO를 구성하는 방법은 다음과 같습니다.

Okta에 접속한 후, 관리자 계정으로 로그인합니다.
Applications 탭에서 Applications를 선택합니다.
Create App Integration 버튼을 클릭합니다.
SAML 2.0 항목 선택 후 Next 버튼을 클릭합니다.
1단계인 General Settings에서 앱 이름을 입력한 다음 나머지 옵션을
2단계인 Configure SAML에서 다음 과정을 수행합니다.
1. General 섹션에서 아래 값을 입력하여 SAML을 설정합니다.
  - Single sign on URL: https://saml.swit.io/saml/acs
  - Audience URI (SP Entity ID): https://<<ORG_DOMAIN_NAME>>.swit.io
2. Attribute Statements (optional) 섹션에서 매핑(Mapping) 필수 정보를 입력하고 Next 버튼 클릭 후 Finish 버튼을 클릭하여 설정을 마칩니다.