mirror of
https://iceshrimp.dev/Crimekillz/jointrashposs.git
synced 2024-11-25 02:09:05 +01:00
OAuthの説明を追加 (#96)
* OAuthの説明を追加 * fix * fix docs * split tip for step 2 * follow convention * code_challenge -> state * permission.mdの相対パスを修正 * 様々な修正 --------- Co-authored-by: kakkokari-gtyih <daisho7308+f@gmail.com>
This commit is contained in:
Kagami Sascha Rosylight
GitHub
parent
73f07aa6d3
commit
eebb382322
85
content/ja/docs/4.for-developers/api/token/1.index.md
Normal file
85
content/ja/docs/4.for-developers/api/token/1.index.md
Normal file
@ -0,0 +1,85 @@
|
|||||||
|
# アクセストークンの取得
|
||||||
|
|
||||||
|
APIを使い始めるには、APIを利用するアカウントに紐づいた**アクセストークン**を取得する必要があります。
|
||||||
|
このドキュメントでは、アクセストークンを取得する手順を説明した後、基本的なAPIの使い方を説明します。
|
||||||
|
|
||||||
|
基本的に、APIはリクエストにはアクセストークンが必要となります。
|
||||||
|
アクセストークンは、ユーザーに紐づいた認証情報で、APIを利用するユーザーを識別するとともに、アクセストークンごとにどういった操作の権限を持っているかが管理されます。
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
ユーザーとそのユーザーに紐づいたアクセストークンは一対多の関係であり、あるユーザーに対して複数のアクセストークンが発行され得ます。
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
あなた自分自身のアクセストークンは簡単に取得できるほか、あなたのアプリケーションを使用することになる不特定のユーザーのアクセストークンを取得することもできます。
|
||||||
|
|
||||||
|
- 前者の場合: **「自分自身のアクセストークンを手動発行する」** に進む
|
||||||
|
- 後者の場合: **「アプリケーション利用者にアクセストークンの発行をリクエストする」** に進む
|
||||||
|
|
||||||
|
## 自分自身のアクセストークンを手動発行する
|
||||||
|
Misskey Webの「設定 > API」で、自分のアクセストークンを発行できます。
|
||||||
|
|
||||||
|
:::danger
|
||||||
|
|
||||||
|
アクセストークンは他人に知られないようにしてください。
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
## アプリケーション利用者にアクセストークンの発行をリクエストする
|
||||||
|
アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の方法の一つを使います。
|
||||||
|
|
||||||
|
:MkIndex
|
||||||
|
|
||||||
|
## APIの利用
|
||||||
|
|
||||||
|
アクセストークンが取得できたら、各種エンドポイントにリクエストすることでAPIの利用が行えます。
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
- HTTP APIはすべてPOSTで、リクエスト/レスポンスともにJSON形式です（drive/files/createを除く）。
|
||||||
|
- 要求ヘッダーに`Content-Type: application/json`を指定します。
|
||||||
|
- アクセストークンは、`i`というパラメータ名でリクエストボディJSONに含めます。
|
||||||
|
- ベースURLは`https://{サーバーのドメイン}/api`です。
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
### Authorization headerを使う方式
|
||||||
|
|
||||||
|
以下のようにヘッダーの`Authorization`フィールドを指定します。
|
||||||
|
|
||||||
|
```js
|
||||||
|
fetch("https://misskey.io/api/notes/create", {
|
||||||
|
method: 'POST',
|
||||||
|
body: JSON.stringify({
|
||||||
|
text: "Hello Misskey API World with My Application!"
|
||||||
|
}),
|
||||||
|
headers: {
|
||||||
|
Authorization: `Bearer ${accessToken}`,
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
},
|
||||||
|
credentials: 'omit',
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### iを使う方式
|
||||||
|
|
||||||
|
アクセストークン付きのボディの例（metaの場合）:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"i": "HogEFugA1341",
|
||||||
|
"detail": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--TODO:「APIリファレンス」をリンクに差し替え-->
|
||||||
|
APIの詳細は、APIリファレンスを参照してください。
|
||||||
|
|
||||||
|
:::warning
|
||||||
|
|
||||||
|
MisskeyはRESTを採用していません。
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
また、MisskeyはHTTP APIだけでなく、ストリーミングAPIも提供しています。ストリーミングAPIの詳細は[こちらのドキュメント](../streaming/)を参照してください。
|
||||||
@ -1,42 +1,20 @@
|
|||||||
# アクセストークンの取得
|
---
|
||||||
|
description: v12.27.0以降で使用できる、Misskey独自の簡素な認証方法について説明しています。
|
||||||
|
---
|
||||||
|
|
||||||
APIを使い始めるには、APIを利用するアカウントに紐づいた**アクセストークン**を取得する必要があります。
|
# MiAuth方式でのアクセストークン取得方式
|
||||||
このドキュメントでは、アクセストークンを取得する手順を説明した後、基本的なAPIの使い方を説明します。
|
|
||||||
|
|
||||||
基本的に、APIはリクエストにはアクセストークンが必要となります。
|
|
||||||
アクセストークンは、ユーザーに紐づいた認証情報で、APIを利用するユーザーを識別するとともに、アクセストークンごとにどういった操作の権限を持っているかが管理されます。
|
|
||||||
|
|
||||||
:::tip
|
|
||||||
|
|
||||||
ユーザーとそのユーザーに紐づいたアクセストークンは一対多の関係であり、あるユーザーに対して複数のアクセストークンが発行され得ます。
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
あなた自分自身のアクセストークンは簡単に取得できるほか、あなたのアプリケーションを使用することになる不特定のユーザーのアクセストークンを取得することもできます。
|
|
||||||
|
|
||||||
- 前者の場合: **「自分自身のアクセストークンを手動発行する」** に進む
|
|
||||||
- 後者の場合: **「アプリケーション利用者にアクセストークンの発行をリクエストする」** に進む
|
|
||||||
|
|
||||||
### 自分自身のアクセストークンを手動発行する
|
|
||||||
Misskey Webの「設定 > API」で、自分のアクセストークンを発行できます。
|
|
||||||
|
|
||||||
:::danger
|
|
||||||
|
|
||||||
アクセストークンは他人に知られないようにしてください。
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
### アプリケーション利用者にアクセストークンの発行をリクエストする
|
|
||||||
アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。
|
アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。
|
||||||
|
|
||||||
:::tip
|
:::tip
|
||||||
|
|
||||||
以下に説明する方法は、アプリを作成せずインスタントにアクセストークンを発行する、MiAuthと呼ばれるものです。
|
以下に説明する方法は、アプリを作成せずインスタントにアクセストークンを発行する、MiAuthと呼ばれるものです。
|
||||||
|
|
||||||
[アプリ作成方式でのアクセストークン取得方法もあります（旧来型）。](./app)
|
- [よりおおく使われているOAuth方式でのアクセストークン取得方法もあります。](./oauth.md)
|
||||||
|
- [アプリ作成方式でのアクセストークン取得方法もあります（旧来型）。](./app.md)
|
||||||
:::
|
:::
|
||||||
|
|
||||||
#### Step 1
|
## Step 1
|
||||||
UUIDを生成する。以後これを**セッションID**と呼びます。
|
UUIDを生成する。以後これを**セッションID**と呼びます。
|
||||||
|
|
||||||
:::danger
|
:::danger
|
||||||
@ -45,7 +23,7 @@ UUIDを生成する。以後これを**セッションID**と呼びます。
|
|||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
#### Step 2
|
## Step 2
|
||||||
アプリケーション認証フォームをユーザーのブラウザで表示させる。認証フォームは、以下の形式のURLで開くことができます:
|
アプリケーション認証フォームをユーザーのブラウザで表示させる。認証フォームは、以下の形式のURLで開くことができます:
|
||||||
|
|
||||||
```
|
```
|
||||||
@ -73,7 +51,7 @@ https://misskey.io/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f?name=MyApp&callba
|
|||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
#### Step 3
|
## Step 3
|
||||||
ユーザーがアプリケーションアクセスを許可した後、次の形式のURLにPOSTリクエストすると、レスポンスとしてアクセストークンを含むJSONが返ります。
|
ユーザーがアプリケーションアクセスを許可した後、次の形式のURLにPOSTリクエストすると、レスポンスとしてアクセストークンを含むJSONが返ります。
|
||||||
|
|
||||||
```
|
```
|
||||||
@ -90,35 +68,3 @@ https://{host}/api/miauth/{session}/check
|
|||||||
| ------- | ---------------------------- |
|
| ------- | ---------------------------- |
|
||||||
| `token` | ユーザーのアクセストークン。 |
|
| `token` | ユーザーのアクセストークン。 |
|
||||||
| `user` | ユーザーの情報。 |
|
| `user` | ユーザーの情報。 |
|
||||||
|
|
||||||
## APIの利用
|
|
||||||
アクセストークンが取得できたら、各種エンドポイントにリクエストすることでAPIの利用が行えます。
|
|
||||||
|
|
||||||
:::tip
|
|
||||||
|
|
||||||
- HTTP APIはすべてPOSTで、リクエスト/レスポンスともにJSON形式です（drive/files/createを除く）。
|
|
||||||
- 要求ヘッダーに`Content-Type: application/json`を指定します。
|
|
||||||
- アクセストークンは、`i`というパラメータ名でリクエストボディJSONに含めます。
|
|
||||||
- ベースURLは`https://{サーバーのドメイン}/api`です。
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
アクセストークン付きのボディの例（metaの場合）:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"i": "HogEFugA1341",
|
|
||||||
"detail": false
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
<!--TODO:「APIリファレンス」をリンクに差し替え-->
|
|
||||||
APIの詳細は、APIリファレンスを参照してください。
|
|
||||||
|
|
||||||
:::warning
|
|
||||||
|
|
||||||
MisskeyはRESTを採用していません。
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
また、MisskeyはHTTP APIだけでなく、ストリーミングAPIも提供しています。ストリーミングAPIの詳細は[こちらのドキュメント](./streaming/index.md)を参照してください。
|
|
||||||
177
content/ja/docs/4.for-developers/api/token/3.oauth.md
Normal file
177
content/ja/docs/4.for-developers/api/token/3.oauth.md
Normal file
@ -0,0 +1,177 @@
|
|||||||
|
---
|
||||||
|
description: v2023.9.0以降で使用できる、OAuth2.0方式での認証方法について説明しています。
|
||||||
|
---
|
||||||
|
|
||||||
|
# OAuth方式でのアクセストークン取得方式
|
||||||
|
|
||||||
|
アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
以下に説明する方法は、[OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749.html)と呼ばれるものです。普通のOAuthはアプリを作成しますが、[IndieAuth](https://indieauth.spec.indieweb.org/)の拡張でアプリ作成なしで使えるようになっています。
|
||||||
|
|
||||||
|
OAuth方式は使えるライブラリが多いので、出来ればライブラリを使うのをおすすめします。
|
||||||
|
|
||||||
|
現在、この方式を使うためにはウェブページが必要になります。どうしてもウェブページを用意できない場合、もしくはMisskey 2023.9.0以前のバージョンをサポートしたい場合、以下の方式を使ってください。
|
||||||
|
|
||||||
|
- [Misskey専用のMiAuth方式でのアクセストークン取得方法](./oauth.md)
|
||||||
|
- [アプリ作成方式でのアクセストークン取得方法（旧来型）。](./app.md)
|
||||||
|
:::
|
||||||
|
|
||||||
|
## Step 1
|
||||||
|
|
||||||
|
アプリ紹介のためのウェブページを作ります。ページがHTTPSアドレスでアクセスできるようにしてください。ページのとこかに以下のようなHTMLコードを書きます。
|
||||||
|
|
||||||
|
```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](https://www.npmjs.com/package/pkce-challenge)とかのライブラリを使ったり、OAuthライブラリのPKCE機能を使うのがおすすめです。
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
:::tip{label='例'}
|
||||||
|
|
||||||
|
```js
|
||||||
|
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}`の部分は、アプリケーションが要求する権限に置き換えます。要求する権限を` `で区切って列挙します。権限の一覧は[こちら](../permission.md)で確認できます。
|
||||||
|
- `{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='例'}
|
||||||
|
|
||||||
|
```js
|
||||||
|
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`を取得して使います。
|
||||||
@ -1,10 +1,10 @@
|
|||||||
---
|
---
|
||||||
description: MiAuth導入以前のアクセストークン取得方法について説明する。
|
description: MiAuth導入以前（v12.27.0未満）でのアクセストークン取得方法について説明しています。
|
||||||
---
|
---
|
||||||
|
|
||||||
# アプリ作成方式でのアクセストークン取得方法
|
# アプリ作成方式でのアクセストークン取得方法（旧来型）
|
||||||
|
|
||||||
MiAuth導入（12.27.0）より前の、旧来のアクセストークン取得方法について説明します。
|
[MiAuth](./miauth.md)導入（12.27.0）や[OAuth](./oauth.md)導入（2023.9.0）より前の、旧来のアクセストークン取得方法について説明します。
|
||||||
12.27.0未満のバージョンのサーバーではこの旧来の方式を使用する必要があります。
|
12.27.0未満のバージョンのサーバーではこの旧来の方式を使用する必要があります。
|
||||||
|
|
||||||
## 1. アプリケーションの作成
|
## 1. アプリケーションの作成
|
||||||
Loading…
Reference in New Issue
Block a user