OAuth 방식의 액세스 토큰 획득 방식

애플리케이션을 이용하는 사용자(이하 단순히 '사용자'라 칭함)의 액세스 토큰을 발급받으려면 아래 절차에 따라 발급을 요청합니다.

도움말

아래 설명할 방법은 OAuth 2.0이라는 방법입니다.일반 OAuth는 앱을 만들어야 하지만, IndieAuth의 확장으로 앱을 만들지 않고도 사용할 수 있도록 되어 있습니다.앱 소개를 위한 웹페이지를 만듭니다.페이지가 HTTPS 주소로 접속할 수 있어야 합니다.페이지 어딘가에 아래와 같은 HTML 코드를 작성합니다.

OAuth 방식은 사용할 수 있는 라이브러리가 많기 때문에 가능하면 라이브러리를 사용하는 것을 추천합니다.

현재 이 방식을 사용하려면 웹페이지가 필요합니다.현재 이 방식을 사용하려면 웹페이지가 필요합니다.웹페이지를 준비할 수 없거나 Misskey 2023.9.0 이전 버전을 지원하고자 하는 경우, 아래의 방법을 사용하시기 바랍니다.

Step 2

PKCE code_verifier와 code_challenge 문자열, 그리고 state 문자열을 생성합니다.

code_verifier의 경우 최소 43자, 최대 128자로 알파벳 대/소문자 및 -.
code_challenge문자열은code_verifier\` 문자열을 SHA256 알고리즘으로 해시하여 base64url로 인코딩한 결과를 사용합니다.
state 문자열에는 특별한 제한이 없습니다.임의의 문자열을 사용합니다.

경고

이 문자열은 매번 생성해야 하며, 반복해서 사용하지 마십시오.

도움말

pkce-challenge와 같은 라이브러리를 사용하거나 OAuth 라이브러리의 PKCE 기능을 사용하는 것을 추천합니다.

例

import crypto from "node:crypto";

const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-._~";
const codeVerifier = new Array(128)
  .fill(0)
  .map(() => chars[Math.floor(chars.length * Math.random())])
  .join("");
console.log('code_verifier', codeVerifier);

const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier, "ascii")
  .digest("base64url");
console.log('code_challenge', codeChallenge);

const state = crypto.randomUUID();
console.log('state', state);

Step 3

상대 서버의 OAuth 정보를 가져옵니다.데이터는 JSON 형식으로 되어 있습니다.

https://{host}/.well-known/oauth-authorization-server

{host}부분은 사용자 서버의 호스트로 대체합니다.보통 호스트는 사용자가 입력합니다._~\` 안에 있는 문자로 제한됩니다.

여기서는 authorization_endpoint와 token_endpoint를 사용합니다.

도움말

다음 단계에서 사용되는 scope에 대한 정보도 scopes_supported에서 확인할 수 있습니다.

Step 4

애플리케이션 인증 양식을 사용자의 브라우저에 표시합니다.애플리케이션 인증 양식을 사용자의 브라우저에 표시합니다.인증 양식은 다음 형식의 URL로 열 수 있습니다.

{authorization_endpoint}?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope={scope}&code_challenge={code_challenge}&code_challenge_method=S256&state={state}

여기서,

{authorization_endpoint}부분은 이전 정보 획득에서 얻은 주소로 대체합니다.
{client_id}부분은 앱 소개 페이지의 주소로 대체합니다.
{code_challenge}부분은 앞서 생성한 code_challenge 문자열로 대체합니다.
code_challenge_method부분은 항상 S256으로 합니다.
{redirect_uri}부분은 소개 페이지에서 사용하고 있는 전송처 주소로 대체합니다.
{scope}부분은 애플리케이션이 요청하는 권한으로 대체합니다.요청하는 권한을 ``로 구분하여 열거합니다.권한 목록은 여기에서 확인할 수 있습니다.요청할 권한을 로 구분지어 열거합니다.권한 목록은 여기에서 확인할 수 있어요.
{state}부분은 앞서 생성한 state 문자열로 대체합니다.

例

https://misskey.local/oauth/authorize?client_id=http%3A%2F%2Fexample.com&code_challenge=C6hwMO2bmIzg3nqppTE9b79fvuOjlrKmH2xNiZSMHzw&code_challenge_method=S256&response_type=code&redirect_uri=http%3A%2F%2Fexample.com%2Fredirect&scope=write%3Anotes&state=87c11f05-86eb-4eb2-9057-f6a98fc5e9ab

이름	설명
`code`	사용자 인증 코드.
`state`	인증 요청에 사용된 `state` 문자열.

転送された認証コードを使ってアクセストークンをPOSTでリクエストします。リクエスト先はtoken_endpointになります。전송된 인증 코드를 사용하여 POST로 액세스 토큰을 요청합니다.요청 대상은 token_endpoint가 됩니다.데이터 형식은 application/json과 application/x-wwww-form-urlencoded를 사용할 수 있습니다.각 매개변수는 다음과 같습니다.각 매개변수는 다음과 같습니다.

이름	설명
`grant_type`	항상 `authorization_code`로 설정합니다.
`client_id`	인증 요청에 사용되는 `client_id` 문자열.
`redirect_uri`	인증 요청에 사용된 `redirect_uri` 문자열.
`scope`	인증 요청에 사용된 `scope` 문자열.
`code`	획득한 인증 코드.
`code_verifier`	앞서 생성한 `code_verifier` 문자열.

例

const res = await fetch(endpoint, {
  method: "POST",
  body: JSON.stringify({
    grant_type: "authorization_code",
    client_id: "https://example.com",
    redirect_uri: "https://example.com/redirect",
    scope: "write:notes",
    code: "...",
    code_verifier: "hjjbCYDmDpSLjirkO-PrfWKsRhDdJr-PAEGRClRwzUKlmFIIIrZNmSvUIraeIa~WqbqQnfbJV-Hc_IfuQkesBYUpukUi~lInDfU_AZjoZqbU.ioQTRzaFfZFfGnT-OAA",
  }),
  headers: {
    "Content-Type": "application/json"
  }
});

응답은 JSON 객체 형태로, 거기서 access_token을 가져와서 사용합니다.

OAuth 방식의 액세스 토큰 획득 방식

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

이 페이지의 내용