OAuth 2.0

개요

Tulip 생태계 내에서 강력하지만 종종 오해받는 인증 프로토콜인 OAuth 2.0을 살펴보는 자리에 오신 것을 환영합니다. 이 글에서는 OAuth 2.0의 기본 원리를 파헤치고, Tulip이 지원하는 인증 흐름을 안내하며, 초기 커넥터 구성 방법을 쉽게 설명하고, 원활한 시작을 위한 간단한 팁을 공유하겠습니다.

Tulip의 리프레시 토큰 처리, 범위 및 대상 관리, 사용자 정의 커넥터 구성에 대해서는 ‘기술적 세부 사항’ 섹션을 참조하십시오.

인증 유형

Tulip은 OAuth 2.0(서비스 계정), OAuth 2.0(사용자 자격 증명), OAuth 2.0(클라이언트 자격 증명)의 세 가지 OAuth 2.0 인증 유형을 지원합니다. 주요 차이점은 사용자 간에 자격 증명이 공유되는 방식과 OAuth 사양에 따라 실행되는 흐름에 있습니다. 고유한 OAuth 흐름에 대한 전체 목록과 설명은 다음 링크에서 확인할 수 있습니다: https://frontegg.com/blog/oauth-flows.

승인 코드 흐름:

• OAuth 2.0 (서비스 계정): Tulip Player의 모든 사용자에 대해 커넥터 테스트 시 제공된 자격 증명을 사용합니다. 조직 내에서 자격 증명을 공유하는 경우에 이상적입니다. 자격 증명 유효 기간이 만료되면 관리자의 재인증이 필요합니다.
• OAuth 2.0 (사용자 자격 증명): Tulip Player에 로그인한 사용자에 따라 인증을 구분합니다. 사용자가 아직 인증을 받지 않았거나 인증이 만료된 경우, 해당 사용자는 Tulip Player 내에서 OAuth 흐름을 거치게 됩니다.

클라이언트 자격 증명 흐름:

• OAuth 2.0 (클라이언트 자격 증명): 이 그랜트 유형은 Tulip이 클라이언트의 자격 증명(클라이언트 ID 및 클라이언트 시크릿)을 사용하여 인증 서버에 인증함으로써 액세스 토큰을 획득하는 데 사용되며, 일반적으로 사용자를 대신하기보다는 클라이언트 자체를 대신하여 리소스에 액세스하는 데 사용됩니다.

구체적인 내용을 살펴보기 전에, ‘환경(Environments) ’에 대해 숙지하고 커넥터 호스트(Connector Hosts) 및 그 기능에 대한 개요를 파악하는 것이 좋습니다.

OAuth 2.0은 Tulip(클라이언트)이 귀사의 비즈니스 시스템에 자신의 신원을 입증하는 메커니즘 역할을 합니다.

인증 코드 흐름

:::(경고) (경고)
사용자 인증 절차를 완료하려면 브라우저에서 팝업이 허용되어야 합니다. connector 에 여러 환경이 구성되어 있는 경우, 인증 과정에서 각 환경마다 별도의 팝업 창이 열립니다.

Chrome에서 팝업이 활성화되어 있는지 확인하세요:

1. Chrome을 열고 창 오른쪽 상단에 있는 점 세 개 메뉴를 클릭합니다.
2. 드롭다운 메뉴에서 ‘설정’을 선택합니다.
3. 아래로 스크롤하여 '개인정보 및 보안'을 클릭합니다.
4. '개인정보 및 보안' 섹션에서 '사이트 설정'을 클릭합니다.
5. 아래로 스크롤하여 '팝업 및 리디렉션'을 클릭합니다.
6. 토글 스위치가 '팝업 허용'으로 설정되어 있는지 확인하거나, 팝업 표시가 허용된 사이트 목록에 해당 웹사이트를 수동으로 추가하세요.

팝업이 차단된 경우, Chrome은 팝업이 차단될 때마다 주소 표시줄에 작은 아이콘을 표시합니다. 이 아이콘을 클릭하면 Tulip의 팝업을 빠르게 허용할 수 있습니다.
:::

접근 권한은 핸드셰이크를 통해 부여되며, Tulip은 가장 일반적인 OAuth 흐름인 '인증 코드 흐름( Authorization Code Flow)'을 주로 지원합니다. 이 흐름이 진행되는 방식에 대한 간략한 개요는 다음과 같습니다:

1. 사용자는 커넥터를 저장하기 전에 ‘테스트’ 버튼을 클릭하여 흐름을 시작합니다.
2. Tulip은 사용자의 OAuth 제공업체에 속한 인증 서버와 통신하며, 클라이언트 식별자, 범위(접근하려는 항목) 및 기타 관련 세부 정보와 같은 특정 매개변수를 공유합니다.
3. 인증 서버는 사용자에게 액세스 권한을 부여하도록 요청하며, 그 예시는 다음과 같습니다:

1. 사용자가 동의하면, 인증 서버는 인증 코드를 생성하고 인증 창을 닫습니다.
2. Tulip은 인증 코드를 확보한 후, 토큰 엔드포인트에 접속하여 인증 코드, 클라이언트 ID, 클라이언트 시크릿 및 추가 속성을 제공함으로써 안전하게 토큰을 요청합니다.
3. 인증 코드를 검증한 후, 서버는 토큰과 선택적으로 리프레시 토큰을 응답으로 반환합니다. 이 토큰은 사용자가 승인한 요청에 사용됩니다.
4. 이제 Tulip은 제공된 토큰을 인증 수단으로 사용하여 사용자를 대신해 요청을 실행할 수 있습니다.

실행 경로를 이해하려면 아래 다이어그램을 참조하십시오:

클라이언트 자격 증명 흐름

클라이언트 자격 증명 흐름은 주로 두 비즈니스 시스템 간의 상호 작용에 사용됩니다. 이 흐름은 한 번 구성되면 모든 사용자가 공유하게 됩니다.

1. 사용자는 커넥터를 저장하기 전에 ‘테스트’ 버튼을 클릭하여 이 흐름을 시작합니다.
2. Tulip은 사용자의 OAuth 제공업체에 속한 인증 서버와 통신하며, 클라이언트 ID, 범위(접근하려는 항목) 및 기타 관련 세부 정보와 같은 특정 매개변수를 공유합니다.
3. 인증 서버는 클라이언트 ID와 클라이언트 시크릿이 정확한 경우 액세스 토큰을 반환합니다. 선택적으로 리프레시 토큰도 반환될 수 있습니다. 이 토큰은 사용자가 승인한 요청에 사용됩니다.
4. 이제 Tulip은 제공된 토큰을 사용하여 인증을 받은 후 사용자를 대신하여 요청을 실행할 수 있습니다.

OAuth 구성

인증 코드 URL

이 URL은 인증 코드 흐름의 2단계에서 Tulip이 접속하는 주소입니다. OAuth 제공자의 API 문서에서 확인할 수 있으며, 일반적으로 /auth 또는 /authorize로 끝납니다.

참고: 클라이언트 자격 증명을 사용하는 경우 이 필드는 표시되지 않습니다.

액세스 토큰 URL

인증 서버의 응답 후, 인증에 필요한 토큰을 얻기 위해 액세스 토큰 URL로 요청이 전송됩니다. 일반적으로 /token으로 끝납니다.

클라이언트 ID 및 클라이언트 시크릿

OAuth 제공자의 UI에서 생성된 클라이언트 ID는 인증 코드를 요청하는 초기 요청과 함께 전달됩니다. 클라이언트 ID와 클라이언트 시크릿은 모든 토큰 요청에 포함됩니다.

기본 만료 시간(초)

이 필드는 만료 시간이 명시적으로 제공되지 않거나 expires_in 필드 외부의 다른 메커니즘을 통해 정의되지 않은 경우, 토큰이 갱신되는 기본 시간(초 단위)을 지정합니다.

대상 및 범위

Audience는 사용자가 접근을 요청하는 특정 자산을 지정하는 반면, Scope는 해당 자산에 대해 수행하고자 하는 작업을 정의합니다. 두 항목 모두 2단계의 인증 코드 요청 과정에서 전달됩니다.

추가 옵션

• 토큰 요청 데이터를 JSON으로 전송: 토큰 URL로 전송되는 요청의 인코딩 유형을 변경합니다. 특정 통합에 필요한 경우 이 옵션을 활성화하십시오.
• 갱신 요청에 인증 헤더 전송: 이 옵션을 활성화하면 갱신 요청에 추가 헤더가 포함됩니다.
• 사용자 동의 프롬프트 건너뛰기: 인증 코드 요청의 프롬프트 속성을 제어합니다. 비활성화하면 ‘동의’로 설정되고, 활성화하면 ‘로그인’으로 설정되어 OAuth 제공자가 표시할 로그인 화면을 결정할 수 있게 합니다.

기술적 세부 사항

다음은 Tulip이 지원하는 기능과 커넥터 인증을 위해 OAuth가 통합되는 방식에 대한 세부 정보입니다.

Tulip 인증 코드 흐름

Tulip은 애플리케이션 내에서 커넥터를 테스트하거나 커넥터 함수를 실행할 때 인증 프로세스를 시작합니다.

1. 인증 서버로 리디렉션

Tulip 애플리케이션은 response_type(인증 코드 흐름의 경우 "code"로 설정됨), client_id(커넥터 UI에서 할당됨), redirect_uri(Tulip에서 사전 정의됨), scope 및 audience(UI에서 설정됨), state(크로스 사이트 요청 위조(CSRF) 공격을 방지하기 위한 임의의 문자열)와 같은 특정 매개변수를 함께 사용하여 사용자를 인증 서버(AS)로 리디렉션합니다.

예시: GET /authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&audience=AUDIENCE&state=STATE

2. 사용자가 동의 부여

인증 서버는 사용자를 인증하고 동의 화면을 표시합니다. 사용자는 요청된 권한을 검토한 후 타사 애플리케이션에 대한 액세스를 허용할지 거부할지 결정할 수 있습니다.

:::(경고) (참고)
특정 connector 의 구성 내에서 “사용자 동의 프롬프트 건너뛰기” 제어 기능을 통해 인증 요청의 prompt 속성을 제어할 수 있습니다. 이 제어 기능이 비활성화되어 있으면 값 consent가 사용되며, 활성화되어 있으면 login이 사용됩니다.

prompt 속성에 추가 값이 필요한 경우 support@tulip.co으로 문의해 주시면, 해당 속성에 대한 추가 옵션을 활성화해 드리겠습니다.
:::

3. 인증 코드

사용자가 동의를 부여하면, 인증 서버는 인증 코드를 생성하고 해당 인증 코드와 함께 사용자를 Tulip으로 다시 리디렉션합니다. 또한 클라이언트가 응답의 무결성을 확인할 수 있도록 'state' 매개변수도 포함됩니다. 이 'state' 매개변수는 1단계에서 전달된 'state' 매개변수와 일치해야 합니다.

클라이언트의 리디렉션 URI로 리디렉션하는 예시:

REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE

4. 토큰 요청

이제 클라이언트는 인증 코드를 확보한 상태에서 이를 사용하여 인증 서버의 토큰 엔드포인트로 안전한 서버 간 요청을 보냅니다. 클라이언트는 grant_type(“authorization_code”로 설정됨), client_id, client_secret(클라이언트와 인증 서버만이 알고 있는 비밀), redirect_uri 및 인증 코드를 포함합니다.

토큰 요청 예시:

grant\_type=authorization\_code&code=AUTHORIZATION\_CODE&redirect\_uri=REDIRECT\_URI&client\_id=CLIENT\_ID&client\_secret=CLIENT\_SECRET```

### 5. 액세스 토큰 응답:

인증 코드가 유효한 경우, 인증 서버는 액세스 토큰과 선택적으로 리프레시 토큰을 포함하여 응답합니다. 액세스 토큰은 클라이언트가 사용자를 대신하여 보호된 API에 요청을 보낼 때 자신을 인증하는 데 사용됩니다.

**토큰 응답 예시:**

`{ "access_token": "ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN", "scope": "SCOPE"}`

:::(Warning) (Services Not Using `expires_in`)
  
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.  
:::

### 6. 리소스 서버에 접근하기

이제 Tulip은 획득한 액세스 토큰을 사용하여 사용자를 대신하여 리소스 서버(API)에 인증된 요청을 보낼 수 있습니다. 액세스 토큰은 일반적으로 HTTP 요청의 Authorization 헤더에 포함됩니다.

**API 요청 예시:**`GET /api/resource Authorization: Bearer ACCESS_TOKEN`

## 리프레시 토큰을 사용하여 토큰 만료 관리

인증 서버는 일반적으로 토큰의 만료일을 설정하여 액세스를 규제하며, 만료 기간은 연동된 시스템에 따라 다릅니다. 그러나 유효 기간이 짧은 토큰은 지속적인 사용자 인증이 Tulip 애플리케이션의 사용자 경험을 저해하기 때문에 문제가 됩니다.

이 문제를 해결하기 위해 OAuth는 리프레시 토큰을 지원합니다. 리프레시 토큰은 선택 사항이지만, 운영자의 수동 입력 없이도 Tulip이 토큰을 원활하게 갱신할 수 있게 하여 사용자 경험을 간소화하므로 적극 권장됩니다.

### Tulip은 토큰 갱신을 어떻게 관리하나요?

Tulip은 액세스 토큰이 만료된 것을 감지하면, 관련 리프레시 토큰을 사용하여 새로운 토큰을 획득하려고 자동으로 시도합니다. 주요 목적은 사용자의 재인증 횟수를 최소화하는 것입니다. 다음 단계는 Tulip이 실행하는 로직을 요약한 것입니다:

![Token Refresh Flow](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/image%28399%29.png)

**1. 만료 감지:** - Tulip은 인증 흐름의 [5단계에서](/r230/docs/oauth20-configuration-and-technical-details#5-access-token-response) 수신한 `expires_in` 속성을 기반으로 만료된 토큰을 식별합니다.

:::(Warning) (Services Not Using `expires_in`)
  
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.  
:::

**2. 토큰 흐름 시도:** - Tulip은 초기 인증 흐름에서 사용된 그랜트 유형을 대체하여 `refresh_token` 그랜트 유형을 사용하여 토큰 흐름을 시작합니다.

**3. 토큰 유효성 검사:** - 새 토큰을 획득하면, Tulip은 이를 저장하고 사용자가 요청한 ` connector function`을 실행합니다. - 성공하면 데이터가 Tulip 앱 런타임에 제공됩니다. - 새 토큰이 OAuth 오류로 실패하면, Tulip은 해당 과정을 최대 5회까지 재시도하며, 매번 1단계로 되돌아갑니다. - 새 토큰이 다른 오류로 실패하면, 플레이어 런타임에 오류 메시지가 표시됩니다.

**4. 토큰 부재 처리:** - 새 토큰이 제공되지 않으면, Tulip은 플레이어에서 사용자에게 인증을 요청하여 전체 인증 절차를 시작합니다. - 인증이 완료되면 connector function 이 실행되고 데이터가 반환됩니다.

리프레시 토큰을 구현함으로써 Tulip은 토큰 만료 및 갱신을 지능적으로 관리하여 워크플로우의 중단을 최소화하고, 더욱 원활한 사용자 경험을 보장합니다.

---

원하시는 정보를 찾으셨나요?

[community.tulip.co를](https://community.tulip.co/?utm_source=intercom&utm_medium=article-link&utm_campaign=all) 방문하여 질문을 게시하거나 다른 사용자들이 비슷한 문제를 겪은 적이 있는지 확인해 보세요!