토큰

옷가게 쇼핑몰을 만들었다고 생각해 보세요. 콘텐츠 스튜디오에 등록해 둔 상품을, 손님이 보는 쇼핑몰 사이트에서 불러다 보여주고 싶습니다. 그런데 그 사이트는 사람이 아니라 프로그램입니다. 사람처럼 아이디와 비밀번호로 로그인할 수 없습니다. 이럴 때 사람 대신 사이트나 프로그램이 콘텐츠에 접근할 수 있도록 발급하는 비밀 열쇠가 토큰입니다.

토큰은 자물쇠를 여는 열쇠 하나라고 생각하면 됩니다. 이 열쇠를 가진 쪽은 로그인 없이도 정해진 범위 안에서 콘텐츠를 다룰 수 있습니다. 그래서 토큰은 비밀번호와 똑같이 다뤄야 합니다. 아무에게나 보여 주면 안 되고, 새어 나가면 가진 사람이 그 권한을 그대로 쓸 수 있습니다.

WEEGLOO에는 쓰임이 다른 세 종류의 열쇠가 있습니다. 계정 전체를 대신하는 강력한 열쇠(Personal Access Token), 한 Space 안에서 콘텐츠를 읽고 쓰는 열쇠(Space Access Token), 공개 사이트에 콘텐츠를 읽어 보내기 위한 읽기 전용 열쇠(Delivery Access Token)입니다. 이 페이지에서는 세 열쇠가 각각 무엇이고 언제 쓰는지 살펴본 뒤, 콘텐츠 스튜디오에서 직접 발급해 봅니다.

세 열쇠는 쓰임이 다릅니다

먼저 셋의 차이를 한눈에 정리하면 다음과 같습니다.

핵심은 이렇습니다. Personal Access Token은 계정 한 사람을 통째로 대신하는 만능열쇠에 가깝고, Space Access Token은 한 Space 안에서만 콘텐츠를 읽고 쓰는 열쇠, Delivery Access Token은 발행된 콘텐츠를 읽어 가기만 하는 읽기 전용 열쇠입니다. 하려는 일이 계정 전체에 걸치는지, 한 Space 안에서 쓰기까지 하는지, 공개 사이트에서 읽기만 하는지에 따라 맞는 열쇠를 고르면 됩니다.

계정 전체를 대신하는 열쇠: Personal Access Token

Personal Access Token은 발급한 계정 본인의 권한을 그대로 쓰는 열쇠입니다. 이 열쇠를 쓰면, 그 계정이 콘텐츠 스튜디오에서 할 수 있는 일을 로그인 없이 그대로 할 수 있습니다. 상품을 등록하거나, 수정하거나, 발행하는 관리 작업까지 가능합니다.

그래서 이 열쇠는 강력합니다. 사람 대신 콘텐츠를 자동으로 올리고 고치는 프로그램에 쥐여 주면, 그 프로그램이 계정 주인처럼 일할 수 있습니다. 여러 Space를 오가거나 Space 설정까지 다뤄야 하는 관리 작업이라면 이 열쇠가 필요합니다. 반대로 한 Space 안에서 콘텐츠만 읽고 쓰면 되는 일이라면, 계정 전체를 대신하는 이 열쇠 대신 뒤에서 설명하는 Space Access Token으로 권한을 좁혀 두는 편이 안전합니다.

강력한 만큼 다루는 데 주의가 필요합니다. 이 열쇠는 손님에게 전달되는 공개 클라이언트에 넣으면 안 됩니다. 공개된 곳에 넣으면 누구나 열쇠를 꺼내 볼 수 있고, 그 열쇠를 손에 넣은 사람은 발급한 계정의 권한을 그대로 쓸 수 있기 때문입니다. 공개 사이트에서 상품을 불러다 보여 주기만 할 때는, 강력한 이 열쇠 대신 아래의 Delivery Access Token을 씁니다.

Personal Access Token은 발급할 때 이름만 정하면 됩니다. 권한 범위를 따로 고르지 않습니다. 발급한 계정이 가진 권한을 그대로 물려받기 때문입니다.

한 Space에서 읽고 쓰는 열쇠: Space Access Token

Space Access Token은 특정 한 Space 안에서만 쓰는 열쇠입니다. Delivery Access Token이 읽기만 되는 것과 달리, 이 열쇠로는 그 Space 안의 콘텐츠를 읽는 것은 물론 쓰는 것까지 할 수 있습니다. 상품을 새로 등록하거나 고치는 일을, 사람이 로그인하지 않아도 프로그램이 대신 할 수 있습니다.

예를 들어 손님이 로그인하지 않고도 옷가게 사이트에 문의 글을 남길 수 있게 하고 싶다고 생각해 보세요. 손님이 쓰는 클라이언트가 그 글을 옷가게 Space에 새로 써 넣어야 하는데, 읽기 전용인 Delivery Access Token으로는 글을 쓸 수 없습니다. 그렇다고 계정 전체를 대신하는 Personal Access Token을 클라이언트에 두면, 그 열쇠가 새어 나갔을 때 옷가게뿐 아니라 계정이 닿는 모든 곳이 위험해집니다. 이럴 때 쓰는 것이, 한 Space 안에서만 쓰기까지 되는 Space Access Token입니다. 손님 클라이언트에서 콘텐츠를 쓰게 하는 이런 경우가 이 열쇠의 대표적인 쓰임이고, 서버에서 콘텐츠를 자동으로 등록·수정할 때도 씁니다.

Space Access Token은 한 Space 안에서만 통합니다. 옷가게 Space의 콘텐츠를 읽고 쓸 수는 있어도, 다른 Space를 들여다보거나, Space의 설정을 바꾸거나, 조직과 계정을 건드리는 일은 하지 못합니다. 그래서 같은 쓰기 작업이라도 Personal Access Token보다 안전합니다.

이 열쇠를 어디에 둘지는 쓰임에 따라 정합니다. 서버에 둘 수도 있고, 손님이 쓰는 클라이언트에 둘 수도 있습니다. 안전은 열쇠를 어딘가에 숨겨서가 아니라, 묶는 역할을 그 쓰임에 맞게 좁혀서 지킵니다. 그래서 다음으로, 역할을 어떻게 묶는지가 중요합니다.

역할을 묶어 읽고 쓸 범위를 정하세요

Space Access Token을 발급할 때도 이 열쇠가 어디까지 할 수 있는지를 SpaceRole(역할)로 정해서 함께 묶습니다. Delivery Access Token의 역할이 "어디까지 읽을 수 있는지"를 정하는 것과 달리, Space Access Token의 역할은 "어디까지 읽고 쓸 수 있는지"를 정합니다.

묶는 역할은 그 열쇠가 어디에 놓이는지에 맞춰 좁힙니다. 서버에서 상품을 자동으로 등록·수정하는 열쇠라면, 상품(Content)에 대해 Read·Create·Edit만 허용하고 Delete·Publish는 넣지 않은 역할을 묶습니다. 반면 손님 클라이언트에 두어 문의 글만 받는 열쇠라면, "문의 글"을 새로 만드는 것(Create)만 허용하는 더 좁은 역할을 묶습니다. 그러면 이 값이 새어 나가더라도 각각 허용한 것 밖으로는 아무것도 할 수 없습니다.

모든 것을 다룰 수 있는 Administrator 역할은 묶지 마세요. 쓰기까지 되는 열쇠일수록, 특히 손님이 볼 수 있는 곳에 두는 열쇠일수록, 새어 나가도 감당할 수 있을 만큼 좁은 역할을 묶어야 안전합니다.

쓰기를 허용하는 역할을 만드는 방법은 역할과 권한에서 다룹니다. 그 페이지에서 만드는 "상품 등록 담당" 역할이, 상품을 등록·수정까지 허용하는 쓰기용 역할의 예입니다.

한 Space에서 읽기만 하는 열쇠: Delivery Access Token

Delivery Access Token은 특정 한 Space 안에서만 통하는 읽기 전용 열쇠입니다. 이 열쇠로는 그 Space 안에서 Published(발행) 상태인 콘텐츠를 읽어 올 수만 있습니다. 발행하지 않은 Draft 상태의 콘텐츠는 이 열쇠로 읽히지 않고, 수정하거나 삭제하는 것도 할 수 없습니다.

손님이 보는 쇼핑몰 사이트가 상품을 불러다 보여 줄 때 쓰는 열쇠가 바로 이것입니다. 사이트는 상품을 보여 주기만 하면 되지 등록하거나 지울 필요가 없으니, 읽기만 할 수 있는 좁은 열쇠로 충분합니다. 이 열쇠가 새어 나가더라도 발행된 콘텐츠가 읽힐 뿐, 콘텐츠를 망가뜨릴 수는 없습니다.

콘텐츠를 발행(Published)한다는 것이 무엇이고 발행해야 외부에 공개(전달)되는 이유는 상태와 발행에서 다룹니다.

좁은 역할을 묶어 읽을 범위를 제한하세요

Delivery Access Token을 발급할 때는 이 열쇠가 어디까지 읽을 수 있는지를 SpaceRole(역할)로 정해서 함께 묶습니다. 역할은 "무엇을, 어떤 동작까지 할 수 있는지"를 정해 둔 권한 묶음입니다. 열쇠에 역할을 묶으면, 그 열쇠는 묶인 역할이 허용하는 만큼만 읽을 수 있습니다.

쇼핑몰 사이트라면 "상품"만 읽으면 되므로, 상품(Content)에 대해 Read만 허용하는 좁은 역할을 만들어 묶습니다. 그러면 이 열쇠가 새어 나가더라도 상품 정보만 읽힐 뿐, 다른 콘텐츠나 멤버 정보까지 새지 않습니다.

모든 것을 다룰 수 있는 Administrator 역할은 묶지 마세요. Administrator는 그 Space 안의 모든 것을 다룰 수 있는 최고 권한 역할입니다. 읽기만 하면 되는 공개 사이트용 열쇠에 이렇게 넓은 권한을 묶으면, 열쇠가 새어 나갔을 때 위험이 커집니다. 필요한 것만 읽도록 좁힌 역할을 따로 만들어 묶는 것이 안전합니다.

역할을 만들고 권한을 좁히는 방법은 역할과 권한에서 다룹니다. 공개 사이트용 열쇠에 묶을, 상품 Read만 허용하는 역할을 그 페이지를 보고 미리 만들어 두세요.

허용 Referrer로 열쇠를 쓸 수 있는 사이트를 정하세요

묶은 역할이 이 열쇠로 무엇을 읽을 수 있는지를 정한다면, 허용 Referrer는 이 열쇠를 어디에서 쓸 수 있는지를 정합니다. 발급 화면 아래쪽에 있고, 발급한 뒤에도 바꿀 수 있습니다.

처음 값은 제한 없음입니다. 이 상태에서는 어느 사이트에서 불러도 콘텐츠가 전달됩니다. 지정한 referrer만 허용을 고르면 주소를 적는 칸이 나타나고, 그때부터는 여기에 적어 둔 주소에서 온 요청만 통과합니다. 옷가게 쇼핑몰의 주소가 https://shop.example.com이라면 그 주소를 적어 둡니다. 그러면 이 열쇠의 값이 남의 손에 들어가도 옷가게 사이트 밖에서는 통하지 않습니다.

주소는 여러 개 적을 수 있습니다. 추가 버튼을 누르면 칸이 하나 더 생기고, 칸 오른쪽의 삭제 아이콘을 누르면 그 줄이 없어집니다.

shop.example.com 아래에 붙는 주소를 한꺼번에 허용하려면 맨 앞에 *.을 붙여 https://*.shop.example.com처럼 적습니다. 이렇게 적으면 event.shop.example.com처럼 앞에 무엇이 붙은 주소가 모두 포함됩니다. 다만 이렇게 적어도 https://shop.example.com 자신은 포함되지 않습니다. 둘 다 허용해야 한다면 https://shop.example.com도 한 줄 따로 넣으세요.

이 목록은 손님이 브라우저에서 사이트를 열어 콘텐츠를 불러오는 경우에 맞춰 동작합니다. 사이트가 아니라 서버에서 돌아가는 프로그램이 이 열쇠를 쓴다면 어느 사이트에서 온 요청인지 알 수 없으므로, 그런 열쇠에는 제한 없음을 그대로 두세요.

발급한 비밀값 다루기

세 열쇠 모두, 발급을 마치면 그 열쇠의 상세 화면으로 넘어갑니다. 기본 정보의 Token 칸에 비밀 토큰 값이 들어 있고, 칸 왼쪽의 복사 버튼을 누르면 값 전체가 복사됩니다. 칸보다 값이 길어서 화면에는 뒷부분이 잘려 보이지만, 복사되는 것은 값 전체입니다. 이 값이 곧 열쇠 그 자체이고, 서버나 사이트에 넣을 때 이 값을 씁니다. 발급 직후에 복사해 두지 않았더라도, 나중에 이 상세 화면에 다시 들어와서 복사할 수 있습니다. 오른쪽 패널의 Token 항목에 있는 ID는 이 열쇠를 가리키는 식별자이고 비밀값이 아닙니다.

다만 열쇠마다 두는 곳이 다릅니다.

• Personal Access Token은 비밀번호처럼 다루세요. 강력한 열쇠이므로 서버 안에만 두고, 손님이 보는 공개 클라이언트나 남이 볼 수 있는 코드에는 넣지 마세요.
• Space Access Token은 어디에 둘지를 묶은 역할로 맞춥니다. 서버에 두는 열쇠에는 필요한 만큼의 쓰기 역할을, 손님에게 전달되는 클라이언트에 두는 열쇠에는 새어 나가도 감당할 수 있을 만큼 좁은 역할(예: 한 종류의 글만 새로 만들기)을 묶으세요. Administrator나 넓은 쓰기 역할은 공개된 곳에 두는 열쇠에 묶지 마세요.
• Delivery Access Token은 반대로, 손님이 보는 공개 사이트에 넣는 것이 본래 용도입니다. 사이트를 여는 사람은 누구나 이 값을 볼 수 있는 셈이지만, 좁은 역할을 묶어 두었으므로 누가 이 값을 가져가더라도 그 역할이 허용한 읽기 범위 밖으로는 아무것도 할 수 없습니다. 그래서 사이트에 넣어 두는 것 자체는 문제가 되지 않습니다. 여기에 허용 Referrer로 쇼핑몰 사이트의 주소까지 적어 두면, 값이 남의 손에 들어가도 그 사이트 밖에서는 쓰이지 못합니다. 다만 쓰려는 사이트 밖으로 함부로 퍼뜨리지는 마세요.

열쇠를 잃어버렸거나 의도와 다르게 쓰인 것 같으면, 그 열쇠를 지우고 새로 발급해서 바꿔 끼우면 됩니다.

Personal Access Token 발급하기

매일 밤 신상품을 자동으로 올려 주는 프로그램에 쥐여 줄 Personal Access Token을 발급해 봅니다.

1. 계정 설정에서 Personal Access Token 화면을 여세요.
2. 오른쪽 위의 생성 버튼을 누르세요.
3. 이름 칸에 야간 신상품 업로드를 입력하세요. 이 이름은 나중에 어떤 용도로 만든 열쇠인지 알아보기 위한 것입니다.
4. 저장 버튼을 눌러 발급하세요.

발급이 끝나면 그 열쇠의 상세 화면으로 넘어갑니다. 비밀 토큰 값은 발급한 비밀값 다루기에서 설명한 대로 이 화면에서 복사해, 이 프로그램이 돌아가는 서버의 안전한 곳에 보관하세요.

Space Access Token 발급하기

이번에는 옷가게 Space에 상품을 자동으로 등록해 줄 서버가 쓸 Space Access Token을 발급해 봅니다. 이 열쇠는 옷가게 Space에서 쓰이고, 상품을 등록·수정할 수 있는 역할을 함께 묶습니다.

먼저 이 열쇠에 묶을 역할이 Space에 있어야 합니다. 상품(Content)을 Read·Create·Edit할 수 있는 역할을 역할과 권한에서 미리 만들어 두세요. 아래에서는 그 역할을 상품 등록 담당이라는 이름으로 만들어 두었다고 하겠습니다.

발급·관리 화면은 Delivery Access Token과 같은 Space 설정 안에 있습니다.

1. 옷가게 Space의 설정에서 Space Access Token 화면을 여세요.
2. 목록 오른쪽 위의 생성 버튼을 누르세요. Space Access Token 생성 화면이 열립니다.
3. 이름 칸에 신상품 자동 등록 서버를 입력하세요.
4. SpaceRole에서 상품 등록 담당을 고르세요. Administrator는 고르지 마세요.
5. 허용 Referrer는 제한 없음을 그대로 두세요. 이 열쇠는 사이트가 아니라 서버에서 쓰기 때문입니다.
6. 화면 오른쪽 위의 생성 버튼을 눌러 발급하세요.

발급이 끝나면 그 열쇠의 상세 화면으로 넘어갑니다. 비밀 토큰 값은 발급한 비밀값 다루기에서 설명한 대로 이 화면에서 복사해 안전한 곳에 보관하세요. 여기서는 상품을 등록·수정할 수 있는 역할을 묶었으니, 이 열쇠는 그 역할이 필요한 서버에서 씁니다. 손님이 쓰는 클라이언트에 직접 두어야 한다면, 새어 나가도 감당할 수 있을 만큼 더 좁은 역할을 묶은 열쇠를 따로 발급해 쓰세요. 그렇게 손님에게 전달되는 열쇠에는 허용 Referrer에 그 사이트의 주소까지 적어 두세요.

Delivery Access Token 발급하기

이번에는 쇼핑몰 사이트가 상품을 불러다 보여 줄 때 쓸 Delivery Access Token을 발급해 봅니다. 이 열쇠는 옷가게 Space에서 쓰이고, 상품을 읽을 수 있는 좁은 역할을 함께 묶습니다.

먼저 이 열쇠에 묶을 역할이 Space에 있어야 합니다. 상품(Content)에 대해 Read만 허용하는 역할을 역할과 권한에서 미리 만들어 두세요. 아래에서는 그 역할을 상품 읽기 전용이라는 이름으로 만들어 두었다고 하겠습니다.

1. 옷가게 Space의 설정에서 Delivery Access Token 화면을 여세요.

2. 목록 오른쪽 위의 생성 버튼을 누르세요. Delivery Access Token 생성 화면이 열립니다.

3. 이름 칸에 쇼핑몰 사이트 전달용을 입력하세요.

4. 설명 칸에는 이 열쇠를 어디에 쓰는지 적어 둘 수 있습니다. (선택 사항입니다.)

5. SpaceRole에서 상품 읽기 전용을 고르세요. Administrator는 고르지 마세요.

   

6. 화면 아래쪽 허용 Referrer에서 지정한 referrer만 허용을 고르세요. 이 열쇠를 쇼핑몰 사이트에서만 쓰도록 묶는 설정입니다.

7. 나타난 칸에 https://shop.example.com을 입력하세요.

8. 추가 버튼을 누르세요.

9. 새로 생긴 칸에 https://*.shop.example.com을 입력하세요.

   

10. 화면 오른쪽 위의 생성 버튼을 눌러 발급하세요.

발급이 끝나면 그 열쇠의 상세 화면으로 넘어갑니다. 비밀 토큰 값은 발급한 비밀값 다루기에서 설명한 대로 이 화면에서 복사해, 쇼핑몰 사이트에 넣어 쓰세요.

더 이상 쓰지 않는 열쇠는 지우세요

쓰지 않게 된 열쇠는 그대로 두지 말고 지우는 것이 안전합니다. 토큰 목록에서 더 이상 쓰지 않는 열쇠를 찾아 지우세요. 열쇠를 지우면 그 열쇠로는 더 이상 접근할 수 없습니다. 열쇠가 새어 나간 것 같을 때도 마찬가지입니다. 의심되는 열쇠를 지우고 새로 발급해서 바꿔 끼우면 됩니다.

다음으로 할 일

• 역할과 권한: Delivery Access Token에 묶을 읽기 전용 역할과, Space Access Token에 묶을 읽고 쓰는 역할을 만듭니다.
• 상태와 발행: Delivery Access Token으로 읽히는 것은 Published 상태의 콘텐츠뿐입니다. 발행이 무엇인지 알아봅니다.
• Space Access Token: 프로그램에서 Space Access Token을 발급하거나, 이 열쇠로 콘텐츠를 읽고 쓸 때 필요한 요청 형식 같은 기술 명세를 다룹니다.
• Delivery Access Token: 허용 Referrer에 주소를 적는 정확한 표기 규칙과, 프로그램에서 이 열쇠를 다룰 때 필요한 요청 형식 같은 기술 명세를 다룹니다.
• API 레퍼런스: 다른 토큰을 발급하거나 콘텐츠를 프로그램에서 직접 다룰 때 필요한 요청 형식 같은 기술 명세를 다룹니다.