애플리케이션에 OAuth 인증 사용하기

모든 Suite 플랜에서 사용 가능 모든 Support 플랜에서 사용 가능

빠른 보기: 관리 센터 > 앱 및 연동 서비스 > API > Zendesk API

OAuth 2를 사용하여 Zendesk에 대한 모든 애플리케이션의 API 요청을 인증할 수 있습니다. OAuth는 민감한 정보인 Zendesk 사용자들의 비밀번호를 저장 및 사용하지 않고서도 애플리케이션이 Zendesk 데이터에 액세스할 수 있는 안전한 방법을 제공합니다.

OAuth 인증을 사용하려면 애플리케이션을 Zendesk에 등록해야 합니다. 또한 OAuth 인증 플로우를 지원하기 위해 애플리케이션에 몇 가지 기능을 추가해야 합니다.

이 문서에서 다루는 주제는 다음과 같습니다.

애플리케이션을 Zendesk에 등록하기
애플리케이션에서 OAuth 권한 부여 플로우 구현하기

애플리케이션을 Zendesk에 등록하기

애플리케이션에서 Zendesk로의 API 호출을 인증하기 위해 사용할 수 있는 OAuth 자격 증명을 생성하도록 애플리케이션을 등록해야 합니다.

참고: 이 섹션에서는 하나의 Zendesk 계정을 가진 사용자들을 위한 OAuth 클라이언트 설정 방법에 대해 설명합니다. 애플리케이션이 하나의 Zendesk 계정이 아닌 많은 Zendesk 계정과 상호작용하는 경우에는 글로벌 OAuth 클라이언트를 요청할 수 있습니다. 글로벌 OAuth 클라이언트는 여러 Zendesk 인스턴스와 API 인증 작업을 하는 안전하고 확실한 방법입니다. 자세한 내용은 글로벌 OAuth 클라이언트 설정을 참조하세요.

애플리케이션을 등록하려면 다음과 같이 하세요.

관리 센터의 사이드바에서 앱 및 연동 서비스를 클릭한 다음 API > Zendesk API를 선택합니다.
Zendesk API 페이지에서 OAuth 클라이언트 탭을 클릭한 다음 OAuth 클라이언트 목록 오른쪽에 있는 OAuth 클라이언트 추가를 클릭합니다.
다음 필드를 완료하여 클라이언트를 만듭니다.
- 클라이언트 이름 - 앱의 이름을 입력합니다. 애플리케이션에 대한 액세스 권한 부여를 요청하고 Zendesk에 액세스할 수 있는 타사 앱 목록을 확인할 때 사용자들에게 표시되는 이름입니다.
- 설명 - 선택 사항으로 애플리케이션에 대한 액세스 권한 부여를 요청할 때 사용자들에게 표시되는 간략한 설명입니다.
- 회사 - 선택 사항으로 애플리케이션에 대한 액세스 권한 부여를 요청할 때 사용자들에게 표시되는 회사 이름입니다. 이 정보로 누구에게 액세스 권한을 부여하는지 이해하는 데 도움이 될 수 있습니다.
- 로고 - 선택 사항으로 애플리케이션에 대한 액세스 권한 부여를 요청할 때 사용자들에게 표시되는 로고입니다. JPG, GIF 또는 PNG 이미지를 사용할 수 있습니다. 최상의 결과를 위해 정사각형 이미지를 업로드하세요. 인증 페이지에 맞게 크기가 조정됩니다.
- 고유 식별자 - 앱에 입력한 이름의 서식이 다시 지정된 버전으로 이 필드가 자동으로 채워집니다. 원하면 변경할 수 있습니다.
- 클라이언트 종류 - 공개 또는 비공개. 공개 OAuth 클라이언트는 모바일 또는 웹 앱과 같이 자격 증명을 안전하게 저장할 수 없는 환경에서 실행되는 애플리케이션입니다. 이러한 클라이언트는 PKCE를 사용해야 합니다. 비공개 OAuth 클라이언트는 자격 증명을 안전하게 유지할 수 있는 안전한 서버에서 실행됩니다. 이러한 클라이언트는 PKCE, 클라이언트 비밀키 또는 둘 다 사용할 수 있습니다. OAuth 클라이언트 유형을 참조하세요.
- URL 리디렉션 - Zendesk가 사용자의 애플리케이션에 대한 액세스 권한 부여 결정을 보내는 데 사용해야 하는 URL을 입력합니다. 상대 경로가 아닌 절대 경로 URL이어야 하며 localhost 또는 127.0.0.1이 아닌 한 https로 시작하고 줄 바꿈으로 구분합니다.
저장을 클릭합니다.
페이지를 새로 고친 후 아래쪽에 새로 채워진 비밀키 필드가 표시됩니다. 이는 OAuth2 사양에서 지정된 “client_secret” 값입니다.
비밀키 값을 클립보드에 복사하여 다른 곳에 안전하게 저장합니다. 참고: 문자가 텍스트 상자 너비를 벗어날 수 있으므로 반드시 모든 문자를 선택한 후 복사하도록 하세요.
중요: 보안상의 이유로 전체 비밀키는 한 번만 표시됩니다. 저장을 클릭한 후에는 첫 9자만 액세스할 수 있습니다.
저장을 클릭합니다.

다음 주제에서 설명한 바와 같이 애플리케이션에 고유 식별자와 비밀키 값을 사용하세요.

OAuth 클라이언트 유형

Zendesk OAuth 클라이언트는 OAuth 클라이언트 만들기 중 전달되며 다음 값 중 하나를 가질 수 있는 kind 특성을 포함합니다.

공개: 공개 OAuth 클라이언트는 모바일 또는 웹 앱과 같이 자격 증명을 안전하게 저장할 수 없는 환경에서 실행되는 애플리케이션입니다. 이러한 클라이언트는 PKCE를 사용해야 합니다.
비공개: 비공개 OAuth 클라이언트는 자격 증명을 안전하게 유지할 수 있는 안전한 서버에서 실행됩니다. 이러한 클라이언트는 PKCE, 클라이언트 비밀키 또는 둘 다 사용할 수 있습니다.

자세한 내용은 클라이언트 유형을 참조하세요.

Zendesk OAuth 클라이언트 유형은 Zendesk Support 통합 티켓 관리 시스템에만 적용됩니다. Chat, Conversations 또는 Sell에서는 지원되지 않습니다.

기존 Zendesk OAuth 클라이언트에는 현재 kind 특성이 unknown으로 설정되어 있습니다. 이러한 클라이언트는 kind 특성이 public 또는 confidential로 업데이트될 때까지 영향을 받지 않습니다. 관리 센터에서 만들어진 새 OAuth 클라이언트는 만들기 중 kind 특성을 설정해야 합니다.

참고: 기존 Zendesk OAuth 클라이언트를 사용 중이며 kind 특성을 public으로 변경할 계획이라면 우선 PKCE를 구현해야 합니다. 그렇게 하지 않으면 PKCE가 즉시 필요하므로 클라이언트가 작동하지 않습니다.

관리 센터에서 만들어진 모든 새 OAuth 클라이언트에 대해 반드시 kind 특성을 설정해야 합니다. api/v2/oauth/clients endpoint로 만들어진 OAuth 클라이언트에는 kind 특성이 필요하지 않지만 Zendesk는 이를 포함할 것을 권장합니다.

애플리케이션에서 OAuth 권한 부여 플로우 구현하기

Zendesk는 액세스 토큰을 얻기 위해 인증 코드 권한 부여 플로우를 지원합니다. 이 플로우는 액세스 토큰을 요청하기 전에 인증 코드를 받아야 하므로 인증 코드 권한 부여 플로우라고 합니다. 다른 권한 부여 플로우는 더 이상 사용되지 않습니다.

이 플로우에서는 새로 고침 토큰을 사용하지 않으며, 액세스 토큰이 만료되지 않습니다.

인증 코드 권한 부여 플로우를 구현하려면 애플리케이션에 다음 기능을 추가해야 합니다.

1단계 - 사용자를 Zendesk 인증 페이지로 보내기
2단계 - 사용자의 권한 부여 결정 처리
3단계 - Zendesk에서 액세스 토큰 받기
4단계 - API 호출에서 액세스 토큰 사용

OAuth 권한 부여 플로우를 구현하는 웹 애플리케이션 구축에 대한 튜토리얼은 OAuth 웹 앱 구축하기를 참조하세요.

인증 코드 부여 방법은 보안을 더욱 강화하는 Proof Key for Code Exchange(PKCE)를 지원합니다. 자세한 내용은 개발자 문서에서 PKCE를 사용하여 Zendesk OAuth 액세스 토큰 보안 강화하기를 참조하세요.

1단계 - 사용자를 Zendesk 인증 페이지로 보내기

먼저, 애플리케이션에서 사용자를 Zendesk 인증 페이지로 보내야 합니다. 이 페이지에서 사용자에게 애플리케이션이 Zendesk에 액세스할 수 있도록 권한을 부여하도록 요청합니다. 사용자가 선택을 하면 Zendesk가 그 결정과 함께 몇 가지 다른 정보를 다시 애플리케이션에 보냅니다.

사용자를 Zendesk 인증 페이지로 보내려면 다음과 같이 하세요.

사용자를 다음 URL로 보내는 링크나 버튼을 애플리케이션에 추가합니다.

https://{subdomain}.zendesk.com/oauth/authorizations/new

여기서 {subdomain}은 회사 Zendesk 하위 도메인입니다. POST 또는 GET 요청을 사용할 수 있습니다. 다음 매개변수를 포함하세요.

response_type - 필수로 Zendesk가 응답에 인증 코드를 리턴하므로 응답 유형으로 code를 지정하세요. 예: response_type=code.
redirect_uri - 필수로 Zendesk가 사용자의 애플리케이션에 대한 액세스 권한 부여 결정을 보내는 데 사용해야 하는 URL입니다. URL은 상대 경로가 아닌 절대 경로여야 하며 localhost 또는 127.0.0.1을 사용하지 않는 한 보안(https) 주소여야 합니다.
client_id - 필수로 Zendesk에 애플리케이션을 등록할 때 받은 고유 식별자입니다. 위의 섹션을 참조하세요.
scope - 필수로 Zendesk 리소스에 대한 액세스를 제어하는 띄어쓰기로 구분된 범위 목록입니다. 모든 리소스 또는 특정 리소스에 대해 read, write 또는 impersonate 액세스를 요청할 수 있습니다. 범위 설정하기를 참조하세요.
state - 사용자가 액세스 권한을 부여할지 여부를 결정한 후 Zendesk에서 받는 응답에 포함된 임의의 문자열입니다. 교차 사이트 요청 위조(CSRF) 공격으로부터 보호하기 위해 이 매개변수를 사용할 수 있습니다. CSRF 공격은 최종 사용자를 속여 사용자가 인증되어 있는 웹 애플리케이션에서 작업을 수행하는 링크를 클릭하게 만듭니다. 이러한 종류의 공격으로부터 보호하려면 state 매개변수에 몇 가지 값을 추가하여 다시 돌아올 때 그 유효성을 검사하세요.
code_challenge - PKCE를 사용하는 경우 필수입니다. 코드 검증기에서 얻은 코드 챌린지를 나타내는 문자열입니다. 개발자 문서에서 code_challenge 값 생성하기를 참조하세요.
code_challenge_method - PKCE를 사용하는 경우 필수입니다. 코드 챌린지를 얻는 데 사용되는 방법입니다. 값으로 "S256"을 지정합니다.

반드시 매개변수를 URL로 인코딩하세요.

예제 GET 요청

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

최종 사용자의 브라우저에 Zendesk 인증 페이지가 열립니다. 사용자가 결정을 한 후 Zendesk가 그 결정을 요청에서 지정된 리디렉션 URL로 보냅니다.

범위 설정하기

Zendesk 리소스에 대한 앱의 액세스 권한을 제어하기 위한 범위를 지정해야 합니다. read 범위는 앱에 GET 엔드포인트에 대한 액세스 권한을 부여하며, 테스트용 앱 로드 관련 리소스에 대한 권한도 포함하고 있습니다. write 범위는 앱에 리소스를 만들고, 업데이트하고, 삭제하기 위한 POST, PUT 및 DELETE 엔드포인트에 대한 액세스 권한을 부여합니다.

범위에 대한 자세한 내용은 권한 부여 유형에 대한 OAuth 토큰을 참조하세요.

impersonate 범위는 Zendesk 관리자가 최종 사용자를 대신하여 요청을 할 수 있도록 합니다. 최종 사용자를 대신하여 API 요청하기를 참조하세요.

예를 들어 다음 매개변수는 앱에 모든 리소스에 대한 읽기 액세스 권한을 부여합니다.

"scope": "read"

다음 매개변수는 모든 리소스에 대한 읽기 및 쓰기 액세스 권한을 부여합니다.

"scope": "read write"

다음 리소스에 대한 범위를 미세 조정할 수 있습니다.

tickets
users
auditlogs(읽기 전용)
organizations
hc
앱
triggers
automations
targets
웹훅
zis

구문은 다음과 같습니다.

"scope": "resource:scope"

예를 들어 다음 매개변수는 앱이 티켓을 읽을 수만 있도록 제한합니다.

"scope": "tickets:read"

앱이 리소스를 읽고 쓸 수 있도록 하려면 두 범위를 모두 지정하세요.

"scope": "users:read users:write"

앱이 예를 들어 조직과 같은 한 리소스에 대해서만 쓸 수 있고 그 외 모든 리소스에 대해서는 읽을 수 있도록 하려면 다음과 같이 지정합니다.

"scope": "organizations:write read"

2단계 - 사용자의 권한 부여 결정 처리

애플리케이션은 사용자가 어떤 결정을 했는지 알리는 Zendesk의 응답을 처리해야 합니다. 이 정보는 리디렉션 URL의 URL 매개변수에 포함되어 있습니다.

사용자가 애플리케이션에 액세스 권한을 부여하기로 결정하면 리디렉션 URL에 인증 코드가 포함됩니다. 예:

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

인증 코드는 120초 동안만 유효합니다.

사용자가 애플리케이션에 액세스 권한을 부여하지 않기로 결정하면 리디렉션 URL에 사용자가 액세스 권한 부여를 거부했다고 앱에 알리는 error 및 error_description 매개변수가 포함됩니다.

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

이러한 값을 사용하여 애플리케이션의 플로우를 제어하세요. URL에 code 매개변수가 포함되어 있으면 다음 섹션에서 설명한 바와 같이 Zendesk에서 액세스 토큰을 받습니다. Zendesk에 보내는 API 호출에 이 토큰이 포함됩니다.

3단계 - Zendesk에서 액세스 토큰 받기

애플리케이션이 액세스 권한을 부여하는 사용자에 대한 응답으로 Zendesk에서 인증 코드를 받으면 애플리케이션이 이를 액세스 토큰과 교환할 수 있습니다. 액세스 토큰을 받으려면 다음 엔드포인트로 POST 요청을 하세요.

https://{subdomain}.zendesk.com/oauth/tokens

참고: 이 엔드포인트를 OAuth 토큰 API의 토큰 만들기 엔드포인트와 혼동하지 마세요. 두 엔드포인트가 모두 유효한 OAuth 액세스 토큰을 리턴하지만 엔드포인트들은 동일한 경로, JSON 형식 또는 요청 매개변수를 공유하지 않습니다.

요청에 다음의 필수 매개변수를 포함하세요.

grant_type - 값으로 “authorization_code”를 지정합니다.
code - 사용자가 액세스 권한을 부여한 후 Zendesk에서 받은 인증 코드를 사용합니다.
client_id - Support 관리자 인터페이스의 OAuth 클라이언트(관리자 > 채널 > API > OAuth 클라이언트)에서 지정된 고유 식별자를 사용합니다. 애플리케이션을 Zendesk에 등록하기를 참조하세요.
client_secret - Support 관리자 인터페이스의 OAuth 클라이언트(관리자 > 채널 > API > OAuth 클라이언트)에서 지정된 비밀키를 사용합니다. 애플리케이션을 Zendesk에 등록하기를 참조하세요.
PKCE code_challenge 및 code_verifier 매개변수를 사용하는 경우에는 client_secret이 필요하지 않습니다. 이 특성을 사용하여 보안 우려로 인해 더 이상 권장되지 않는 암시적 권한 부여 플로우에서 마이그레이션할 수 있습니다. 개발자 문서에서 PKCE를 사용하여 암시적 권한 부여 플로우에서 마이그레이션하기를 참조하세요.
redirect_uri - 1단계에서 사용한 것과 같은 리디렉션 URL입니다. ID 용도로만 사용됩니다.
scope - 범위 설정하기를 참조하세요.
code_verifier - PKCE를 사용하는 경우 필수입니다. code_challenge 값을 생성하는 데 사용되는 문자열입니다. 개발자 문서에서 code_challenge 값 생성하기를 참조하세요.

요청은 https를 통해 전송되어야 하며 특성은 JSON으로 서식 지정되어야 합니다. 사용자 지정 또는 제3자 애플리케이션을 사용하여 API 요청을 하는 경우에는 해당 문서에서 특성 값의 올바른 서식을 확인하세요.

curl 사용하기

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

예제 응답

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

4단계 - API 호출에서 액세스 토큰 사용

앱은 액세스 토큰을 사용하여 API 호출을 할 수 있습니다. 다음과 같이 요청과 함께 HTTP 권한 부여 헤더에 토큰을 포함하세요.

Authorization: Bearer {a_valid_access_token}

예를 들어 티켓을 나열하는 curl 요청은 다음과 같습니다.

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"