Zendesk 개발자 플랫폼에서 401 및 403 오류 해결하기

Zendesk 개발자 플랫폼에서 구축 중이라면 어느 시점에서 401 또는 403 오류가 발생할 가능성이 있습니다. 이러한 두 가지 상태 코드는 특히 연동 서비스의 수명 주기 초기에 개발자로부터 받는 실패한 API 요청의 상당 부분을 차지합니다.

두 오류 모두 액세스 제어와 관련되어 있지만 매우 다른 이유로 실패하며 서로 다른 디버깅 접근 방식이 필요합니다. 상호 교환 가능한 것으로 취급하면 종종 시간 낭비와 반복적인 요청 실패로 이어집니다.

이 게시물에서는 Zendesk에서 401 및 403 오류가 작동하는 방식, 신속하게 진단하는 방법, 실용적인 예와 문제 해결 단계를 사용하여 자신 있게 해결하는 방법을 안내해 드립니다.

학습 내용

이 게시물을 마치면 다음 사항을 이해하게 될 것입니다.

Zendesk에서 401 Unauthorized와 403 Forbidden의 차이점
API 토큰, OAuth 액세스 토큰 및 JWT를 사용하여 올바르게 인증하는 방법
OAuth 범위가 권한 부여에 미치는 영향
잘못된 형식의 헤더, 잘못된 하위 도메인 및 만료된 자격 증명을 진단하는 방법

401과 403 비교 이해하기

두 상태 코드 모두 액세스 제어와 관련이 있지만 요청 처리의 서로 다른 단계에서 실패합니다.

401 권한 없음

401 응답은 Zendesk API가 요청을 인증할 수 없음을 의미합니다. Zendesk는 발신자가 누구인지 확인할 수 없으므로 권한이나 비즈니스 논리를 평가하지 않습니다.

일반적인 원인은 다음과 같습니다.

권한 부여 헤더가 없거나 형식이 잘못됨
기본 인증에 대한 잘못된 Base64 인코딩
잘못된 이메일 및 토큰 서식
만료되었거나 취소된 API 토큰
기본 인증 헤더에서 OAuth 토큰 사용하기
메시징에 대한 JWT가 올바르지 않거나 만료되었습니다.

401 오류가 발생하면 요청이 수행하려는 작업이 아닌 요청이 인증되는 방식에 먼저 집중하세요.

403 사용 권한 없음

403 응답은 요청이 성공적으로 인증되었지만 인증된 ID에 요청된 작업을 수행할 수 있는 권한이 없음을 의미합니다.

일반적인 원인은 다음과 같습니다.

OAuth 토큰에 필수 범위가 누락되었습니다.
최종 사용자 자격 증명을 사용하여 상담사 전용 엔드포인트 호출하기
다른 브랜드에 속한 리소스에 액세스하려고 시도하는 경우
계정에 IP 제한이 사용 설정됨
일시 중단되거나 다운그레이드된 상담사 계정

403 오류가 발생하면 인증이 올바르게 작동하는 것입니다. 문제는 권한 부여입니다.

빠른 진단 플로우

액세스 문제를 디버깅할 때 가장 빠른 방법은 문제를 단계적으로 격리하는 것입니다.

먼저 curl로 요청을 테스트하세요. curl 요청이 실패하면 애플리케이션 코드가 아니라 자격 증명이나 계정 구성에 문제가 있을 수 있습니다.

다음은 올바른 Zendesk 하위 도메인으로 전화를 걸고 있는지 확인합니다. 자격 증명은 특정 환경으로 범위가 지정되며 샌드박스와 프로덕션 토큰은 서로 바꾸어 사용할 수 없습니다.

그런 다음 올바른 인증 방법을 사용하고 있는지 확인합니다. 기본 인증, OAuth 및 JWT 인증을 함께 사용하는 것이 일반적인 실패 원인입니다.

인증된 사용자의 역할을 확인합니다. 인증에 성공하더라도 많은 엔드포인트에 상담사 또는 관리자 권한이 필요합니다.

OAuth 사용하는 경우에는 토큰에 엔드포인트에 필요한 범위가 포함되어 있는지 확인합니다.

마지막으로 요청이 실행 중인 곳을 고려하세요. API 토큰 기본 인증 또는 기타 지원되지 않는 클라이언트 측 플로우를 사용할 때 브라우저 출처 요청은 종종 브라우저 간 리소스 공유(CORS) 정책에 의해 차단됩니다. 브라우저에서 API를 호출해야 하는 경우에는 CORS를 지원하는 OAuth 플로우를 사용하거나, ZAF 클라이언트를 사용하여 백엔드 서비스나 Zendesk 앱을 통해 요청을 라우팅하세요. CORS 요청에 대한 자세한 내용은티켓 작성 API에 클라이언트 측 CORS 요청하기를참조하세요.

올바르게 인증하기

권한이나 비즈니스 논리 확인 전에 인증이 이루어집니다. 인증에 실패하면 Zendesk가 요청을 사용자나 연동 서비스와 연결할 수 없으며 401 오류를 리턴합니다.

Zendesk는 여러 인증 방법을 지원하며, 각각 엄격한 서식 요구 사항이 있습니다.

API 토큰 인증

API 토큰은 사용자 이름에 /token 접미어를 포함하는 기본 인증을 사용합니다.

올바른 형식은 다음과 같습니다.

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

401 오류가 발생하는 일반적인 실수는 다음과 같이/token접미어를 생략하는 것입니다.

emailAddress:APITOKEN

Node.js에서 작동하는 예는 다음과 같습니다.

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

OAuth 인증

OAuth 액세스 토큰은 일반적으로 장기 자격 증명이나 세분화된 권한 제어가 필요한 연동 서비스에 사용됩니다. Bearer인증 체계를 사용하여 OAuth 토큰을 보내야 합니다. 올바른 헤더 형식은 다음과 같습니다.

Authorization: Bearer ACCESS_TOKEN

curl을 사용한 요청 예:

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

Node.js에서 작동하는 예는 다음과 같습니다.

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

OAuth 사용할 때401 권한이 부여되지 않음오류가 발생하는 일반적인 원인은 잘못된 인증 체계로 올바른 액세스 토큰을 보내는 것입니다. 이 경우 Zendesk는 요청을 인증할 수 없으며 범위나 권한을 평가하기 전에 401을 리턴합니다.

OAuth 토큰은 토큰이 수행할 수 있는 작업을 명시적으로 정의하는범위의 개념도 도입합니다. 토큰이 성공적으로 인증될 수 있지만 호출되는 엔드포인트에 필요한 범위가 부족한 경우에는 여전히403 금지응답을 리턴합니다.

예를 들어ticket:read가있는 토큰은 티켓 데이터를 가져올 수 있지만 티켓을 만들거나 업데이트할 수는 없습니다. 적절한 범위 없이 쓰기 작업을 시도하면 계속해서 403 오류가 발생합니다.

403: You do not have access to this resource

이 경우 인증이 예상대로 작동하지만 올바른 범위로 토큰을 다시 생성해야 합니다. 범위에 대한 자세한 내용은권한 부여 유형에 대한 OAuth 토큰을참조하세요.

메시징을 위한 JWT 인증

웹 또는 모바일 애플리케이션에서 Zendesk 메시징을 구현할 때 최종 사용자를 안전하게 식별하기 위해 JWT 인증이 사용됩니다. 이 모델에서는 백엔드가 관리 센터 에서 구성된 비밀키를 사용하여 JSON 웹 토큰(JWT)을 생성하고 서명하는 일을 담당합니다. Zendesk는 메시징 세션이 사용자와 연결되도록 허용하기 전에 토큰의 유효성을 검사합니다.

API 토큰이나 OAuth 와 달리 메시징 JWT에는 Zendesk가 사용자의 ID를 올바르게 확인할 수 있도록 특정 클레임 및 헤더 정보가 필요합니다.

메시징 JWT에는 최소한 다음이 포함되어야 합니다.

kid– Zendesk 관리 센터 의 키 ID입니다. 페이로드가 아닌 JWT 헤더에 포함되어야 합니다.
external_id– 사용자의 고유 식별자입니다. Zendesk는 사용자 레코드를 일치시키거나 만들 때 이 값을 기본 키로 사용합니다.
scope– 토큰이 메시징에서 최종 사용자 인증을 위한 것임을 나타내는 “user”로 설정되어야 합니다.

name,email및email_verified등의 추가 클레임은 선택 사항이며 상담사 인터페이스에서 사용자 세부 정보를 채우거나 이메일 기반 ID 일치를 지원하기 위해 포함될 수 있습니다.

Node.js JWT 생성기 예:

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
	keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

external_id 또는 scope와 같은 필수 클레임이 없거나 토큰이 잘못된 비밀키로 서명된 경우에는 Zendesk가 401 Unauthorized 응답을 리턴합니다.

JWT 관련 401 오류의 일반적인 원인은 다음과 같습니다.

잘못된 환경에서 JWT 비밀키 사용하기(샌드박스와 프로덕션)
만료된 토큰 또는 잘못된 시간 기반 클레임이 있는 토큰 보내기
external_id 또는 scope와 같은 필수 클레임 생략하기
올바르지 않거나 순환된 비밀키를 사용하여 토큰에 서명하기
형식이 잘못되었거나 잘못 인코딩된 JWT 보내기

메시징 인증 문제를 디버깅할 때에는 먼저 토큰이 올바른 비밀키로 서명되어 있고 필요한 클레임이 포함되어 있는지 확인하세요. 인증에 성공했지만 사용자 ID 동작이 예기치 않은 경우에는 external_id 및 모든 선택적 ID 필드에 사용된 값을 검사하여 세션 간에 안정적이고 일관된지 확인하세요. 자세한 내용은애플리케이션에서 사용자 인증하기를참조하세요.

401 오류의 일반적인 원인

401 응답은 Zendesk가 요청을 인증할 수 없고 발신자의 신원을 확인할 수 없음을 의미합니다.

이는 대부분 잘못 구성된 권한 부여 헤더, 사용 중지된 토큰 또는 환경 불일치로 인해 발생합니다.

기본 인증 헤더는 아래와 같거나 이에 상응하는 형식이어야 합니다.

headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
}

예기치 않은 문자, 공백 또는 인코딩 문제로 인해 종종 자동 오류가 발생합니다.

마지막으로 Zendesk REST API는 브라우저 출처 인증을 지원하지 않습니다. 클라이언트 측 JavaScript 요청은 CORS, 누락된 세션 쿠키 및 지원되지 않는 인증 플로우로 인해 실패합니다. 대신 백엔드 서비스나 ZAF 클라이언트로 구축된 Zendesk 앱을 사용하세요.

403 오류의 일반적인 원인

403 응답은 Zendesk가 요청을 인증했지만 권한 규칙으로 인해 액세스가 거부되었음을 나타냅니다.

가장 일반적인 원인은 OAuth 범위 누락입니다. 예를 들어 ticket:read가 있는 토큰은 티켓을 가져올 수 있지만 티켓을 만들거나 업데이트할 수는 없습니다. 쓰기 시도가 계속해서 403 오류를 리턴합니다.

토큰을 만든 후에는 OAuth 범위를 수정할 수 없습니다. 범위가 올바르지 않으면 새 토큰을 생성해야 합니다.

또 다른 일반적인 혼동 원인은 최종 사용자 자격 증명을 사용하여 상담사 전용 엔드포인트를 호출하려고 시도하는 것입니다. 최종 사용자 OAuth 토큰은/users/me에 대해 작동할 수 있지만 티켓, 보기 또는 티켓 필드와 같은 제한된 엔드포인트를 호출할 때에는 403을 리턴합니다.

다른 빈번한 원인으로는 취소된 토큰, IP 허용 목록 제한 및 멀티브랜드 액세스 제한이 있습니다. 이러한 경우에는 자격 증명이 더 이상 활성 상태가 아니거나 사용자가 특정 액세스 기준을 충족하지 못하기 때문에 요청이 거부됩니다.

단계별 문제 해결 방법

1. 따로따로 자격 증명 검증확실하지 않은 경우에는 등식에서 애플리케이션 코드를 제거하는 것부터 시작하세요. curl을 사용하여 자격 증명을 확인합니다.

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

실패하는 경우: 자격 증명 또는 계정 관련 문제일 수 있습니다.
성공하면 다음과 같이 됩니다. 자격 증명이 유효합니다. 애플리케이션 논리 또는 환경 내에 문제가 있습니다. 2단계로 이동합니다.

2. CORS 제한 사항 확인: curl 명령은 작동하지만 클라이언트 측 애플리케이션이 실패하면 CORS 제한에 도달할 가능성이 있습니다.

브라우저의 개발자 콘솔을 열고 오류를 검사합니다. Access-Control-Allow-Origin에 관한 콘솔 메시지와 함께 401/403 오류가 표시되면 Zendesk에서 요청을 처리하기 전에 브라우저가 요청을 차단하는 것입니다.

3. 원시 요청 헤더 검사서버 측 코드(Node.js, Python, PHP 등)를 실행하면서 여전히 문제가 발생하는 경우:

Authorization 헤더를 로깅합니다. 애플리케이션에서 보내는 정확한 문자열을 인쇄하세요. 숨겨진 공백 문자나 잘못된 접두어가 없는지 확인합니다(예: Basic과 Bearer가 올바르게 사용되도록 보장).
환경 확인: 애플리케이션이 올바른 하위 도메인을 대상으로 하고 있는지 확인합니다. 실수로 프로덕션 자격 증명으로 샌드박스 URL을 대상으로 하거나 그 반대의 경우도 종종 있습니다.

4. 범위 및 클레임 확인인증에 성공했지만 403 Forbidden 메시지가 표시되면 토큰에 필요한 권한이 부족할 수 있습니다.

OAuth 의 경우: /api/v2/oauth/tokens/current엔드포인트를 호출하여 현재 범위를 확인합니다. 액세스하려는 리소스에 필요한 범위가 토큰에 있는지 확인합니다.
메시징/JWT의 경우: JWT 페이로드를 다시 검증합니다. 키(키 ID)가 Zendesk 구성과 일치하고 토큰을 생성하는 데 사용된 서명 비밀키가 올바른지 확인합니다.

최종 생각

Zendesk 개발자 플랫폼에서 발생하는 대부분의 401 및 403 오류는 소수의 예측 가능한 구성 오류에서 발생합니다. 인증 실패와 권한 부여 실패를 명확하게 구분하면 디버깅 속도와 안정성이 훨씬 높아집니다.

조기에 자격 증명의 유효성을 검사하고, 범위와 역할을 확인하고, 구조화된 진단 접근 방식에 따라 이러한 문제를 신속하게 해결하고 프로덕션에서 다시 표시되는 것을 방지할 수 있습니다.

자세한 내용은API 토큰 액세스,OAuth 인증, Zendesk 앱 프레임워크및메시징 JWT 인증에 대한 Zendesk 문서를 참조하세요.

번역 고지 사항: 본 문서는 콘텐츠에 대한 기본적인 이해를 제공하기 위해 자동 번역 소프트웨어를 사용하여 번역되었습니다. 정확한 번역을 제공하고자 합당한 노력을 기울였으나 Zendesk는 번역의 정확성을 보장하지 않습니다.

번역된 문서에 포함된 정보의 정확성과 관련하여 질문이 있으시면 문서의 공식 버전인 영문 버전을 참조하시기 바랍니다.