> For the complete documentation index, see [llms.txt](https://guide.roundhr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.roundhr.com/setting/integrations/services/sso/okta.md).

# 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="/files/qbyuRQ3122vuV0SBX6ua" 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="/files/zaE01gyeoEl75OF1GCvs" 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="/files/TqyuSKN2c7yLCCMI6Vz5" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Qj9P172tLtDMrETbrnQE" 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="/files/8N52GYq1OUcDul64EHD0" 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="/files/BNmj2DCFoQ6hL8hEb6q3" 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guide.roundhr.com/setting/integrations/services/sso/okta.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.