Core API は、/auth/authorization、/auth/token、/auth/userinfo など、OAuth 2.0 / OpenID Connect のプロトコルリクエストを処理する Authlete API 群です。認可サーバーはクライアントアプリケーションからのリクエストを自身のエンドポイントで受け取り、プロトコル処理を Core API に委譲します。
このページでは、Core API に共通するリクエスト・レスポンスの構造を説明します。
リクエスト形式
Core API は JSON ボディを持つ HTTP POST リクエストを受け付けます。Authorization ヘッダーにはサービスアクセストークンを指定します。
curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "parameters": "response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb%2Fexample.com" }'
us.authlete.com をご利用のクラスターホスト（eu.authlete.com、jp.authlete.com など）に置き換えてください。サービスアクセストークンの取得方法は認証を参照してください。
主なリクエストパラメーター
リクエストパラメーターの正確な構成は API ごとに異なり、サービスがサポートする OAuth/OIDC 仕様にも依存するため、完全には一般化できません。呼び出す API の API リファレンスを必ず確認してください。そのうえで、多くの Core API に共通して登場する主なリクエストパラメーターは次のとおりです。
| パラメーター | 説明 |
|---|
parameters | エンドポイントがクライアントから受け取ったリクエストをそのまま渡します。認可エンドポイントではクエリ文字列、トークンエンドポイントでは application/x-www-form-urlencoded のリクエストボディです。 |
clientId | クライアント ID。クライアントが client_secret_basic で認証する場合は、トークンエンドポイントへのリクエストの Authorization: Basic ヘッダーから取り出します。 |
clientSecret | クライアントシークレット。同様に Authorization: Basic ヘッダーから取り出します。 |
clientCertificate | mutual TLS 接続のクライアント証明書。mTLS クライアント認証や証明書バインドアクセストークン（RFC 8705）をサポートする場合に必要です。 |
ticket | 2 段階呼び出しの 1 つ目の API（/auth/authorization など）が返すチケット。2 つ目の API（/auth/authorization/issue など）に渡します。2 段階の API 呼び出しを参照してください。 |
token | 検査対象のアクセストークン。/auth/introspection や /auth/userinfo などで使用します。 |
subject | サーバーが認証したエンドユーザーの一意な識別子。/auth/authorization/issue などの発行系 API に渡します。 |
dpop、htm、htu が加わります。
クライアントからのリクエストパラメーターはそのまま渡す
認可サーバーは、認可エンドポイントやトークンエンドポイントで受け取ったパラメーターを、対応する Authlete API にそのまま渡すことが期待されます。原則として、事前に変更・加工してはいけません。
たとえば認可リクエストの scope パラメーターの値を確認したい場合でも、/auth/authorization API を呼び出す前に検証する必要はありません。クエリ文字列全体を parameters フィールドの値としてそのまま渡してください。Authlete がリクエストを検証し、検証済みのスコープ値をレスポンスで返すので、認可サーバーはそれを安全に利用できます。
/auth/authorization や /auth/token の呼び出し前に独自の検証・加工処理を実装することにはリスクがあります。Authlete のプロトコル処理やエラーチェックを活用できなくなり、最悪の場合、認可サーバーが OAuth 2.0 / OpenID Connect に非準拠となるおそれがあります。 レスポンス形式
Core API のレスポンスは次のフィールドを共通して持ちます。
| フィールド | 説明 |
|---|
resultCode | 処理結果を識別するコード（例：A004001）。ログ記録やトラブルシューティングに利用します。 |
resultMessage | 処理結果を説明する、人間が読めるメッセージ。 |
action | サーバーが次に取るべきアクション。実装はこのフィールドで分岐しなければなりません。 |
responseContent | クライアントへのレスポンス構築に使う内容。JSON ボディやエラーパラメーター付きのリダイレクト URI などです。 |
action フィールドは Core API のプログラミングモデルの中核です。クライアントにどのような HTTP レスポンスを返すべきか、あるいは次にどの Authlete API を呼ぶべきかを示します。詳細はアクションハンドリングを参照してください。
resultCode を処理の分岐条件に使ってはいけません。結果コードは診断情報であり、認可サーバーの処理の分岐は action を利用することが推奨されます。
