**注:** アプリケーションをデフォルトのポート8080および8081以外で実行している場合は、eコマースアプリケーションの設定ファイルも更新する必要があります。以下の内容で、`oauthService.json`という名前のファイルをローカルマシン上に作成します:
```json theme={null}
{
"service_name": "Loyalty",
"auth_uri": "http://localhost:8081/loyalty/oauth/authorization",
"redirect_uri": "http://localhost:8080/ecommerce/oauth",
"token_uri": "http://authlete-loyalty:8080/loyalty/oauth/token",
"api_endpoint": "http://authlete-loyalty:8080/loyalty/api/currentCustomer",
"query_params": {
"prompt": "login"
},
}
```
`auth_uri`と`redirect_uri`エンドポイントは、ローカルマシン（Dockerホスト）上で実行されているブラウザからアクセスされます。これらの2つのURLのポート番号を、ロイヤルティコンテナおよびeコマースコンテナで使用しているホストポートに変更します。
`token_uri`や`api_endpoint`のポート番号は変更しないでください。eコマースアプリケーションはこれらのエンドポイントにDockerネットワーク経由で直接アクセスします。
次に、`oauthService.json`をeコマースアプリケーションのコンテナにコピーします:
docker cp oauthService.json authlete-ecommerce:/src/ecommerce/src/main/webapp/WEB-INF/oauthService.json
最後に、eコマースアプリケーションを再ビルドします:
docker exec -it authlete-ecommerce /run/rebuild.sh
## 次のステップ
これで、eコマースアプリケーションにOAuth 2.0クライアントとして必要なすべてが揃いました。次はロイヤルティアプリケーションに取り掛かります。
## サービスクレデンシャルの設定
`$SOURCE_ROOT/loyalty/src/main/webapp/WEB-INF`ディレクトリに`authleteCredential.json`という名前のファイルを作成し、先ほどメモしたサービスオーナークレデンシャル（APIキーとAPIシークレット）を記述します:
```json theme={null}
{
"api_key" : "",
"api_secret" : ""
}
```
各クレデンシャルはダブルクォートで囲む必要があることに注意してください。
では、コーディングを始めましょう！
## ステップ1: 認可の開始
このステップでは、`http://localhost:8081/loyalty/oauth/authorization`にサーブレットを作成し、認可リクエストの処理を行います。
このサーブレットは、受信した認可リクエストをAuthleteのAuthorization APIに転送し、そのレスポンスに従って動作し、ログインページにリダイレクトします。
## 始める前に
前述の通り、ソースディレクトリにはGitリポジトリが含まれています。リポジトリが正しい開始状態にあることを確認するために、以下のコマンドを実行します:
```
git status
```
以下のような出力が表示されます:
```
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
```
リポジトリが`main`ブランチではない場合は、以下のコマンドで正しいブランチをチェックアウトします:
```
git checkout main
```
## 認可サーブレットの作成
`$SOURCE_ROOT/loyalty/src/main/java/com/authlete/simpleauth`に`oauth`という新しいディレクトリを作成し、その中に`OAuthAuthorizationServlet.java`という新しいJavaソースファイルを以下の内容で作成します:
```
package com.authlete.simpleauth.oauth;
import com.authlete.simpleauth.LoginUtils;
import com.authlete.simpleauth.UserAccount;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.GenericType;
import javax.ws.rs.core.MediaType;
import java.io.IOException;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@WebServlet("/oauth/authorization")
public class OAuthAuthorizationServlet extends HttpServlet {
private static final Logger logger = LogManager.getLogger();
private static final long serialVersionUID = 1L;
private final ObjectMapper mapper = new ObjectMapper();
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
}
}
```
ロイヤルティウェブアプリケーションは、サーブレットフィルタを使用してHTTPリクエストをログインページにリダイレクトします。`LoginUtils`クラスの`isPublicPage()`メソッドは、ユーザーのログインを必要とせずに返すことができるリソースを判断します。OAuthサーブレットのパスをそのリソースリストに追加し、サーブレットがログインプロセスを制御できるようにする必要があります。
`$SOURCE_ROOT/loyalty/src/main/java/com/authlete/simpleauth/LoginUtils.java`を開き、`isPublicPage()`メソッドを以下のコードに置き換えます:
```
public static boolean isPublicPage(HttpServletRequest request) {
String requestUri = request.getRequestURI();
String contextPath = request.getContextPath();
// The login page, front page and CSS path are public
return requestUri.equals(contextPath + "/login") ||
requestUri.equals(contextPath + "/index.html") ||
requestUri.equals(contextPath + "/") ||
requestUri.startsWith(contextPath + "/css") ||
requestUri.startsWith(contextPath + "/oauth/");
}
```
## AuthleteのAuthorization APIの呼び出し
先ほど作成した`OAuthAuthorizationServlet.java`ファイルに戻り、`doGet()`メソッドに以下のコードを追加します:
```
initiateAuthleteAuthorization(request, response);
```
次に、同じクラス内に以下のコードを追加し、`initiateAuthleteAuthorization()`メソッドを定義します:
```
private void initiateAuthleteAuthorization(HttpServletRequest request, HttpServletResponse response) throws IOException {
// 1. Get a Jersey HTTP client
Client client = OAuthUtils.getClient(getServletContext());
// 2. We will wrap the incoming query string in a JSON object
Map
同社は近日中にeコマースウェブサイトを立ち上げる予定です。このPoCの要件は、既存のロイヤルティプログラムメンバーが自分のロイヤルティアカウントをeコマースサイトにリンクし、eコマースのフロントページでポイント残高を表示できるようにすることです。将来的には、顧客がロイヤルティポイントを購入に利用できる本番システムを導入する予定です。
この統合は「ファーストパーティ」統合であることに注意してください。ロイヤルティプログラムとeコマースサイトはどちらも同じ会社が運営しています。このようなケースでは、クライアントがサービスでユーザーデータにアクセスできるかどうかを明示的に尋ねるステップを省略する場合があります。しかし、たとえロイヤルティプログラムのウェブサイトに既にアクティブセッションがあったとしても、アカウントをリンクする際には、ユーザーが本当にアカウントをリンクしたいことを確認するためにログインを要求します。
eコマースチームは既に[OAuth 2.0](https://www.rfc-editor.org/rfc/rfc6749) クライアントを実装済みです。あなたの仕事は、ロイヤルティプログラムチームの開発者として、ロイヤルティプログラムのウェブアプリケーションに[OAuth 2.0 の認可サーバーとリソースサーバーの役割](https://www.rfc-editor.org/rfc/rfc6749#section-1.1)を実装することです。
あなたはOAuth 2.0の基本を理解しており、顧客のブラウザ（以下の図での「リソースオーナーの『ユーザーエージェント』」）、eコマースウェブサイト（「クライアント」）、およびロイヤルティプログラムのウェブサイト（「認可サーバー」と「リソースサーバー」）の間でどのようなやり取りが行われるかも把握しています。
1. 認可の開始
* 顧客がeコマースサイトで「Link Account」をクリックします。
* eコマースのOAuthクライアントが、クライアントIDとリダイレクトURLをクエリパラメータとして含む形で、顧客のブラウザをロイヤルティプログラムの認可サーバーにリダイレクトします。
* ロイヤルティプログラムの認可サーバーがログインフォームを表示します。
* 顧客が通常の方法でロイヤルティプログラムのウェブサイトにログインします。
2. クライアントへの認可コードの発行
* 認可サーバーが顧客のブラウザをeコマースサイトにリダイレクトし、認可コードを渡します。
3. クライアントのアクセストークン要求の処理
* eコマースのOAuthクライアントが認可コード、クライアントID、およびクライアントシークレットを認可サーバーに送信します。
* 認可サーバーがアクセストークンをクライアントに返します。
4. クライアントからのロイヤルティプログラムAPIへのリクエストの検証
* eコマースウェブサイトは、顧客のポイント残高を要求するAPIリクエストにアクセストークンを含めます。
* ロイヤルティプログラムのリソースサーバーはアクセストークンを検証し、そのリクエストに顧客の識別子を添付して、ロイヤルティプログラムAPIに処理を移します。
*注意: OAuthの仕様および上記の図では、ユーザーを認証および認可する役割を担う認可サーバーと、APIリクエストを処理する役割を担うリソースサーバーを区別しています。仕様ではこれらを2つの別々の役割として明示していますが、単一のアプリケーションが両方の役割を果たすことも可能であり、このチュートリアルでのロイヤルティプログラムのウェブアプリケーションはこの例に該当します。*
大変な仕事のように見えるかもしれませんが、Authleteがあれば、これを1〜2時間で完了できます！
# 前提条件
必要なもの:
* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* 任意のコードエディタ
* Java EE の基礎知識
# セットアップ
デモシステムは、eコマースウェブサイト用とロイヤルティサイト用の2つのJava EEウェブアプリケーションをそれぞれ格納するDockerコンテナのペアとして実装されています。
## Dockerネットワークの作成
上記のフローのステップ3では、eコマースOAuthクライアントがロイヤルティ認可サーバーに直接リクエストを送信します。このため、eコマースコンテナがロイヤルティコンテナのIPアドレスを解決できるように、[Dockerネットワーク](https://docs.docker.com/network/)を作成する必要があります。以下のコマンドを実行してください:
```
docker network create --driver bridge authlete-net
```
## Start the E-Commerce Container
Start the e-commerce container with
```
docker run -d \
--name authlete-ecommerce \
--network authlete-net \
--publish 8080:8080 \
us-docker.pkg.dev/authlete/demo/java-getting-started-ecommerce:latest
```
環境に合わせて`docker run`の引数を変更できます:
* Tomcatはコンテナ内でポート8080でリッスンするように設定されています。上記の例では、Dockerがホストのポート8080にそのポートを公開しています。マシン上でポート8080がすでに使用されている場合は、`--publish 12345:8080`を指定して別のホストポートを選択できます。その場合、チュートリアル全体で8080を選択したポートに変更する必要があります。
以下のコマンドでコンテナのログを表示することで、コンテナが正しく起動し、Tomcatが準備完了状態であることを確認できます:
```
docker logs authlete-ecommerce
```
以下のような2行のログが表示されます:
```
19-Mar-2022 22:24:15.466 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
19-Mar-2022 22:24:15.472 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [3463] milliseconds
```
エラーが起きていないにも関わらず、出力の最後にこれらのログが表示されない場合は、Tomcatがまだ起動中です。数秒待ってから再度確認してください。
必要に応じて、以下のコマンドでDockerコンテナを一時停止できます:
```
docker pause authlete-ecommerce
```
チュートリアルを再開する準備ができたら、以下のコマンドで再開します:
```
docker resume authlete-ecommerce
```
## ロイヤルティコンテナの起動
ロイヤルティコンテナは、[Docker bind mount](https://docs.docker.com/storage/bind-mounts/)を使用してローカルディレクトリにソースコードを公開します。これにより、任意のソースコードエディターやIDEでホストマシン（Dockerホスト）のコードを編集できます。
ソースディレクトリは、ローカルマシン上の任意の場所に作成できます。このチュートリアルでは、このディレクトリを`$SOURCE_ROOT`と呼びます。
ソースディレクトリはDockerコンテナを起動する前に存在している必要があり、`docker run`でコンテナを起動する際に`--mount`オプションで参照する必要があります。
例えば、`/Users/jdoe/authlete_src`をソースディレクトリとして使用する場合:
```
mkdir /Users/jdoe/authlete_src
docker run -d \
--name authlete-loyalty \
--network authlete-net \
--publish 8081:8080 \
--mount type=bind,source="/Users/jdoe/authlete_src",target=/mount \
us-docker.pkg.dev/authlete/demo/java-getting-started-loyalty:latest
```
コンテナの起動後、`ls /Users/jdoe/authlete_src`コマンドでソースディレクトリを見ると、`loyalty`サブディレクトリが含まれていることが確認できます。このディレクトリにはロイヤルティウェブアプリケーションのソースコードが含まれています。このソースディレクトリにはgitリポジトリも含まれているため、チュートリアルの各ステップ後に必要に応じてコードをチェックアウトすることが簡単にできます。
ロイヤルティコンテナは、eコマースコンテナとは異なるホストポートでリッスンする必要があります。このチュートリアルでは、eコマースコンテナはポート8080で、ロイヤルティコンテナはポート8081でリッスンします。
前セクションに記載されているように、`docker run`の引数を変更すると、ホストポート番号を変更することができます。
eコマースコンテナと同様のコマンドを使用して、コンテナログの確認、コンテナの一時停止、および再開を行います。その際は、eコマースインスタンス名の代わりにロイヤルティインスタンス名である`authlete-loyalty`を使用することを忘れないでください。
# サンプルウェブサイトの確認
## ロイヤルティプログラムウェブサイト
[http://localhost:8081/loyalty/](http://localhost:8081/loyalty/)にアクセスします。ロイヤルティプログラムのホームページが表示され、プレースホルダーテキストとログインリンクが表示されます。リンクをクリックして、ページに表示されているクレデンシャルのセットのいずれか1つを使ってログインします。すると、アカウントの概要が表示され、取引リストが表示されます。ロイヤルティプログラムウェブアプリケーションは、アプリケーションが起動するたびにサンプル取引が読み込まれるインメモリデータベースを使用しています。「Redeem Points」をクリックして、リンクされた銀行口座に対して現金を振り込むためにロイヤルティポイントを交換するシミュレーションを行うことができます。この機能を使用すると、システムが稼働している間にアカウント残高を簡単に変更できるため、残高が動的に取得されていることを確認できます。
このチュートリアルには、ロイヤルティプログラムウェブアプリケーションをOAuth 2.0対応にするために必要なすべてが含まれています。ロイヤルティおよびeコマースウェブアプリケーションのソースコードは[https://github.com/authlete/java-getting-started](https://github.com/authlete/java-getting-started)で自由に確認できます。どちらもJava JDK 11でApache Tomcat 9.0.x向けに書かれています。アプリケーションには以下の技術が使用されています:
* [Eclipse Jersey](https://eclipse-ee4j.github.io/jersey/) Java RESTフレームワーク、バージョン2.34
* [Hibernate](https://hibernate.org) Java Persistence API (JPA) の実装、バージョン5.6.4.Final
* [H2](https://www.h2database.com/) インメモリデータベースエンジン、バージョン2.1.210
* [Apache Log4j](https://logging.apache.org/log4j/2.x/) ロギングフレームワーク、バージョン2.17.1
* [Java Server Pages](https://www.oracle.com/java/technologies/jspt.html) (JSP) をeコマースウェブサイトで使用
* HTML5、JavaScript、CSSをロイヤルティウェブサイトで使用
eコマースチームはOAuthクライアントを実装し、ロイヤルティ認可サーバーのURLについても合意していますが、まだロイヤルティ認可サーバーの実装は存在していません。それを修正しましょう！
# Authleteアカウントの作成とクライアントアプリケーションの設定
[Authleteアカウントにサインアップ](https://so.authlete.com/accounts/signup)し、サービスオーナーコンソールに遷移します。すると、初期作成されたサービスの一覧が表示されます。
サービスをクリックして詳細を確認します。
ロイヤルティプログラムは、Authleteの観点からは「サービス」と見なされ、ここでそのAuthlete設定を管理します。
**APIキー**と**APIシークレット**をメモしておいてください。次のステップで必要になります。
下にスクロールすると、**クライアントアプリ開発者コンソール**へのリンクが表示されます。
リンクをクリックし、APIキーをログインID、APIシークレットをパスワードとして使用してログインします。
デフォルトのクライアントアプリケーションが表示されない場合は、**アプリ作成**をクリックしてアプリケーションを作成します。クライアントアプリケーションは、eコマースサイトのOAuth 2.0設定に該当します。
アプリケーションをクリックして詳細を確認します。
**クライアントID**と**クライアントシークレット**をメモしておいてください。これも後で必要になります。
次に、このシナリオに合わせてクライアントの初期設定をいくつか変更します。
ページの下部にスクロールし、**編集**をクリックします。
eコマースアプリケーションは、クレデンシャルの機密性を維持できるWebアプリケーションです（詳細は[Client Types](https://www.rfc-editor.org/rfc/rfc6749#section-2.1)を参照）。クレデンシャルはサーバーで安全に保存されるため、**アプリケーションタイプ**を**WEB**に、**クライアントタイプ**を**CONFIDENTIAL**に変更します。
次に、**認可**タブをクリックします。このシナリオでは、クライアントは[authorization code grant type](https://www.rfc-editor.org/rfc/rfc6749#section-1.3.1)を使用し、認可サーバーから認可コードを受け取ることを期待しているため、**認可種別**の**AUTHORIZATION\_CODE**にチェックが入っていることを確認し、さらに**応答種別**の**CODE**ににチェックが入っていることを確認します。
上記のステップ2で、ユーザーを認証した後、認可サーバーがユーザーのブラウザをクライアントアプリケーションにリダイレクトします。このリダイレクトURIをクライアント設定に追加する必要があります。**リダイレクトURI作成**をクリックし、クライアントのリダイレクトURIを入力します:
`http://localhost:8080/ecommerce/oauth`
その後、**作成**をクリックし、モックのリダイレクトURIを削除します。
アクセストークンを取得する際、クライアントは[section 2.3 of RFC 674](http://tools.ietf.org/html/rfc6749#section-2.3)に従って認可サーバーに対してクレデンシャルをPOSTします（上記のステップ3）。これを設定するには、**トークンエンドポイント**までスクロールし、**クライアント認証方式**を**CLIENT\_SECRET\_POST**に変更します。下までスクロールし、**更新**をクリックしてから、**OK**をクリックして設定を保存します。
## クレデンシャルを設定しクライアントアプリケーションを再起動する
eコマースアプリケーションは環境変数からクレデンシャルを読み取るため、eコマースコンテナを停止して、先ほどメモしたクライアントIDとシークレットを渡したうえで再起動します。
まず、eコマースコンテナを停止し、削除します:
```
docker stop authlete-ecommerce
docker rm authlete-ecommerce
```
次に、再度実行し、コマンドラインで`CLIENT_ID`と`CLIENT_SECRET`環境変数を設定します:
```
docker run -d \
--name authlete-ecommerce \
--network authlete-net \
--publish 8080:8080 \
--env CLIENT_ID="your_client_id" \
--env CLIENT_SECRET="your_client_secret" \
us-docker.pkg.dev/authlete/demo/java-getting-started-ecommerce:latest
```