これはリソースサーバーの Java による実装です。 OpenID Connect Core 1.0 で定義されているユーザー情報エンドポイント をサポートし、また、RFC 6750 (The OAuth 2.0 Authorization Framework: Bearer Token Usage) に定義されている方法でアクセストークンを受け取る保護リソースエンドポイントの例も含んでいます。
この実装は JAX-RS 2.0 API と authlete-java-jaxrs ライブラリを用いて書かれています。 JAX-RS は The Java API for RESTful Web Services です。 JAX-RS 2.0 API は JSR 339 で標準化され、Java EE 7 に含まれています。 一方、authlete-java-jaxrs は、認可サーバーとリソースサーバーを実装するためのユーティリティークラス群を提供するオープンソースライブラリです。 authlete-java-jaxrs は authlete-java-common ライブラリを使用しており、こちらは Authlete Web API とやりとりするためのオープンソースライブラリです。
クライアントアプリケーションが提示したアクセストークンの有効性を調べるため、 このリソースサーバーは Authlete サーバーに問い合わせをおこないます。 これはつまり、このリソースサーバーは、アクセストークンを発行した認可サーバーが Authlete をバックエンドサービスとして使用していることを期待していることを意味します。 java-oauth-server はそのような認可サーバーの実装であり、OAuth 2.0 と OpenID Connect をサポートしています。
Apache License, Version 2.0
https://github.com/authlete/java-resource-server
Authlete (オースリート) は、OAuth 2.0 & OpenID Connect の実装をクラウドで提供するサービスです (overview)。 Authlete が提供するデフォルト実装を使うことにより、もしくは java-oauth-server でおこなっているように Authlete Web API を用いて認可サーバーを自分で実装することにより、OAuth 2.0 と OpenID Connect の機能を簡単に実現できます。
この認可サーバーの実装を使うには、Authlete から API
クレデンシャルズを取得し、authlete.properties に設定する必要があります。
API クレデンシャルズを取得する手順はとても簡単です。
単にアカウントを登録するだけで済みます (サインアップ)。
詳細は Getting Started を参照してください。
-
このリソースサーバーの実装をダウンロードします。
$ git clone https://github.com/authlete/java-resource-server.git $ cd java-resource-server -
設定ファイルを編集して API クレデンシャルズをセットします。
$ vi authlete.properties -
maven がインストールされていること、
JAVA_HOMEが適切に設定されていることを確認します。 -
http://localhost:8081/ でリソースサーバーを起動します。
$ mvn jetty:run &
Docker を利用する場合は, ステップ 2 の後に以下のコマンドを実行してください.
$ docker-compose up
java-resource-server は authlete.properties を設定ファイルとして参照します。
他のファイルを使用したい場合は、次のようにそのファイルの名前をシステムプロパティー
authlete.configuration.file で指定してください。
$ mvn -Dauthlete.configuration.file=local.authlete.properties jetty:run &
この実装は、下表に示すエンドポイントを公開します。
| エンドポイント | パス |
|---|---|
| ユーザー情報エンドポイント | /api/userinfo |
| カントリーエンドポイント | /api/country/{国コード} |
ユーザー情報エンドポイントは、OpenID Connect Core 1.0 の 5.3. UserInfo Endpoint に記述されている要求事項を実装したものです。
このエンドポイントは、アクセストークンを Bearer Token として受け取ります。
つまり、Authorization: Bearer {アクセストークン}
を介して、もしくはリクエストパラメーター access_token={アクセストークン}
によりアクセストークンを受け取ります。 詳細は RFC 6750 を参照してください。
このエンドポイントは、クライアントアプリケーションの設定に応じて、ユーザー情報を
JSON 形式もしくは JWT 形式で返します。 クライアントアプリケーションのメタデータの
userinfo_signed_response_alg と userinfo_encrypted_response_alg
の両方とも指定されていなければ、ユーザー情報は素の JSON で返されます。
そうでない場合は、シリアライズされた JWT で返されます。 Authlete
はクライアントアプリケーションのメタデータを管理するための Web コンソール
(デベロッパー・コンソール) を提供しています。
クライアントアプリケーションのメタデータについては、
OpenID Connect Dynamic Client Registration 1.0 の 2. Client Metadata
を参照してください。
エンドポイントから返されるユーザー情報には、ユーザーのクレームが含まれています。
手短に言うと、_クレーム_とは、名前やメールアドレスなどの、ユーザーに関する情報です。
Authlete は (OpenID Connect をサポートしているにもかかわらず)
ユーザーデータを管理しないので、あなたがクレーム値を提供しなければなりません。
これは、UserInfoRequestHandlerSpi インターフェースを実装することでおこないます。
このリソースサーバーの実装では、UserInfoRequestHandlerSpiImpl が UserInfoRequestHandlerSpi
インターフェースの実装で、ダミーデータベースからクレーム値を取り出しています。
実際のユーザーデータベースを参照するよう、この実装を変更する必要があります。
java-oauth-server にもユーザー情報エンドポイントが実装されました。 java-resource-server のユーザー情報エンドポイントの実装はメンテナンスされません。
java-oauth-server のユーザー情報エンドポイントは、OpenID Connect for Identity Assurance 1.0 のフィルタリング規則とデータ最小化ポリシーを正しく実装し、また、 OpenID Connect Advanced Syntax for Claims 1.0 で定義されている変換クレーム (Transformed Claim) をサポートします。
このリソースサーバーに実装されているカントリーエンドポイントは、
保護リソースエンドポイントの一例に過ぎません。
主な目的は、保護リソースエンドポイントにおけるアクセストークンの有効性の確認方法を示すことです。
具体的には、BaseResourceEndpoint クラスの extractAccessToken メソッドと
validateAccessToken メソッドの使い方を示すことです。
カントリーエンドポイントのパスは /api/country/{国コード} で、{国コード} の部分は
ISO 3166-1 コードです (alpha-2、alpha-3 または numeric)。
例えば、JP、JPN、392 は有効な ISO 3166-1 コードで、これらは全て日本を表します。
ですので、次の URL はカントリーエンドポイントに対する有効なリクエストです。
http://localhost:8081/api/country/JP?access_token={access-token}
エンドポイントからの応答は JSON で、{国コード} で指定された国に関する次の情報を含んでいます。
- 国名
- ISO 3166-1 alpha-2 コード
- ISO 3166-1 alpha-3 コード
- ISO 3166-1 numeric コード
- 通貨
次に示すのは応答例です。
{
"name": "Japan",
"alpha2": "JP",
"alpha3": "JPN",
"numeric": 392,
"currency": "JPY"
}Web API を OAuth のアクセストークンで保護する方法に関する一般的な情報および Authlete 固有の情報については、Authlete Definitive Guide の Protected Resource を参照してください。
新しい保護リソースエンドポイントを追加する最も簡単な方法は、CountryEndpoint
がおこなっているように、BaseResourceEndpoint のサブクラスを作成する方法です。
しかし、もちろん、直接 AcessTokenValidator (authlete-java-jaxrs) を使用したり
AuthleteApi.introspection(IntrospectionRequest) API (authlete-java-common)
をコールしてもかまいません。
新しい保護リソースエンドポイントを追加するに従い、新しいスコープを追加したいと思うでしょう。 あなたの Web API 用に新しいスコープを追加するには、サービスオーナー・コンソール を使用してください。
- Authlete - Authlete ホームページ
- authlete-java-common - Java 用 Authlete 共通ライブラリ
- authlete-java-jaxrs - JAX-RS (Java) 用 Authlete ライブラリ
- java-oauth-server - 認可サーバーの実装
| 目的 | メールアドレス |
|---|---|
| 一般 | [email protected] |
| 営業 | [email protected] |
| 広報 | [email protected] |
| 技術 | [email protected] |