JAX-RS

JAX-RS Web サービスは Liferay モジュール内でも Liferay 外部と同じように動作しますが、OSGi フレームワークにクラスを登録する必要があります。 これらのアプリケーションを作成する方法については、 Jakarta のドキュメントを参照してください。 ここでは、Liferay で JAX-RS アプリケーションを統合および認証する方法を示します。

サンプルのREST APIをデプロイする

この例では、カタログ内の ID によってテスト製品を返すサンプル API をデプロイします。 この例がどのように機能するかを理解したら、独自のアプリケーション用の API を作成できます。

新しいLiferay インスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132

http://localhost:8080でLiferayにサインインします。 メールアドレス test@liferay.com とパスワード testを使用してください。 プロンプトが表示されたら、パスワードを learnに変更します。

次に、以下の手順に従います。

1. liferay-u6b1.zip サンプルプロジェクトをダウンロードして解凍します。

   curl https://resources.learn.liferay.com/examples/liferay-u6b1.zip -O
   

   unzip liferay-u6b1.zip
   

2. サンプルをビルドしてデプロイします。

   ./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
   

   注

   このコマンドは、デプロイされたjarをDockerコンテナ上の /opt/liferay/osgi/modules にコピーするのと同じです。

3. Docker コンテナ コンソールでデプロイメントを確認します。

   STARTED com.liferay.headless.admin.site.internal.jaxrs.application_1.0.0
   

JAX-RS Webサービスの認証

認証には、基本認証と OAuth 2.0 の 2 つの方法があります。 基本認証は、本番環境では決して使用しないでください。これは、開発者が開発中に簡単に使用できるようにするために用意されているものです。 URL で渡された資格情報はサーバー ログに表示されるため、ログにアクセスできるユーザーに資格情報が漏洩する可能性があります。

基本認証で認証する場合、 サービス アクセス ポリシー SYSTEM_USER_PASSWORD が適用されます。 OAuth 2.0 経由で認証する場合、 AUTHORIZED_OAUTH2_SAP ポリシーが適用されます。 デフォルトではすべてのリモート サービスの呼び出しが許可されるため、環境に合わせて適切に構成してください。 JAX-RSエンドポイントに対するサービスアクセスポリシーの適用を無効にして、ゲストがデフォルトのサービスアクセスポリシーなしでこれらのエンドポイントを呼び出せるようにするには、 liferay.access.control.disable プロパティを trueに設定します。

@Component(
    property = {
        JaxrsWhiteboardConstants.JAX_RS_APPLICATION_BASE + "=/greeting",
        JaxrsWhiteboardConstants.JAX_RS_NAME + "=Greeting.Rest",
        "liferay.access.control.disable=true"
    },
    service = Application.class)

META-INF/services/com.liferay.portal.security.auth.verifier.internal.tracker.AuthVerifierFilterTracker.config ファイルで次のプロパティを設定することにより、OAuth 2.0 とポータルセッション認証を有効にしたまま、すべての JAX-RS アプリケーションの基本認証を無効にすることができます。

default.registration.property=["filter.init.auth.verifier.OAuth2RESTAuthVerifier.urls.includes=*","filter.init.auth.verifier.PortalSessionAuthVerifier.urls.includes=*"]

開発中: 基本認証の使用

JAX-RS アプリケーションをデプロイすると、認証検証フィルターが登録されます。 プロパティの前にauth.verifierを付けることで、@Componentアノテーションでプロパティを設定できます。 たとえば、サービスへのゲスト アクセスを無効にするには、次の構成を使用します。

@Component(
    property = {
        JaxrsWhiteboardConstants.JAX_RS_APPLICATION_BASE + "=/greeting",
        JaxrsWhiteboardConstants.JAX_RS_NAME + "=Greeting.Rest",
        "auth.verifier.guest.allowed=false"
    },
    service = Application.class)

OAuth 2.0の使用

JAX-RS Web サービスでは、デフォルトで認証が必要です。 これを有効にするには、まず OAuth 2.0 アプリケーション を作成して、サービスへのアクセスを許可する方法を提供する必要があります。 ヘッドレス サーバー プロファイルを選択します。このプロファイルは、 クライアント資格情報 認証タイプを使用するため、サービスを非対話形式で呼び出すことができます。 次に、サービスをアクセス可能にするために、

1. 新しい OAuth 2.0 アプリケーションを開きます。

2. スコープ タブをクリックします。

3. 矢印をクリックして、 Greeting.Rest サービスを展開します。

4. 「 あなたに代わってデータを読み取る」というラベルの付いたボックスをチェックします。

5. [保存]をクリックします。

次に、新しい OAuth 2.0 アプリケーション用に生成されたクライアント ID とクライアント シークレットを使用して、OAuth トークンを要求する必要があります。 簡単にするために、以下の例では Curl を使用して認証します。 ローカルでテストする場合は、次のようなリクエストを作成します。

curl http://localhost:8080/o/oauth2/token -d 'grant_type=client_credentials&client_id=[Your Client ID here]&client_secret=[Your Client Secret here]'

JSON 形式の応答には、このクライアント用に生成されたトークンが含まれます。 例:

{"access_token":"a7f12bef7f2e578cf64bce4085db8f17b6a3c2963f865a65b374e89784bbca5","token_type":"Bearer","expires_in":600,"scope":"GET POST PUT"}

有効期限は 600 秒で、この Web サービスに対して GET、POST、および PUT を許可します。 サービスを呼び出すときは、次のように HTTP ヘッダーにトークンを指定する必要があります。

curl --header "Authorization: Bearer [Your access token here]" http://localhost:8080/o/greeting

承認されると、Web サービスを呼び出すことができ、リクエストに応答します。

Hello, World!

Curl は OAuth 2.0 で認証する多くの方法の 1 つですが、実稼働環境では推奨されません。 詳細については、 OAuth 2.0 の使用 を参照してください。

OAuth 2.0のスコープ

OAuth 2.0 アノテーションまたはプロパティのない標準の JAX-RS アプリケーションでは、スコープはアプリケーションでサポートされている HTTP 動詞に基づいて導出されます。 スコープを指定するには、oauth2.scope.checker.type=annotationsプロパティと、Liferay OAuth2 Provider Scope APIバンドルからエクスポートされたcom.liferay.oauth2.provider.scope.RequiresScopeアノテーションを使用して、エンドポイントリソースのメソッドやクラス全体にこのようなアノテーションを付けます：

@RequiresScope("scopeName")

デプロイされると、これは OAuth 2.0 構成のスコープになります。 スコープ チェッカーを存在しない型に設定することで、スコープ チェックを無効にすることができます (非推奨)。

@Component(
    property = {
        JaxrsWhiteboardConstants.JAX_RS_APPLICATION_BASE + "=/greeting",
        JaxrsWhiteboardConstants.JAX_RS_NAME + "=Greeting.Rest",
        "oauth2.scope.checker.type=none"
    },
    service = Application.class)

@Component アノテーションでこのプロパティを使用することにより、JAX-RS アプリケーションに必要な OAuth 2.0 認証を指定できます。

osgi.jaxrs.extension.select=(osgi.jaxrs.name=Liferay.OAuth2)

CORS で JAX-RS を使用する

@CORS アノテーションを使用して、デプロイされた JAX-RS アプリケーションに CORS ポリシー を定義し、別のドメインからアクセスできるようにすることができます。

1. Portal Remote CORS API 依存関係をモジュールの build.gradle ファイルに追加します。

compileOnly project(":apps:portal-remote:portal-remote-cors-api")

1. アプリケーション プロパティで CORS アノテーション機能を有効にします。

@Component(
    property = {
        "osgi.jaxrs.application.base=/my-application",
        "osgi.jaxrs.name=My.Application.Name",
        "liferay.cors.annotation=true"
    },
    service = Application.class
    )

1. アプリケーション全体でグローバルまたはメソッドごとに @CORS アノテーションを使用します。

世界的に：

@CORS(allowMethods="GET")
public class HeadlessAdminSiteApplication extends Application {

方法別：

@CORS
	@GET
	@Path("/users")
	public List<User> getUserList() throws Exception {
		return _users;
	}

アノテーションを使用して、任意の CORS ヘッダーの構成を提供できます。

ここまでで、 これで、Liferay で JAX-RS Web サービスを作成、デプロイ、および呼び出す方法がわかりました。

関連トピック

• RESTビルダー