앱 연결하기

직접 만든 앱에서 리크루터가 자신의 Tahoe 계정으로 로그인하고, 볼 수 있는 것을 읽고, 허용하면 대신 무언가를 바꾸게 할 수 있습니다. 이 가이드는 앱을 등록하는 소유자나 관리자, 그리고 로그인을 구현하는 개발자를 위한 것입니다. 로그인 자체는 Sign in with Tahoe의 표준 흐름과 같습니다. 내 워크스페이스가 등록한 앱에서 달라지는 것은 누가 등록할 수 있는지, 어떤 스코프를 요청할 수 있는지, 누가 승인할 수 있는지입니다.

앱 등록하기#

https://tahoe.workonward.com/api/partner/v1/oauth/authorize
  ?client_id=thc_7f3a9c21d84e4b6fa0c5e19b2d7a6e31
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Ftahoe%2Fcallback
  &response_type=code
  &scope=openid%20offline_access%20applications%3Aread%20applications%3Awrite
  &state=<random, tied to the user's session>
  &nonce=<random, saved for the id_token check>
  &code_challenge=<base64url(sha256(code_verifier))>
  &code_challenge_method=S256

클라이언트 시크릿 교체하기#

앱에서 교체를 선택하면 새 시크릿을 받습니다. 이전 시크릿은 다음 교체 때까지 계속 작동하므로 중단 없이 새 시크릿을 배포할 수 있습니다. 새 시크릿을 배포하고 동작을 확인하세요. 이전 시크릿은 다시 교체할 때에야 멈춥니다. 정기적으로 교체하고, 시크릿이 유출되었을 가능성이 있으면 바로 교체하세요.

앱 비활성화하기#

앱을 비활성화하면 모든 사용자의 동의가 끝나고, 앱이 가진 모든 리프레시 토큰이 모든 사용자에 대해 폐기됩니다. 액세스 토큰은 다음 요청부터 작동하지 않습니다. 되돌릴 수 없으므로, 다시 필요하면 새 앱을 등록하세요.

앱이 요청할 수 있는 스코프#

워크스페이스가 등록한 앱은 그 워크스페이스의 API 키와 같은 등급을 따릅니다. 키에 줄 수 있는 스코프를 참고하세요.

쓰기 스코프에는 한 가지 조건이 더 있습니다. 연결된 앱의 쓰기가 켜져 있어야 합니다. 켜지기 전에는 앱을 등록할 때 그 스코프가 거부되고, 동의 화면에서도 부여할 수 없습니다.

누가 무엇을 승인할 수 있는가#

로그인하는 사용자가 동의 화면을 보고 결정합니다. 고객이 등록한 앱은 Tahoe가 검토하지 않았으므로 그 화면에 등록한 워크스페이스의 이름과 함께 미확인으로 표시됩니다. 사용자가 부여할 수 없는 스코프는 체크되지 않은 채 이유와 함께 나옵니다. 같은 규칙을 사용자가 승인할 때 다시 확인하므로, 양식을 고쳐서 더 많은 권한을 줄 수는 없습니다.

승인된 앱이 동작하는 곳#

토큰은 사용자가 승인할 때 로그인해 있던 워크스페이스를 읽습니다. 토큰에 쓰기 스코프나 민감한 스코프가 있으면, 사용자가 지금도 소유자나 관리자인 워크스페이스에서만 동작합니다. 사용자를 강등하면 앱은 일반 데이터의 읽기 접근은 유지하고, 나머지는 사용자의 다음 요청부터 잃습니다. 사용자를 워크스페이스에서 제외하면 다음 갱신을 포함해 모든 것이 끝납니다. 사용자는 언제든 설정의 연결된 앱에서 앱 연결을 끊을 수도 있습니다.

사용자로서 쓰기#

연결된 앱의 쓰기가 켜져 있으면, 쓰기 스코프가 있는 토큰은 API 키와 같은 쓰기 엔드포인트를 쓸 수 있습니다. 그 전에는 모든 쓰기가 403 write_requires_api_key를 반환합니다.

{
  "detail": {
    "code": "write_requires_api_key",
    "type": "permission",
    "message": "Writing requires an API key. A Sign in with Tahoe token may only read.",
    "param": null
  }
}

• 쓰기는 앱이 아니라 사용자의 것입니다. 메모, 단계 이동, 메시지는 로그인한 사람의 이름으로 Tahoe에 나타나며, API에서 온 변경임을 표시하는 활동 항목에는 앱과 요청이 담깁니다. 사용자가 Tahoe에서 할 수 없는 일은 앱도 할 수 없습니다.
• 나머지는 키와 같습니다. 같은 엔드포인트, 같은 스코프, 같은 오류, 그리고 후보자에 대한 같은 규칙입니다. POST /messages를 통하지 않고는 후보자에게 아무것도 가지 않으며, 아무것도 삭제되지 않습니다. 쓰기를 하는 스코프를 참고하세요.
• Idempotency-Key를 보내세요. 앱도 재시도하고, 더블클릭하는 사용자도 있습니다. 중복 요청 방지를 참고하세요.
• 이벤트에 origin이 있습니다. 앱이 한 변경은 app: 뒤에 클라이언트 ID가 붙은 origin이 들어 있는 이벤트를 만들므로 내 에코를 건너뛸 수 있습니다. 이벤트의 출처를 참고하세요.

curl -X POST https://tahoe.workonward.com/api/partner/v1/applications/app_6Qm2xKd4Rp8v/move \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: move-6Qm2-to-screen-0001" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stg_3Rp8vKd2mXq4" }'

리프레시 토큰과 교체#

• 갱신할 때마다 새 리프레시 토큰이 반환되고 보낸 토큰은 끝납니다. 새 토큰을 쓰기 전에 먼저 저장하세요.
• 리프레시 토큰은 30일 동안 쓰지 않으면 만료되고, 한 번의 로그인에서 이어지는 토큰은 그 로그인으로부터 90일 뒤에 끝납니다.
• 이미 교환한 리프레시 토큰을 보내면 그 로그인에서 나온 모든 토큰이 끝나고 사용자는 다시 로그인합니다. 사용자 한 명씩 갱신하고, 타임아웃 뒤에 이전 토큰으로 재시도하지 마세요.
• 앱 비활성화, 비밀번호 재설정, 사용자가 워크스페이스를 떠나는 것 모두 토큰을 끝냅니다. invalid_grant는 “이 사용자를 다시 로그인시키라”는 뜻으로 받아들이세요.

관련 문서#