앱 등록하기
Hivesigner로 사람들을 로그인시키는 앱은 하나의 Hive 계정입니다. 그 이름이 여러분이 보내는 client_id입니다. 그 프로필에는 Hivesigner가 읽는 설정이 들어 있습니다. 토큰을 보낼 수 있는 콜백과, 코드 흐름을 위한 클라이언트 시크릿입니다. API로 브로드캐스트하려면 앱 계정이 @hivesigner에 게시 권한도 줍니다. 이 문서는 각 단계를 차례로 짚습니다.
필요한 것
| 하려는 일 | 앱 계정과 콜백 | 클라이언트 시크릿 | @hivesigner 허용 |
|---|---|---|---|
| 로그인시키고 토큰 흐름으로 브로드캐스트 | 예 | 아니요 | 예 |
| 로그인시키고 코드 흐름으로 브로드캐스트(갱신 토큰) | 예 | 예 | 예 |
| 로그인만, 앱 이름이 든 토큰으로 | 예 | 아니요 | 아니요 |
| 로그인만, Hive 계정이 없는 사이트에서 | 아니요 | 아니요 | 아니요 |
| 서명 링크 보내기 | 아니요 | 아니요 | 아니요 |
마지막 두 줄은 게시 접근 없는 로그인과 서명 링크를 보세요.
앱 계정 만들기
- 앱을 위한 Hive 계정을 만듭니다. 예를 들어 https://ecency.com/signup 에서 만들 수 있습니다. 개인 계정이 아니라 앱 전용 계정을 쓰세요. 그 이름이 여러분의
client_id입니다. 사용자는 동의 화면의 «Hive 계정» 옆에서 그것을 봅니다. Hive 계정은 이름을 바꿀 수 없으니 신중히 고르세요. - https://hivesigner.com/import 에서 그 계정을 Hivesigner에 추가합니다(계정 추가). 활성 키나 마스터 비밀번호를 쓰세요. 아래의 허용 단계에는 활성 키가 필요합니다.
앱 설정 채우기
앱 계정을 고른 상태로 https://hivesigner.com/profile 을 열고 다음을 설정합니다.
- 이 계정은 앱입니다. 켜세요. 계정을 앱으로 표시하며, API는 그 계정의 코드나 갱신 토큰을 받기 전에 이것을 확인합니다.
- 리디렉션 URI. 여러분의 콜백을 한 줄에 하나씩 적습니다. 콜백을 보세요.
- 제작자. 앱을 관리하는 사람입니다. https://hivesigner.com/apps 의 앱 목록에 표시됩니다.
- 상태. 운영인지 시험인지를 여러분의 기록을 위해 적습니다. Hivesigner는 둘을 똑같이 다룹니다.
- 클라이언트 시크릿. 코드 흐름에만 필요합니다. 클라이언트 시크릿을 보세요.
이름과 프로필 사진 URL도 채우세요. 동의 화면에 앱의 그림과 이름이 나옵니다. https://hivesigner.com/apps 의 앱 목록에는 이름, 소개, 웹사이트가 나옵니다.
저장하면 계정의 프로필이 온체인에서 바뀌며 그 계정의 게시 키가 필요합니다. Hivesigner는 로그인 요청이 열릴 때 계정에서 콜백을 읽으므로, 바뀐 내용은 거래가 블록에 들어가는 즉시 반영됩니다.
참고: 이름, 그림, 설명은 여러분의 앱 계정이 직접 게시한 것입니다. 그래서 동의 화면에는 실제 계정 이름(
@myapp)과 사용자를 보내는 호스트도 함께 나옵니다. 허용과 리디렉션이 실제로 쓰는 것은 그 둘입니다.
콜백
콜백(로그인 요청의 redirect_uri)은 Hivesigner가 토큰이나 코드와 함께 사용자를 돌려보내는 곳입니다. Hivesigner는 여러분의 앱 계정에 등록된 콜백에만 보냅니다.
규칙
- 정확히 일치. 요청의
redirect_uri는 여러분의 리디렉션 URI 가운데 하나와 한 글자도 빠짐없이 같아야 합니다. 스킴, 호스트, 포트, 경로, 쿼리 모두입니다. - https만. 콜백은
https://를 써야 합니다. 평범한http://는 루프백에서만 받아들입니다.localhost,127.0.0.1,[::1]입니다. - 루프백 포트는 달라도 됩니다. 평범한 http로 등록한 루프백 콜백은, 경로와 쿼리와 프래그먼트와 사용자 정보가 같다면 어떤 루프백 호스트와 포트와도 맞습니다.
https://로 등록한 루프백 콜백은 정확히 일치해야 합니다. - 자체 스킴은 안 됩니다.
myapp://callback같은 콜백은 거절됩니다. 모바일과 데스크톱 앱을 보세요. - 프래그먼트는 안 됩니다. 콜백에
#fragment를 붙이지 마세요.
프로필 페이지는 결코 동작할 수 없는 콜백의 저장을 거절하며 «사용할 수 없는 콜백(https 또는 localhost의 http만 가능)»라고 알립니다.
예시
다음 리디렉션 URI가 등록되어 있을 때:
https://myapp.example/auth/callback
http://localhost:3000/auth
요청의 redirect_uri |
결과 |
|---|---|
https://myapp.example/auth/callback |
받아들임: 정확히 일치 |
https://myapp.example/auth/callback/ |
거절: /가 더 있음 |
https://myapp.example/auth/callback?next=home |
거절: 쿼리가 다름 |
https://www.myapp.example/auth/callback |
거절: 다른 호스트 |
http://myapp.example/auth/callback |
거절: 루프백 밖의 평범한 http |
http://localhost:3000/auth |
받아들임: 정확히 일치 |
http://127.0.0.1:51234/auth |
받아들임: 루프백, 같은 경로, 다른 포트 |
http://[::1]:3000/auth |
받아들임: 루프백, 같은 경로 |
http://127.0.0.1:3000/other |
거절: 다른 경로 |
https://localhost:3000/auth |
거절: https는 평범한 http 등록과 맞지 않음 |
myapp://auth |
거절: 자체 스킴 |
콜백에서 쿼리를 받으려면 그 쿼리까지 그대로 포함해 등록하세요. Hivesigner는 콜백 자체의 쿼리를 그대로 두고 그 뒤에 자신의 매개변수를 붙입니다.
모바일과 데스크톱 앱
Hivesigner는 토큰을 콜백 URL에 넣습니다. myapp:// 같은 자체 스킴은 특정 앱에 묶여 있지 않습니다. 같은 기기의 다른 앱이 그것을 가로채 토큰을 받을 수 있습니다. 그래서 Hivesigner는 자체 스킴을 거절하고, 토큰은 https 주소나 사용자 기기의 루프백으로만 보냅니다.
네이티브 앱은 대신 다음 중 하나를 씁니다.
- 자신이 가진 https 링크. 운영체제가 여러분의 앱에서 여는 콜백을 여러분의 도메인에 등록하세요(Android의 App Links나 iOS의 Universal Links).
- 루프백 콜백. 앱이
127.0.0.1에서 리디렉션을 기다립니다.http://127.0.0.1/auth(또는localhost)를 등록하고 실행할 때 비어 있는 포트를 쓰면 됩니다. 포트는 같지 않아도 됩니다.
클라이언트 시크릿
클라이언트 시크릿은 코드 교환이 여러분의 서버에서 왔음을 증명합니다. 코드 흐름에는 반드시 필요합니다. 서버는 코드나 갱신 토큰을 보낼 때마다 이것을 /api/oauth2/token에 함께 보냅니다. 토큰 흐름에서는 쓰지 않습니다.
- 긴 무작위 값을 만드세요. 예를 들어
openssl rand -hex 32입니다. - 프로필 페이지에서 설정하세요. Hivesigner는 여러분 앱 계정의 프로필에 그 sha256 해시만 저장합니다. 칸을 비워 두면 지금의 시크릿이 그대로 유지됩니다.
- 서버에 보관하세요. 웹 페이지, 모바일 앱, URL에는 절대 넣지 마세요.
- 바꾸려면 새 값을 설정하고 같은 때에 서버도 함께 바꾸세요.
@hivesigner에 게시 권한 주기
API는 @hivesigner 계정의 게시 키로 브로드캐스트합니다. Hive가 여러분의 사용자를 위해 그 서명을 받아들이는 것은, 여러분의 앱 계정이 자신의 게시 권한에 @hivesigner를 추가했을 때뿐입니다. 게시 권한의 연결 고리를 보세요.
- Hivesigner에서 여러분의 앱 계정을 고릅니다.
- https://hivesigner.com/authorize/hivesigner 를 엽니다.
- 화면에 «@hivesigner 앱 승인»와 «@hivesigner 앱이 @myapp 계정으로 글 작성, 댓글, 투표, 팔로우를 할 수 있게 됩니다.»가 나옵니다. 승인를 고르세요. 여기에는 앱 계정의 활성 키가 필요합니다.
이것은 한 번만 하면 됩니다. 이것이 없으면 모든 브로드캐스트가 unauthorized_client와 «Broadcaster account doesn't have permission to broadcast for @myapp»로 실패합니다. 로그인만 하는 앱에는 필요 없습니다.
이 허용은 @hivesigner가 여러분의 앱 계정 자체로도 글을 쓸 수 있게 합니다. 앱 계정을 앱 전용으로만 두어야 할 이유가 하나 더 있는 셈입니다.
이 허용을 갖추고 Hivesigner로 브로드캐스트하는 앱은 https://hivesigner.com/apps 의 앱 목록에, 쓰는 사람 수 순서로 나올 수 있습니다.
무언가 잘못되었을 때 사용자에게 보이는 것
Hivesigner는 안전하게 답할 수 없는 요청을 거절합니다. 메시지와 이 문제 신고하기 버튼을 보여 줍니다. 그 요청은 승인할 수 없습니다. 여러분의 콜백으로는 아무것도 보내지 않습니다.
| 문제 | 사용자에게 보이는 문구 |
|---|---|
redirect_uri가 여러분의 리디렉션 URI가 아님 |
«이 앱의 리디렉션 URL이 등록되어 있지 않습니다. 안전을 위해 로그인이 차단되었습니다.» |
client_id가 Hive 계정이 아님 |
«@myapp 이름의 Hive 계정이 없으므로 승인할 앱이 없습니다. 사이트로 돌아가 다시 시도하세요.» |
| 계정이 앱으로 표시되어 있지 않음 | «@myapp은(는) 앱으로 설정되어 있지 않아 로그인할 수 없습니다. 사이트로 돌아가 다시 시도하세요.» 위에서 설명한 대로 이 계정은 앱입니다을 켜세요. |
요청에 redirect_uri가 없음 |
«이 승인 요청은 불완전합니다. 앱 이름이나 리디렉션 URL이 없습니다. 앱으로 돌아가 다시 시도하세요.» |
사용자가 이런 경우를 알려 오면, 여러분의 앱이 보내는 redirect_uri를 등록된 리디렉션 URI와 한 글자씩 맞춰 보세요.
점검 목록
- 앱을 위한 Hive 계정을, 그 활성 키로 Hivesigner에 추가해 두었는지.
- https://hivesigner.com/profile 에서 «이 계정은 앱입니다»이 켜져 있고, 리디렉션 URI가 등록되어 있으며, 코드 흐름을 쓴다면 클라이언트 시크릿이 설정되어 있는지.
- API로 브로드캐스트한다면 https://hivesigner.com/authorize/hivesigner 에서 @hivesigner를 승인했는지.
- 등록된 리디렉션 URI 가운데 하나를 그대로 보내는 로그인 링크가 있는지. OAuth2로 로그인을 보세요.