Bantu kami menerjemahkan

Dokumen ini diterjemahkan oleh komunitas. Kamu dapat ikut berkontribusi menyempurnakan terjemahan ini melalui Crowdin. Kami sangat mengapresiasi atas kerjasama yang telah kamu berikan dengan ikut berkontribusi dalam proyek ini 🙏.

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

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

Tips

以下に説明する方法は、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_verifiercode_challenge文字列, 及びstate文字列を生成します。

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

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

Tips

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

Tips

次のステップで使われる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/jsonapplication/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を取得して使います。