เอกสารนี้เป็นการแปลโดยชุมชน การแปลเอกสารสามารถทำได้ที่ Crowdin ขอบคุณสำหรับความร่วมมือนะคะ 🙏
OAuth方式でのアクセストークン取得方式
アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。
以下に説明する方法は、OAuth 2.0と呼ばれるものです。普通のOAuthはアプリを作成しますが、IndieAuthの拡張でアプリ作成なしで使えるようになっています。
OAuth方式は使えるライブラリが多いので、出来ればライブラリを使うのをおすすめします。
現在、この方式を使うためにはウェブページが必要になります。どうしてもウェブページを用意できない場合、もしくはMisskey 2023.9.0以前のバージョンをサポートしたい場合、以下の方式を使ってください。
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
文字列には特別な制限はありません。ランダムな文字列を使います。
この文字列は毎回生成し、使いまわさないようにしてください。
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
Step 5
ユーザーがアプリケーションアクセスを許可したら、redirect_uri
のアドレスに認証コードがURLパラメータの形式で転送されます。
名前 | 説明 |
---|---|
code | ユーザーの認証コード。 |
state | 認証リクエストに使われたstate 文字列。 |
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 文字列。 |
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
を取得して使います。