OAuth2.0 구성 및 기술 세부 사항

이 글에서는 Tulip이 커넥터 인증을 위해 OAuth를 구현하는 방법에 대한 기술적 세부 사항을 자세히 살펴보겠습니다. OAuth는 강력하지만 약간의 복잡성이 추가됩니다. 이 가이드는 Tulip이 무엇을 지원하고 어떻게 통합되는지에 대한 기술적 질문을 해결하기 위한 것입니다.

참고: 클라이언트 자격증명 흐름은 인증 코드 흐름과 일부 다릅니다. 1단계와 2단계는 클라이언트 자격증명 흐름과 관련이 없습니다.

Tulip 인증 코드 흐름

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

1. 인증 서버로 리디렉션:

Tulip 애플리케이션은 응답 유형(인증 코드 흐름에 대해 "코드"로 설정), client_id(커넥터 UI에서 할당), redirect_uri(Tulip에서 미리 정의), 범위 및 대상(UI에서 설정), 상태(사이트 간 요청 위조 공격으로부터 보호하기 위한 임의 문자열) 등의 특정 매개변수와 함께 사용자를 권한 부여 서버(AS)로 리디렉션합니다.

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

2. 사용자가 동의를 부여합니다:

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

:::(경고) (참고) 부여 커넥터의 구성 내에서 '사용자 동의 프롬프트 건너뛰기' 컨트롤을 사용하면 권한 요청에 대한 프롬프트 속성을 제어할 수 있습니다. 이 컨트롤을 비활성화하면 동의 값이 사용되며, 활성화하면 로그인이 사용됩니다.

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

3. 인증 코드:

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

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

REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE

4. 토큰 요청:

이제 클라이언트는 인증 코드를 가지고 있으며 이를 사용하여 인증 서버의 토큰 엔드포인트에 안전한 서버 대 서버 요청을 합니다. 클라이언트에는 grant_type("authorization_code"로 설정됨), client_id, client_secret(클라이언트와 권한 부여 서버만 아는 비밀), redirect_uri 및 권한 부여 코드가 포함됩니다.

토큰 요청 예시

'''POST /tokenContent-Type: application/x-www-form-urlencoded

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", "토큰 유형": "무기명", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN", "scope": "SCOPE"}

6. 리소스 서버에 액세스하기:

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

API 요청 예: GET /api/resourceAuthorization: 베어러 ACCESS_TOKEN

토큰 새로 고침으로 토큰 만료 관리하기

권한 부여 서버는 일반적으로 토큰의 만료 날짜를 설정하여 액세스를 규제하며, 인터페이스하는 시스템에 따라 만료 기간이 다릅니다. 그러나 수명이 짧은 토큰은 지속적인 사용자 인증이 Tulip 애플리케이션의 사용자 경험을 방해하기 때문에 문제가 됩니다.

이 문제를 해결하기 위해 OAuth는 토큰 새로 고침을 지원합니다. 선택 사항이지만, 운영자의 수동 입력 없이도 토큰을 원활하게 새로 고칠 수 있어 사용자 경험을 간소화하므로 적극 권장합니다.

토큰 새로 고침을 관리하는 방법

Tulip은 액세스 토큰이 만료된 것을 감지하면 자동으로 연결된 새로 고침 토큰을 사용하여 새 토큰을 얻으려고 시도합니다. 주요 목표는 사용자 재인증을 최소화하는 것입니다. 다음 단계는 Tulip에서 실행되는 로직을 간략하게 설명합니다:

1. 만료 감지:
2. Tulip은 인증 흐름의 5단계에서 받은 expires_in 속성을 기반으로 만료된 토큰을 식별합니다.

1. 토큰 흐름 시도:

2. Tulip은 초기 인증 플로우에 사용된 부여 유형을 대체하여 refresh_token 부여 유형을 사용하여 토큰 플로우를 시작합니다.

3. 토큰 유효성 검사:

4. 새 토큰이 획득되면 Tulip은 토큰을 저장하고 사용자가 요청한 커넥터 기능을 실행합니다.

   • 성공하면 데이터가 Tulip 앱 런타임에 제공됩니다.
   • 새 토큰이 OAuth 오류로 실패하면 Tulip은 프로세스를 최대 5회까지 재시도하여 매번 1단계로 되돌아갑니다.
   • 새 토큰이 다른 오류와 함께 실패하면 플레이어 런타임에 오류가 표시됩니다.

5. 토큰 부재 처리:

6. 새 토큰이 제공되지 않으면 Tulip은 플레이어에서 사용자에게 인증을 받으라는 메시지를 표시하고 전체 인증 프로세스를 시작합니다.

7. 완료되면 커넥터 함수가 실행되고 데이터가 반환됩니다.

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

더 읽어보기

• Tulip 커넥터 호스트 소개
• 커넥터 스냅샷
• OAuth2.0 설명