사용자 동의 받기
이 문서를 따라 하면 DJ 를 Spoon 동의 화면으로 보내고, DJ 가 허용한 뒤 돌아오는 값을
받을 수 있어요. 돌아온 값에 담긴 code 로 다음 단계에서 토큰을 받아요.
준비물
- 등록을 마친 앱의 Client ID — 앱 등록 에서 받아요.
- 앱에 등록한 로그인 리디렉션 URL — 여기로 DJ 가 돌아와요.
전체 흐름
내 봇 서버 ──▶ DJ 브라우저를 authorize 주소로 보내요
│
▼
Spoon 이 로그인과 동의 화면을 맡아요
│
▼
내 리디렉션 URL ◀── DJ 브라우저가 code 또는 error 를 달고 돌아와요
로그인 화면과 동의 화면은 Spoon 이 그려요. 내 서버가 할 일은 보내는 것과 돌아온 값을 받는 것. 두 가지예요.
1. DJ 를 동의 화면으로 보내요
DJ 브라우저를 아래 주소로 이동시켜요. 서버끼리 부르는 API 가 아니라 브라우저가 직접 여는 주소예요.
https://developers.spooncast.net/kr/oauth/authorize
?response_type=code
&client_id={Client ID}
&redirect_uri={로그인 리디렉션 URL}
&scope=events.chat%20chat.send
&state={내가 만든 임의 값}
주소에 지역을 넣어요. 한국 앱은 /kr, 일본 앱은 /jp 예요.
| 지역 | authorize 주소 |
|---|---|
| 한국 | https://developers.spooncast.net/kr/oauth/authorize |
| 일본 | https://developers.spooncast.net/jp/oauth/authorize |
내 앱이 등록된 지역을 써요. 다른 지역 주소로 보내면 DJ 가 그 지역 계정으로 로그인해야 해서 동의 화면까지 가지 못해요.
| 파라미터 | 필수 | 규칙 |
|---|---|---|
response_type | 필수 | code 만 받아요. |
client_id | 필수 | 앱 상세 화면의 Client ID 예요. |
redirect_uri | 필수 | 앱에 등록한 주소와 글자 하나까지 같아야 해요. 다르면 동의 화면에 오류가 뜨고, 내 주소로 돌아오지 않아요. |
scope | 필수 | 요청할 권한을 공백으로 이어서 적어요. 주소에 실을 때는 %20 으로 인코딩해요. 앱에 등록하지 않은 권한을 넣으면 거절돼요. |
state | 권장 | 요청마다 새로 만든 임의 값이에요. 돌아올 때 그대로 실려 오니 대조해서 위조 요청을 걸러내요. 512바이트까지 받아요. |
DJ 가 로그인하지 않은 상태여도 그대로 보내요. Spoon 이 로그인을 받은 뒤 동의 화면으로 이어 줘요.
이미 같은 권한에 동의한 DJ 는 화면을 보지 않고 곧바로 돌아와요. 동의는 쌓이기 때문에 새로 요청한 권한만 화면에 나와요.
2. 돌아온 값을 받아요
DJ 브라우저가 redirect_uri 로 돌아와요. 성공과 실패를 쿼리로 가려내요.
DJ 가 허용하면 code 가 실려요.
https://my-bot.example.com/callback?code=9d41f7a0c86b23e5...&state=내가-보낸-값
| 값 | 쓰임 |
|---|---|
code | 토큰으로 바꾸는 1회용 값이에요. 60초 안에 써야 해요. |
state | 내가 보낸 값 그대로예요. 다르면 그 요청을 버려요. |
DJ 가 거절하거나 요청이 잘못되면 code 대신 error 가 실려요.
https://my-bot.example.com/callback?error=access_denied&state=내가-보낸-값
error | 무슨 일인가요 | 어떻게 하나요 |
|---|---|---|
access_denied | DJ 가 허용하지 않았어요. | 연동을 멈추고 DJ 에게 안내해요. 다시 시도해도 돼요. |
invalid_scope | 앱이 갖지 않은 권한을 요청했어요. | scope 를 앱에 등록한 권한으로 줄여요. 다시 보내도 같은 결과예요. |
error 가 오지 않는 실패도 있어요. client_id 나 redirect_uri 를 믿을 수 없을 때는
내 주소로 돌려보내지 않고 Spoon 동의 화면에 오류를 띄워요. 등록하지 않은 주소로 사용자를
보내지 않기 위한 규칙이에요. 이때는 DJ 가 내 서비스로 돌아오지 않으니, 값을 보내기 전에
Client ID 와 리디렉션 URL 을 먼저 확인해요.
확인하는 방법
브라우저에서 authorize 주소를 직접 열어 봐요. 아래 순서대로 되면 연동이 맞아요.
- Spoon 로그인 화면이 뜨거나, 로그인한 상태면 동의 화면이 바로 떠요.
- 요청한 권한 중 아직 동의하지 않은 것만 목록에 나와요.
- 허용을 누르면 내
redirect_uri로code와state가 실려 돌아와요.
동의 화면 대신 오류 문구가 보이면 client_id 와 redirect_uri 를 다시 확인해요.
다음 단계
받은 code 를 토큰으로 바꿔요. code 는 60초 안에
써야 하고, 한 번 쓴 값은 다시 쓸 수 없어요.