github-actions[bot]
a0493dbc4b
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
190 lines
7.4 KiB
Plaintext
190 lines
7.4 KiB
Plaintext
---
|
||
title: OAuth
|
||
icon: key
|
||
description: PKCE を用いた認可コードフロー、およびサーバー間アクセス向けのクライアントクレデンシャル。
|
||
---
|
||
|
||
Twenty は、ユーザー向けアプリでは認可コード + PKCE、サーバー間アクセスではクライアントクレデンシャルを用いた OAuth 2.0 を実装しています。 クライアントは [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) に従って動的に登録され、ダッシュボードでの手動セットアップは不要です。
|
||
|
||
## OAuth を使用するタイミング
|
||
|
||
| シナリオ | 認証方法 |
|
||
| ---------------------- | ---------------------------------------------------------------- |
|
||
| 社内向けスクリプト、自動化 | [API キー](/l/ja/developers/extend/api#authentication) |
|
||
| ユーザーの代理として動作する外部アプリ | **OAuth — 認可コード** |
|
||
| サーバー間、ユーザーコンテキストなし | **OAuth — クライアントクレデンシャル** |
|
||
| UI 拡張機能を備えた Twenty アプリ | [アプリ](/l/ja/developers/extend/apps/getting-started)（OAuth は自動で処理されます） |
|
||
|
||
## クライアントを登録
|
||
|
||
Twenty は [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) に準拠した**動的クライアント登録**をサポートします。 手動セットアップは不要—プログラムで登録します:
|
||
|
||
```bash
|
||
POST /oauth/register
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"client_name": "My Integration",
|
||
"redirect_uris": ["https://myapp.com/callback"],
|
||
"grant_types": ["authorization_code"],
|
||
"token_endpoint_auth_method": "client_secret_post"
|
||
}
|
||
```
|
||
|
||
**レスポンス:**
|
||
|
||
```json
|
||
{
|
||
"client_id": "abc123",
|
||
"client_secret": "secret456",
|
||
"client_name": "My Integration",
|
||
"redirect_uris": ["https://myapp.com/callback"]
|
||
}
|
||
```
|
||
|
||
<Warning>
|
||
`client_secret` は安全に保管してください—後から再取得することはできません。
|
||
</Warning>
|
||
|
||
## スコープ
|
||
|
||
| スコープ | アクセス |
|
||
| --------- | ---------------------------------------- |
|
||
| `api` | Core および Metadata API への読み取り/書き込みのフルアクセス |
|
||
| `profile` | 認証済みユーザーのプロフィール情報を読み取る |
|
||
|
||
スコープはスペース区切りの文字列で指定します: `scope=api profile`
|
||
|
||
## 認可コードフロー
|
||
|
||
アプリが Twenty ユーザーの代理として動作する場合にこのフローを使用します。
|
||
|
||
### 1. ユーザーを認可にリダイレクト
|
||
|
||
```
|
||
GET /oauth/authorize?
|
||
client_id=YOUR_CLIENT_ID&
|
||
response_type=code&
|
||
redirect_uri=https://myapp.com/callback&
|
||
scope=api&
|
||
state=random_state_value&
|
||
code_challenge=CHALLENGE&
|
||
code_challenge_method=S256
|
||
```
|
||
|
||
| パラメーター | 必須 | 説明 |
|
||
| ----------------------- | --- | ------------------------------------------------- |
|
||
| `client_id` | はい | 登録済みのクライアント ID |
|
||
| `response_type` | はい | `code` である必要があります |
|
||
| `redirect_uri` | はい | 登録済みのリダイレクト URI と一致している必要があります |
|
||
| `scope` | いいえ | スペース区切りのスコープ（既定は `api`） |
|
||
| `state` | 推奨 | CSRF 攻撃を防ぐためのランダムな文字列 |
|
||
| `code_challenge` | 推奨 | PKCE チャレンジ（ベリファイアの SHA-256 ハッシュを base64url エンコード） |
|
||
| `code_challenge_method` | 推奨 | PKCE 使用時は `S256` である必要があります |
|
||
|
||
ユーザーに同意画面が表示され、アクセスを許可または拒否します。
|
||
|
||
### 2. コールバックを処理
|
||
|
||
認可後、Twenty はあなたの `redirect_uri` にリダイレクトします:
|
||
|
||
```
|
||
https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
|
||
```
|
||
|
||
`state` が送信した値と一致することを確認します。
|
||
|
||
### 3. コードをトークンに交換
|
||
|
||
```bash
|
||
POST /oauth/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
grant_type=authorization_code&
|
||
code=AUTH_CODE&
|
||
redirect_uri=https://myapp.com/callback&
|
||
client_id=YOUR_CLIENT_ID&
|
||
client_secret=YOUR_CLIENT_SECRET&
|
||
code_verifier=YOUR_PKCE_VERIFIER
|
||
```
|
||
|
||
**レスポンス:**
|
||
|
||
```json
|
||
{
|
||
"access_token": "eyJhbG...",
|
||
"token_type": "Bearer",
|
||
"expires_in": 3600,
|
||
"refresh_token": "dGhpcyBpcyBh..."
|
||
}
|
||
```
|
||
|
||
### 4. アクセストークンを使用
|
||
|
||
```bash
|
||
GET /rest/companies
|
||
Authorization: Bearer ACCESS_TOKEN
|
||
```
|
||
|
||
### 5. 期限切れ時にリフレッシュ
|
||
|
||
```bash
|
||
POST /oauth/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
grant_type=refresh_token&
|
||
refresh_token=YOUR_REFRESH_TOKEN&
|
||
client_id=YOUR_CLIENT_ID&
|
||
client_secret=YOUR_CLIENT_SECRET
|
||
```
|
||
|
||
## クライアントクレデンシャルフロー
|
||
|
||
ユーザー操作のないサーバー間統合向け:
|
||
|
||
```bash
|
||
POST /oauth/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
grant_type=client_credentials&
|
||
client_id=YOUR_CLIENT_ID&
|
||
client_secret=YOUR_CLIENT_SECRET&
|
||
scope=api
|
||
```
|
||
|
||
返されるトークンは特定のユーザーに紐づかないワークスペースレベルのアクセス権を持ちます。
|
||
|
||
## サーバーディスカバリー
|
||
|
||
Twenty は標準のディスカバリーエンドポイントで OAuth 設定を公開しています:
|
||
|
||
```
|
||
GET /.well-known/oauth-authorization-server
|
||
```
|
||
|
||
これにより、すべてのエンドポイント、対応するグラントタイプ、スコープ、および機能が返されます—汎用的な OAuth クライアントを構築するのに役立ちます。
|
||
|
||
## API エンドポイント概要
|
||
|
||
| エンドポイント | 目的 |
|
||
| ----------------------------------------- | ----------------- |
|
||
| `/.well-known/oauth-authorization-server` | サーバーメタデータのディスカバリー |
|
||
| `/oauth/register` | 動的クライアント登録 |
|
||
| `/oauth/authorize` | ユーザー認可 |
|
||
| `/oauth/token` | トークンの交換とリフレッシュ |
|
||
|
||
| 環境 | ベース URL |
|
||
| ---------- | ------------------------ |
|
||
| **クラウド** | `https://api.twenty.com` |
|
||
| **セルフホスト** | `https://{your-domain}` |
|
||
|
||
## OAuth と API キー
|
||
|
||
| | APIキー | OAuth |
|
||
| --------------- | -------------- | ----------------- |
|
||
| **セットアップ** | 設定で生成 | クライアントを登録し、フローを実装 |
|
||
| **ユーザーコンテキスト** | なし（ワークスペースレベル） | 特定ユーザーの権限 |
|
||
| **最適な用途** | スクリプト、社内ツール | 外部アプリ、マルチユーザー統合 |
|
||
| **トークンローテーション** | 手動 | リフレッシュトークンにより自動 |
|
||
| **スコープによるアクセス** | API へのフルアクセス | スコープによりきめ細かな制御 |
|