# Okta 연동

## 개요

Okta 연동을 통해 조직의 기존 ID 관리 시스템과 라운드HR을 통합할 수 있습니다. 이를 통해 임직원은 별도의 회원가입 절차 없이 Okta 계정으로 라운드HR에 접근할 수 있으며, 관리자는 중앙에서 사용자 접근을 통제할 수 있습니다.

### 핵심 이점

* **간편한 접근:** 임직원이 기존 Okta 계정으로 라운드HR에 로그인할 수 있습니다.
* **중앙화된 보안 관리:** Okta에서 사용자 접근 권한을 일괄 관리하여 보안을 강화합니다.
* **회원가입 절차 불필요:** 신규 입사자도 Okta 계정만 있으면 즉시 라운드HR 사용이 가능합니다.
* **퇴사자 자동 차단:** Okta에서 계정을 비활성화하면 라운드HR 접근도 자동으로 차단됩니다.

## 사전 준비

이 기능을 사용하기 위해서는 다음 조건이 필요합니다:

* **권한:** Okta 관리자(Admin) 권한
* **플랜:** 라운드HR Enterprise 플랜
* **기술 요건:** OIDC (OpenID Connect) 지원

{% hint style="success" %}
Okta 연동 도입 및 관련 문의는 전문 컨설턴트가 안내를 도와드리고 있습니다. 문의하기를 눌러 폼을 제출해 주시면 연락 드리겠습니다. ([**문의하기 >**](https://round.channel.io))
{% endhint %}

***

## 1. Okta 관리 콘솔에서 앱 추가

***

* Okta 관리 콘솔(<https://admin.okta.com>)에 로그인합니다.
* 좌측 메뉴에서 `[Applications]` > `[Applications]`를 클릭합니다.
* `[Create App Integration]` 버튼을 클릭하면 새 앱 생성 팝업이 나타납니다.

<figure><img src="https://3113620308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx3vbe9mozK3C5425TCxL%2Fuploads%2FVYNAY8G0V99i6q8zknjJ%2Fimage.png?alt=media&#x26;token=e03a4f7e-1444-4d96-b333-2eba019b5db5" alt=""><figcaption></figcaption></figure>

***

## 2. OIDC 앱 생성

***

* **Sign-in method:** `OIDC - OpenID Connect`를 선택합니다.
* **Application type:** `Web Application`을 선택합니다.
* `[Next]` 버튼을 클릭하면 앱 설정 화면으로 이동합니다.

{% hint style="info" %}
라운드HR은 OIDC(OpenID Connect) 프로토콜을 사용합니다. SAML이 아닌 OIDC를 선택해 주세요.
{% endhint %}

<figure><img src="https://3113620308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx3vbe9mozK3C5425TCxL%2Fuploads%2FOfAO74iHKENbg47qJZ0w%2Fimage.png?alt=media&#x26;token=45dd4b46-80ad-4bec-8083-46eaf006fb74" alt=""><figcaption></figcaption></figure>

***

## 3. 앱 기본 정보 입력

***

* **App integration name:** `roundHR` 또는 `라운드HR`을 입력합니다.

***

## 4. Sign-in redirect URI 설정

***

1. 라운드HR > 설정 > 서비스 연동 > Okta 로 접속합니다.
   1. <https://app.roundhr.com/setting/integration/data/okta?back=true>
2. 라운드HR에서 아래 정보를 복사하여 okta에 붙여넣어줍니다.

<table><thead><tr><th width="779.046875">항목</th></tr></thead><tbody><tr><td><strong>Sign-in redirect URI</strong></td></tr><tr><td><strong>Sign-out redirect URI</strong></td></tr></tbody></table>

<figure><img src="https://3113620308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx3vbe9mozK3C5425TCxL%2Fuploads%2FpnY8kMsCQKutgCbpq9be%2Fimage.png?alt=media&#x26;token=6ce9e3a1-dc5d-4d69-be88-0d83c995b949" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3113620308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx3vbe9mozK3C5425TCxL%2Fuploads%2FgjrkfCHXQ92kObP5kB4V%2Fimage.png?alt=media&#x26;token=8562a8a5-7638-46d0-ab69-23aacaddcd71" alt=""><figcaption></figcaption></figure>

`[Save]` 버튼을 클릭하면 앱이 생성되고 상세 페이지로 이동합니다.

***

## 5. Client Credentials 확인

***

앱 생성이 완료되면 **General** 탭에서 다음 정보를 확인할 수 있습니다:

| 설정 항목                      | 설정값                                      |
| -------------------------- | ---------------------------------------- |
| **Login initiated by**     | `Either Okta or App` 선택                  |
| **Application visibility** | `Display application icon to users` 체크   |
| **Initiate Login URI**     | `https://app.roundhr.com/account/sso` 입력 |

{% hint style="warning" %}
**Client Secret**은 이 화면에서만 확인할 수 있습니다. 반드시 안전한 곳에 저장해 주세요.
{% endhint %}

<figure><img src="https://3113620308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx3vbe9mozK3C5425TCxL%2Fuploads%2FhbZ9jObYkVvlPg4JHhAK%2Fimage.png?alt=media&#x26;token=331bc678-de81-4c71-9e90-b2cc99b3e824" alt=""><figcaption></figcaption></figure>

***

## 6. Issuer URL 확인

***

* 앱 상세 페이지에서 `[Sign On]` 탭을 클릭합니다.
* **OpenID Connect ID Token** 섹션에서 **Issuer** URL을 확인합니다.
* **Edit** 버튼을 클릭합니다
* **Issuer** 항목을 `Okta URL`로 선택합니다
* **Save** 버튼을 클릭합니다

{% hint style="info" %}
Issuer URL은 Okta 조직의 기본 도메인입니다. 커스텀 도메인을 사용 중인 경우 해당 도메인이 표시됩니다.
{% endhint %}

***

***

## 7. 사용자 할당

***

라운드HR에 접근할 수 있는 사용자를 지정해야 합니다.

* 생성한 라운드HR 앱에서 `[Assignments]` 탭을 클릭합니다.
* `[Assign]` 버튼을 클릭하고 `[Assign to People]` 또는 `[Assign to Groups]`를 선택합니다.
* 라운드HR을 사용할 사용자 또는 그룹을 선택하여 할당합니다.
* `[Done]` 버튼을 클릭하면 할당이 완료됩니다.

{% hint style="success" %}
**팁:** 부서별 그룹을 활용하면 신규 입사자가 해당 그룹에 추가될 때 자동으로 라운드HR 접근 권한이 부여됩니다.
{% endhint %}

***

## 8. 라운드HR에서 SSO 연동하기

***

연동 설정이 완료되면 정상 작동 여부를 테스트합니다.

* 라운드HR 로그인 페이지(<https://app.roundhr.com>)로 이동합니다.
* `[SSO로 로그인]` 버튼을 클릭합니다.
* 회사 이메일 주소를 입력합니다.
* Okta 로그인 페이지로 리다이렉트되면 Okta 계정으로 로그인합니다.
* 로그인 성공 시 라운드HR 홈 화면으로 이동합니다.

{% hint style="info" %}
SSO 로그인 시 입력하는 이메일의 도메인을 기준으로 Okta 연동 여부를 자동 판별합니다. 회사 도메인이 등록되어 있어야 SSO 로그인이 가능합니다.
{% endhint %}

### 9-1. SSO 연동 정보 입력

다음 정보를 Okta에서 복사하여 입력합니다:

<table><thead><tr><th width="141.78515625">입력 필드</th><th>Okta에서 확인하는 위치</th></tr></thead><tbody><tr><td><strong>Client ID</strong></td><td>General 탭 > Client Credentials</td></tr><tr><td><strong>Client Secret</strong></td><td>General 탭 > Client Credentials</td></tr><tr><td><strong>Issuer URL</strong></td><td>Sign On 탭 > OpenID Connect ID Token > Issuer</td></tr></tbody></table>

<figure><img src="https://3113620308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx3vbe9mozK3C5425TCxL%2Fuploads%2FGsE3I2AkSHOW7vjyc2ar%2Fimage.png?alt=media&#x26;token=4ef44400-9101-4027-b785-63ac09e4fbc3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Issuer URL 형식**

`https://`를 포함한 전체 도메인을 입력해야 합니다.

예시: `https://your-company.okta.com`
{% endhint %}

#### 9.2 연동 완료 및 로그인 테스트

연동이 성공적으로 완료되면:

* Okta 대시보드에서 라운드HR 앱 아이콘이 표시됩니다
* 라운드HR에 이메일 입력 후 바로 로그인할 수 있습니다

***

## 자주 발생하는 문제 (Troubleshooting)

<details>

<summary>로그인 시 "SSO 설정을 확인할 수 없습니다" 오류가 발생합니다</summary>

**1. 연동 상태 확인**

* 라운드HR에 Okta 연동이 완료되었는지 담당자에게 확인합니다.
* 조직의 도메인이 SSO 연동에 등록되어 있는지 확인합니다.

**2. Redirect URI 확인**

* Okta 앱 설정에서 Sign-in redirect URI가 정확한지 확인합니다.
* URL 끝에 불필요한 공백이나 슬래시(`/`)가 있는지 확인합니다.

</details>

<details>

<summary>로그인 시 "계정 정보를 확인할 수 없습니다" 오류가 발생합니다</summary>

**1. 이메일 주소 확인**

* 라운드HR에 등록된 이메일과 Okta 계정의 이메일이 일치하는지 확인합니다.
* Okta에서 로그인하는 이메일이 라운드HR에 미리 초대되어 있어야 합니다.

**2. 계정 생성**

* 라운드HR 관리자에게 해당 이메일로 사용자 초대를 요청합니다.

</details>

<details>

<summary>특정 사용자만 로그인이 안됩니다</summary>

**1. 사용자 할당 확인**

* Okta 앱의 `[Assignments]` 탭에서 해당 사용자가 할당되어 있는지 확인합니다.

**2. 사용자 상태 확인**

* Okta에서 해당 사용자 계정이 Active 상태인지 확인합니다.
* Suspended 또는 Deactivated 상태의 사용자는 로그인할 수 없습니다.

**3. 조직 확인**

* 해당 사용자가 라운드HR의 올바른 조직에 소속되어 있는지 확인합니다.

</details>

<details>

<summary>"초대 받은 이메일 주소로 로그인해 주세요" 오류가 발생합니다</summary>

**초대 이메일 확인**

* 초대 링크를 통해 가입하는 경우, 초대받은 이메일과 동일한 Okta 계정으로 로그인해야 합니다.
* 다른 이메일로 로그인을 시도하면 이 오류가 발생합니다.

</details>

<details>

<summary>Okta에서 로그아웃해도 라운드HR에 여전히 로그인 상태입니다</summary>

**Single Logout(SLO) 미지원**

* 현재 라운드HR은 Single Logout(SLO)을 지원하지 않습니다.
* Okta에서 로그아웃 후에도 라운드HR 세션이 유지될 수 있습니다.
* 라운드HR에서 별도로 로그아웃하거나, 브라우저를 완전히 종료해 주세요.

</details>

***

## 참고 자료

* [Okta 공식 OIDC 앱 설정 가이드](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)
* 추가 문의: [문의하기 >](https://round.channel.io)