63 WEMフレームワークでのRESTリソースの使用

RESTリソースはWEMフレームワーク内で使用できます。

RESTリソースの使用の詳細は、次の項を参照してください。

63.1 RESTリソースの認証

WEMフレームワークでは、CAS (http://www.jasig.org/cas)上に構築されたSSOメカニズムを認証の際に使用します。このシステムの動作は、REST APIをブラウザから使用するか、プログラムから使用するかによって異なります。

ブラウザからREST APIにアクセスすると、ユーザーはCASログイン・ページにリダイレクトされ、ログインに成功すると、ユーザーのアイデンティティを確立するために検証されるticketパラメータによって、元の位置に戻されます。プログラムでREST APIにアクセスする場合は、開発者がticketパラメータまたはmultiticketパラメータのいずれかを指定する必要があります。

ticketおよびmultiticketパラメータを取得するにはいずれも、Oracle SSO APIを使用するか(Javaでコールする場合)、単にHTTPプロトコルを使用します(他の言語でコールする場合)。ticketとmulticketの違いは、ticketはRESTリソースごとに取得され、1回しか使用できないのに対し(名前からわかるように、列車や劇場のチケットが1回の乗車あるいは1回の鑑賞のみに有効であることを想像してください)、multiticketは任意のリソースに対して複数回使用できます。ticketおよびmultiticketパラメータはいずれも回数に制限がありますが、一般的な使用パターンが異なります。チケットはコールごとに取得されるので、有効期限はありません。一方、同じmultiticketを再利用すると最終的に期限切れとなり、HTTP 403エラーが発生します。期限切れになった場合、アプリケーションでこのような動作を認識して、そのmultiticketを再取得できる必要があります。ticketとmultiticketのどちらを使用するかは、アプリケーション開発者が決定します。

この項には次のトピックが含まれます:

63.1.1 Javaコードからのチケットの取得

Oracle SSO APIは、認証プロバイダに依存しない方法で実装されています。ただし、ユーザーは独自のSSO認証プロバイダを登録できません。新しい認証プロバイダのサポートは、Oracleでのみ実装できます。プロバイダの切替えは、SSO構成ファイルを変更するのみで済みます。

すべてのSSOコールは、SSOフロントエンド・クラスSSOで開始します。これは、SSOSessionオブジェクトの取得に使用されます。SSOSessionは、SSO構成ごとに取得されます。Webアプリケーションの場合はSpring Webアプリケーション・ローダーを使用してロードされた単一の構成、またはスタンドアロン・アプリケーションの場合は構成ファイルからロードされた構成となります。

Webアプリケーションでチケットを取得するには:

SSO.getSession().getTicket(String service, String username, String password)
SSO.getSession().getMultiTicket(String username, String password)

スタンドアロン・アプリケーションでチケットを取得するには:

SSO.getSession(String configName).getTicket
  (String service, String username, String password)
SSO.getSession(String configName).getMultiTicket
  (String username, String password)

63.1.2 他のプログラミング言語からのチケットの取得(HTTPを経由)

CAS REST APIは、チケットまたはマルチチケット(あるいはその両方)を配信環境で取得するために使用します。チケットまたはマルチチケットのいずれかを取得するには、2つのHTTP POSTコールを実行する必要があります。チケットとマルチチケットとの違いは、マルチチケットの場合はserviceパラメータが*(アスタリスク)であるのに対し、ticketパラメータの場合は、実際にアクセスするRESTリソースである点です。

次の例では、CASサーバーに対して実行されるコールを示します。このコールでは、資格証明fwadmin/xceladminを使用してhttp://localhost:8080/cs/REST/sitesサービスのチケットを取得します。

Ticket Granting Ticket を取得するためのコール

リクエスト

POST /cas/v1/tickets HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 35

username=fwadmin&password=xceladmin

レスポンス

HTTP/1.1 201 Created
Location: http://localhost:8080/cas/v1/tickets/TGT-1-ej2biTUFoCNBwA5X4lJn4PjYLRcLtLYg2QhLHclInfQqUk3au0-cas
Content-Length: 441
...

サービス・チケットを取得するためのコール

リクエスト

POST /cas/v1/tickets/TGT-1-ej2biTUFoCNBwA5X4lJn4PjYLRcLtLYg2QhLHclInfQqUk3au0-cas  HTTP/1.1
Content-Type: application/x-www-form-urlencoded 
Content-Length: 57

service=http%3A%2F%2Flocalhost%3A8080%2Fcs%2FREST%2Fsites

レスポンス

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 29

ST-1-7xsHEMYR9ZmKdyNuBz6W-cas

プロトコルは、非常に単純です。最初に、ユーザー名およびパスワード・パラメータをapplication/x-www-form-urlencoded POSTリクエストで渡すことで、Ticket Granting Ticket (TGT)を取得するためのコールを実行します。レスポンスにはLocation HTTPヘッダーが含まれます。これを使用して、serviceパラメータを指定する2番目のapplication/x-www-form-urlencoded POSTリクエストを発行します。レスポンス本文には実際のチケットが含まれます。

63.1.3 チケットおよびマルチチケットの使用

生成されたチケット/マルチチケット(図63-1)を使用するには、ticket/multiticket URL問合せパラメータを指定します。次に例を示します。

http://localhost:8080/cs/REST/sites?ticket=ST-1-7xsHEMYR9ZmKdyNuBz6W-cas
http://localhost:8080/cs/REST/sites?multiticket=ST-2-Bhen7VnZBERxXcepJZaV-cas

図63-1 チケットおよびマルチチケット

「図63-1 チケットおよびマルチチケット」の説明

アプリケーションが、チケット/マルチチケットを取得するためのコールを実行します。
- 入力: サービス、ユーザー名、パスワード
- 出力: チケット/マルチチケット
アプリケーションが、リソースを取得するためのコールをリモートSatellite Serverに対して実行します。
- 入力: チケット、リソース入力データ
- 出力: リソース出力データ
リモートSatellite Serverは、結果のアサーションを検証するためのコールを実行します。アサーションにはユーザー情報が含まれます。また、Satellite Serverはマルチチケットの時間ベースのキャッシュを保持しているため、後続のコールでは検証によるコストは発生しません。
- 入力: チケット/マルチチケット
- 出力: アサーション
この手順は省略可能です。Satellite Server側で、SSOConfig.xmlファイルのproxyTicketsパラメータがtrueに設定されている場合は、チケットのプロキシも行われます。
- 入力: チケット
- 出力: プロキシされたチケット
リモートSatellite Serverが、WebCenter Sitesに対してコールを実行します。
- 入力: アサーション(シリアライズ形式)、リソース入力データ
- 出力: リソース出力データ
この手順は省略可能です。WebCenter Sites側でセキュリティが有効な場合は、チケットを検証するためのコールが実行されます。
- 入力: チケット/マルチチケット
- 出力: アサーション

デフォルトでは、WebCenter SitesとリモートSatellite Server間の通信チャネルは信頼されていません。リモートSatellite ServerのSSOConfig.xmlファイルのproxyTicketsパラメータがtrueに設定されているため、アクセスしているアプリケーションで指定されたチケットが、リモートSatellite Serverによって強制的にプロキシされます。

最適なパフォーマンスを得るために、システムをSatellite Serverのみによって認証するように構成できます。REST APIによって使用されるRESTおよびWebCenter SitesエレメントをSSOフィルタから除外することにより、WebCenter Sites側でセキュリティ・チェックを無効にする必要があります。Satellite Server側で、SSOConfig.xmlファイルのproxyTicketsパラメータをfalseに設定する必要があります。このモードではマルチチケットを活用できます。このモードでは、WebCenter Sitesのインストールはプライベート・ネットワーク内でホストする必要があること、およびWebCenter SitesとリモートSatellite Server間の通信チャネルの信頼性を確保する必要があることに注意してください。

63.1.4 スタンドアロン・アプリケーションのSSO構成

シングル・サインオン・モジュールはSpring構成に基づいています。唯一必要なBeanはssoproviderで、これはssoconfig Beanを参照しています。

この項には次のトピックが含まれます:

63.1.4.1 Beanおよびプロパティ

表63-1では、ssolistener Beanおよびプロパティを説明します。

id="ssolistener", class="com.fatwire.wem.sso.cas.listener.CASListener"

表63-1 id="ssolistener"

プロパティ	説明
このBeanにはプロパティはありません。	該当なし

表63-2では、ssofilter Beanおよびプロパティを説明します。

id="ssofilter",
class="com.fatwire.wem.sso.cas.filter.CASFilter"

表63-2 id="ssofilter"

プロパティ説明

プロパティ	説明
`config`	必須。SSO構成参照です。サンプル値: `ssoconfig`
`provider`	必須。SSOプロバイダ参照です。サンプル値: `ssoprovider`

config

必須。SSO構成参照です。

サンプル値: ssoconfig

provider

必須。SSOプロバイダ参照です。

サンプル値: ssoprovider

表63-3では、provider Beanおよびプロパティを説明します。

id="provider",
class="com.fatwire.wem.sso.cas.CASProvider"

表63-3 id="provider"

プロパティ説明

プロパティ	説明
`config`	SSO構成参照です。サンプル値: `ssoconfig`

config

SSO構成参照です。

サンプル値: ssoconfig

表63-4では、config Beanおよびプロパティを説明します。

id="config",
class="com.fatwire.wem.sso.cas.conf.CASConfig"

表63-4 id="config"

プロパティ	説明
`applicationProxyCallbackPath`	プロキシ・コールバックのパス(`casUrl`からの相対パス)。サンプル値: `/proxycallback`
`authRedirect`	このプロパティは、保護されているページへの未認証アクセスに対するデフォルト動作を指定するために使用します。`true`を指定すると、ユーザーがCASログイン・ページにリダイレクトされます。`false`を指定すると、ユーザーが未認証の場合は403エラーが表示されます。この設定は、Pragma: auth-redirect HTTPヘッダーによってオーバーライドできます。サンプル値: `true`
`casLoginPath`	ログイン・ページのパス(`casUrl`からの相対パス)。次の追加の問合せパラメータを受け取ることができます。 `wemLoginTemplate`は、デフォルト・テンプレートのかわりに使用されるHTMLログイン・テンプレートを含むページを指します。このテンプレートには2つの入力フィールド(`username`および`password`)を含める必要があります。このテンプレートでは、HTML `<form>`タグは使用しないでください。 `wemLoginCss`。ログイン・フォームで使用されるスタイル宣言を含むCSSページを指します。サンプル値: `/login`
`casRESTPath`	CAS RESTサーブレットのパス(`casUrl`からの相対パス)。サンプル値: `/v1`
`casSignoutPath`	ログアウト・ページのパス(`casUrl`からの相対パス)。サンプル値: `/logout`
`casUrl`	必須プロパティ。CAS URLの接頭辞です。 URLは内部と外部の両方で解決する必要があります。例: `http://localhost:8080/cas`
`gateway`	`true`の場合、保護されているページへのリクエストはCASにリダイレクトされます。チケット発行Cookieが存在する場合は、ユーザーは暗黙的に認証されます。存在しない場合は、ユーザーは元の位置にリダイレクトされます。これは主に、ユーザーが別のアプリケーションにログインしている場合に、暗黙的な認証を許可するために使用されます。
`gateway` (続き)	デフォルトでリダイレクトの動作が行われるようにする場合は次の点に注意してください。クライアントがリダイレクトを追従できることを確認してください。そうでない場合は、`gateway=false` URL問合せパラメータを使用して、デフォルトの動作をオーバーライドする必要があります。たとえば、`wemLoginTemplate`および`wemLoginCss`パラメータの処理中は、CASがリダイレクトを追従しないため、この設定をオンにするときに、`gateway=false`をURLに付加する必要があります。デフォルト値: `false`
`multiticketTimeout`	マルチチケットのタイムアウト(ミリ秒単位)。デフォルト値: `600000`
`protectedMappingExcludes`	除外されるマッピングのリスト。正規表現を使用できます。許可値: `protectedMappingIncludes`を参照してください。
`protectedMappingIncludes`	保護されるマッピングのリスト。正規表現を使用できます。許可値: `path?[name=value,#]` pathはURLパスの一部です。アスタリスクを含めることができます(``および``)。単一のアスタリスク``は、スラッシュ(/)までの文字シーケンスを表し、*は、パス全体に適用されます。例 /folder1/folder2は/folder1/と一致しますが、/folder1/folder2/folder3は一致しません。 /folder1/folder2と/folder1/folder2/folder3は、/folder1/**と一致します。 `?[..]`ブロックはオプションです。問合せパラメータはブロック内で指定できます。パラメータはカンマで区切られます。特殊文字`#`は、指定されたパラメータがリクエストの内容のサブセットであることを意味しています。`#`を省略するには、指定されたパラメータに正確に一致するリクエスト・パラメータが必要です。パラメータには、`name`のみを含めることができます。照合は、`name`に対してのみ、または`name=value` (つまり、`name`と`value`の両方)に対して実行されます。パラメータには、複数の値を指定できます。この場合、指定したパラメータ値のいずれかが、対応するリクエストのパラメータ値と一致すると照合テストに合格します。例 `/file1[size=1\|2] matches against /file1?size=2, but not against /file1?size=2&author=admin` `/file1[size=1\|2,name=file1,#] matches against /file1?size=2 and /file1?size=2&author=admin,but not against /file1?size=3`
`protectedMappingIncludes` (続き)	リモートSatellite Serverを介してアプリケーションのカスタムRESTリソースを使用可能にするには、次の値を指定します。 `/ContentServer?[pagename=rest/<path toCSElement>,#]` 例「WebCenter SitesおよびSatellite Server用のRESTリソースの作成: 例」のカスタムRESTリソースに指定する場合は、`/ContentServer?[pagename=rest/sample/recommendation,#]`です。
`proxyTickets`	チケットをプロキシするかどうかを指定します。コール・チェーンの最後のサーバーに対してこのプロパティを`false`に設定すると、パフォーマンスが最適化されます。現在のログイン済ユーザーの代理としてこのアプリケーションからCASで保護された別のアプリケーションをコールする必要がある場合は、このプロパティを`true`に設定します。これにより、メソッド`SSO.getSSOSession().getTicket(String service, String username, String password)`をコールできるようになります。デフォルト値: `true`
`useMultiTickets`	マルチチケットを使用するかどうかを指定します。デフォルト値: `true`

63.1.4.2 SSOフィルタで処理される問合せパラメータ

表63-5で、SSOフィルタで処理される問合せパラメータについて説明します。

表63-5 SSOフィルタで処理される問合せパラメータ

プロパティ名	説明
`ticket`	ユーザーIDを検証するために使用します。あるかぎられた期間内で、1つのリソースに対して1回のみ使用できます。タイプ: `<query parameter>` 値: `<random string>`
`multiticket`	ユーザーIDを検証するために使用します。あるかぎられた期間内で、任意のリソースに対して複数回使用できます。タイプ: `<query parameter>` 値: `<random string>`
`gateway`	このプロパティが`true`に設定されている場合は、パブリック・ページのリクエストはCASにリダイレクトされます。チケット発行Cookieが存在する場合は、ユーザーは暗黙的に認証されます。存在しない場合は、ユーザーは元の位置にリダイレクトされます。これは主に、ユーザーが別のアプリケーションにログインしている場合に、暗黙的な認証を許可するためです。タイプ: `<query parameter>` 値: `true \| false`
`auth-redirect`	保護されているページへの未認証アクセスに対するデフォルトの動作を指定するために使用します。このプロパティが`true`に設定されている場合は、ユーザーはCASログイン・ページにリダイレクトされます。`false`に設定されている場合は、`403`エラーが表示されます。タイプ: `<Pragma HTTP header>` 値: `true \| false`

63.2 CASの構成について

CASクラスタリングに関する情報は、次のソースを参照してください。

CASアーキテクチャの詳細は、次のリンクを使用してください。

http://www.jasig.org/cas/about
WebCenter Sitesのインストール時にCASクラスタリングを構成する方法の詳細は、『Oracle WebCenter Sitesのインストールと構成』を参照してください。
LDAPプロバイダでCASを構成する方法の詳細は、次のリンクを使用してください。

http://www.jasig.org/cas/server-deployment/authentication-handler

63.3 REST認可

REST認可は、アプリケーションのリソース(WebCenter Sites内のオブジェクトにマップされる)に対してRESTの各操作を実行するための権限を付与するプロセスです。REST認可は、デフォルトではすべてを拒否するモデルを使用します。権限が特定のグループに対して明確に付与されていない場合、その権限は拒否されます。

この項には次のトピックが含まれます:

63.3.1 セキュリティ・モデル

WEMセキュリティ・モデルはオブジェクト、グループおよびアクションに基づいています。セキュリティは、図63-2に示すように、Adminインタフェースでオブジェクト・タイプごとに構成する必要があります。特定のタイプのオブジェクトにユーザーがアクセスできるのは、特定のタイプのオブジェクトに対して指定されたアクションを実行する権限を持つグループの少なくとも1つにこのユーザーが属する場合のみです。

図63-2 新規セキュリティ構成の追加

「図63-2 新規セキュリティ構成の追加」の説明

オブジェクトは、サイト、ユーザー、アセットなど、WEMフレームワーク内のエンティティを示す総称です。保護オブジェクトには次のタイプがあります。
- アセット・タイプ
- アセット
- 索引
- サイト
- ロール
- ユーザー
- ユーザー・ロケール
- ACL
- アプリケーション
セキュリティ・グループは、ユーザーを集約して、ユーザーの(オブジェクトへの操作)権限を同時に管理するために使用します。
アクションは、LIST、READ、UPDATE、CREATE、DELETEの各セキュリティ権限です。LISTはオブジェクトをリストするサービス(/typesなど)に対するGET権限を提供し、READは個々のオブジェクトの詳細を取得するサービス(/types/{assettype}など)に対するGET権限を提供します。

権限は、許可されたオブジェクトを操作するためにグループに割り当てられます。ACLなど一部のオブジェクトは読取り専用です(WebCenter Sitesで直接作成できますが、RESTを介して作成できません)。

前述のように、セキュリティ構成とは1つの配列です。セキュリティ構成では次を指定します。

保護されているオブジェクト・タイプおよびオブジェクト
オブジェクトにアクセス可能なグループ
グループ(およびそのメンバー)がオブジェクトに実行できるアクション

可能なセキュリティ構成およびWebエクスペリエンス管理フレームワークの詳細は、『Oracle WebCenter Sitesの管理』を参照してください。

63.3.2 RESTリソースへのセキュリティ・モデルを使用したアクセス

WebCenter Sites内のオブジェクト・タイプとオブジェクトは、WEMフレームワーク内のRESTリソースにマップされます。たとえば、Asset Typeオブジェクトは次のリソースにマップされます。

<BaseURI>/types/リソース(システム内のすべてのアセット・タイプを一覧表示します)
<BaseURI>/types/<assettype>リソース(選択されたアセット・タイプに関する情報を表示します)など。

WebCenter Sitesのアクションは、WEMフレームワークのRESTメソッドにマップされます。たとえば、アセット・タイプContent_Cを操作するためのREAD権限をグループEditorに付与すると、Editorグループのユーザーには、RESTリソース/types/Content_Cに対してGETおよびHEADメソッドを使用する権限が付与されます。

LISTアクションでは、グループ・メンバーがRESTリソースに対してGETメソッドを使用できます。
READアクションでは、グループ・メンバーがRESTリソースに対してGETおよびHEADメソッドを使用できます。
UPDATEアクションでは、グループ・メンバーがRESTリソースに対してPOSTメソッドを使用できます。
CREATEアクションでは、グループ・メンバーがRESTリソースに対してPUTメソッドを使用できます。
DELETEアクションでは、グループ・メンバーがRESTリソースに対してDELETEメソッドを使用できます。

詳細は、『Oracle WebCenter Sites REST APIリソース・リファレンス』を参照してください。

63.3.3 RESTセキュリティの構成について

RESTセキュリティの構成およびWebエクスペリエンス管理フレームワークの詳細は、『Oracle WebCenter Sitesの管理』を参照してください。

63.3.4 権限解決アルゴリズム

セキュリティ権限を構成する際に、特定のタイプのすべてのオブジェクトまたは特定のタイプの単一のオブジェクトに権限が適用されるように指定します。たとえば、任意のサイトに対するUPDATE (POST)権限を付与すると、グループ内のユーザーはすべてのサイトの詳細をWEMフレームワークで変更できるようになります。

Assetオブジェクト・タイプでは、セキュリティ設定の適用先サイトを指定する必要があります。アセットは、常に特定のサイトからアクセスされるからです。AssetTypeオブジェクトはサブタイプを指定することで拡張でき、セキュリティ構成をより詳細に設定するために使用されます。たとえば、アセット・タイプContent_CにDELETE権限を設定すると、RESTリソース/types/Content_CでのDELETEリクエストの実行(つまり、システムからContent_Cアセット・タイプを削除するための)が許可されます。

権限はグループにのみ付与できるため、ユーザーの全体的な権限は、そのユーザーの全グループを通じて権限が算出されるまで明確になりません。WEMフレームワークには、権限解決アルゴリズムが用意されています。その基本的な手順を次に示します。

RESTによって、ユーザーがメンバーシップを持つグループが検索されます。
RESTによって、各グループが実行できるREST操作およびその対象となるRESTリソースが判別されます。サイトまたはサブタイプが指定されている場合は、個々に考慮されます。
RESTによって、手順1および2の結果が比較されます。手順1の1つ以上のグループが、手順2のグループのリストで該当する場合、アクセスが許可されます。そうでない場合は、アクセスが拒否されます。

63.4 RESTを介したアセットの管理

WebCenter Sites REST APIを介したアセットの管理を示すサンプル・コードは、WebCenter Sitesのインストール・ディレクトリの次のパスにあります。

Misc/Samples/WEM Samples/REST API samples/Basic Assets/com/fatwire/rest/samples/basic/
Misc/Samples/WEM Samples/REST API samples/Basic Assets/com/fatwire/rest/samples/flex/

サブフォルダbasicおよびflexには、それぞれ次のファイルが含まれます。

CreateAsset.java
DeleteAsset.java
ReadAsset.java
UpdateAsset.java。

コードは、段階を追った説明によって詳細に文書化されています。