jointrashposs/content/id/docs/4.for-developers/api/token/3.oauth.md

description
v2023.9.0以降で使用できる、OAuth2.0方式での認証方法について説明しています。

OAuth方式でのアクセストークン取得方式

アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。

:::tip

以下に説明する方法は、OAuth 2.0と呼ばれるものです。普通のOAuthはアプリを作成しますが、IndieAuthの拡張でアプリ作成なしで使えるようになっています。

OAuth方式は使えるライブラリが多いので、出来ればライブラリを使うのをおすすめします。

現在、この方式を使うためにはウェブページが必要になります。どうしてもウェブページを用意できない場合、もしくはMisskey 2023.9.0以前のバージョンをサポートしたい場合、以下の方式を使ってください。

• Misskey専用のMiAuth方式でのアクセストークン取得方法
• アプリ作成方式でのアクセストークン取得方法（旧来型）。

:::

Step 1

アプリ紹介のためのウェブページを作ります。ページがHTTPSアドレスでアクセスできるようにしてください。ページのとこかに以下のようなHTMLコードを書きます。

<!-- （必須項目）hrefのアドレスが認証コードの転送先になります。 -->
<link rel='redirect_uri' href='/redirect'>

<!-- ユーザーに見せるアプリの名前になります。なかったらこのページのアドレスが名前になります。 -->
<div class='h-app'>
	<a href="/" class="u-url p-name">My Misskey App</a>
</div>

あとでredirect_uriのアドレスに認証コードが転送されます。

Step 2

PKCE code_verifierとcode_challenge文字列, 及びstate文字列を生成します。

• code_verifierの場合は最低43字、最高128字でアルファベット大・小文字及び-._~の中の文字に限られます。
• code_challenge文字列はcode_verifier文字列をSHA256アルゴリズムでハッシュしてbase64urlでエンコードした結果を使います。
• state文字列には特別な制限はありません。ランダムな文字列を使います。

:::danger

この文字列は毎回生成し、使いまわさないようにしてください。

:::

:::tip

pkce-challengeとかのライブラリを使ったり、OAuthライブラリのPKCE機能を使うのがおすすめです。

:::

:::tip{label='例'}

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を使います。

:::tip

次のステップで使われる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文字列に置き換えます。

:::tip{label='例'}

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

:::

Step 5

ユーザーがアプリケーションアクセスを許可したら、redirect_uriのアドレスに認証コードがURLパラメータの形式で転送されます。

名前	説明
code	ユーザーの認証コード。
state	認証リクエストに使われたstate文字列。

:::tip{label='例'}

https://example.com/redirect?code=...&state=87c11f05-86eb-4eb2-9057-f6a98fc5e9ab

:::

state文字列がちゃんと一致しているのか確認して、次のステップに進みます。

Step 6

転送された認証コードを使ってアクセストークンをPOSTでリクエストします。リクエスト先はtoken_endpointになります。データ形式はapplication/jsonとapplication/x-www-form-urlencodedを使えます。各パラメータは以下のようになります。

名前	説明
grant_type	常にauthorization_codeにします。
client_id	認証リクエストに使われたclient_id文字列。
redirect_uri	認証リクエストに使われたredirect_uri文字列。
scope	認証リクエストに使われたscope文字列。
code	取得した認証コード。
code_verifier	前に生成したcode_verifier文字列。

:::tip{label='例'}

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を取得して使います。