ユーザ＆プログラマ・ガイド¶
イントロダクション¶
PEP Proxy GE のユーザ＆プログラマ・ガイドへようこそ。PEP Proxy は、FIWARE GEs およびバックエンド・サービスに認証および認可フィルタを追加するためのセキュリティ・レイヤを提供します。これは、FIWARE Security Chapter の PEP （Police Enforcement Point） です。Identity Management とAuthorization PDP GEs とあわせて、FIWARE バックエンドにセキュリティを提供します。
注 : PEP Proxy GE はバックエンドコンポーネントであるため、この GE ではユーザ・ガイドを用意する必要はありません。
ユーザ・ガイド¶
PEP Proxy GE は、フロントエンド・インタフェースを持たないバックエンド・コンポーネントです。したがって、ユーザ・ガイドを用意する必要はありません。このコンポーネントが FIWARE アプリケーションのユーザの認証と認可をチェックすることを考慮してください。ユーザとアプリケーションを作成および管理し、ロールと権限を設定するには、Identity Management GE の Web インターフェイスを使用する必要があります。設定する方法を知るために、ユーザ・ガイドを確認してください。
基本的なユースケース¶
基本的な使用例は、フロントエンド・アプリケーションのユーザがバックエンド・アプリケーションのリソースにアクセスするシナリオです。また、FIWARE ユーザだけがそのリソースにアクセスできるようにしたいとします。この環境を設定する手順は次のとおりです :
- バックエンド・サービスの上に PEP Proxy を展開します。このサービスのエンドポイントは PEP Proxy のエンドポイントです。バックエンドを他のエンドポイントに変更する必要があります。これは、同じサーバにある可能性がありますが、他のポートにある可能性もあります。PEP Proxy は、リクエストをサービスにリダイレクトします
- IdM でアプリケーションを登録します
- OAuth2 ライブラリとアプリケーションの IdM で取得された資格情報を使用して、アプリケーションに OAuth2 メカニズムを実装します。したがって、ユーザは、自分の FIWARE accouts を使用してアプリケーションにログインすることができます
- ユーザがアプリケーションにログインすると、IdM はそのアプリケーションを表す OAuth2 トークンを生成します。この OAuth2 トークンを保存して、HTTPヘッダとして、バックエンド・サービスへのリクエストに含める必要があります
- バックエンド・サービスへのすべてのリクエストを、PEP Proxy がデプロイされているエンドポイントに送信する必要があります
- リクエストに含まれるトークンが有効な場合、PEP Proxy はリクエストをバックエンドにリダイレクトします。そうでない場合は、不正なコードでレスポンスします
プログラマ・ガイド¶
PEP Proxy GE は、バックエンド REST API の3つのレベルのセキュリティを実行するように設計されています。Proxy へのリクエストは特別な HTTP Header: X-Auth-Token で行う必要があります。このヘッダには、FIWARE IDM GE から取得した OAuth アクセストークンが含まれています。リクエストの例 :
GET / HTTP/1.1
Host: proxy_host
X-Auth-Token:z2zXk...ANOXvZrmvxvSgリクエストを検証してバックエンド・アプリケーションに転送するために、PEP Proxy は、管理者が設定したセキュリティ・レベルに応じて、Identity Managemen tおよび Authorization PDP GE に異なるパラメータをチェックします。使用可能なレベルは次のとおりです :
- レベル1 : Authentication PEP Proxy は、リクエストに含まれるトークンが FIWARE の認証されたユーザに対応するかどうかをチェックします
- レベル2 : Basic Authorization PEP Proxy は、リクエストに含まれるトークンが FIWARE の認証されたユーザに対応するかどうかをチェックしますが、ユーザがリクエストで指定されたリソースにアクセスできるようにしている場合はチェックします。これは、HTTP verb とパスに基づいています
- レベル3 : Advanced Authorization PEP Proxy は、リクエストに含まれるトークンが FIWARE の認証されたユーザに対応するかどうかをチェックしますが、リクエストの本文やヘッダなどのその他の高度なパラメータもチェックします
以下にこれらの3つのレベルとそれぞれを構成する方法を示します。
これらのリクエストを Identity Management および Authorization PDP GEs に行うには、PEP Proxy が Identity Management で認証される必要があります。資格情報は、設定ファイルのユーザ名とパスワードのフィールドで指定します。
レベル1 : Authentication (認証)¶
アプリケーションのフロントエンド部分 （Webアプリケーション） がバックエンド部分 （バックエンド・アプリケーション）に、REST リクエストを送信すると、ユーザの OAuth2 トークン （access_token） を含める必要があります。最初のステップは、FIWARE アカウントでユーザとアプリケーションを作成することです。進める方法を知るために、Identity Management のユーザ・ガイドを参照してください。
図1 : Authentication
図 1 に、この構成のアーキテクチャを示します。PEP Proxy はリクエストを受信すると、HTTP ヘッダ（X-Auth-Token） から access_token を抽出し、それを検証するために FIWARE アカウント・サーバ （Identity Management GE） にリクエストを送信します。サーバの URL は、設定ファイルの account_host フィールドに設定されます。
検証が成功した場合、PEP Proxy は configファイルの app_hos と app_port フィールドに設定されたバックエンド・サービスにリクエストをリダイレクトします。
Basic Authorization (基本認証)¶
まず、最初のステップでは、FIWARE アカウントにユーザとアプリケーションを作成することです。この場合、そのアプリケーションでそのユーザのロールとアクセス許可を構成する必要もあります。進める方法を知るために、Identity Management のユーザ・ガイドを参照してください。
図2 : Basic Authorization
図 2 に、この構成のアーキテクチャを示します。PEP Proxy は、リクエストに含まれる access_token が FIWARE アカウントの認証されたユーザに対応するかどうかをチェックします。検証が成功した場合、レスポンスにはそのアプリケーションのユーザ情報が含まれます。この情報には、ユーザがアプリケーションに持つロールのリストが含まれています。また、PEP Proxy は、ユーザがリクエストのリソースにアクセスする権限を持っている場合、Authorization PDP GE でチェックします。これは、HTTP verb とリクエストのパスを考慮に入れます。
この認証レベルを有効にするには、config ファイルの check_permissions オプションを true に設定、Authorization PDP GE URL を指定します。
Advanced Authorization (高度な承認)¶
まず、FIWARE アカウントにユーザとアプリケーションを作成します。次に、そのアプリケーションでそのユーザのロールと XACML ポリシーを構成します。進める方法を知るために、Identity Management のユーザガイドを参照してください。
図3 : Advanced Authorization
図 3 に、この構成のアーキテクチャを示します。この場合は、本文やカスタムヘッダなどのリクエストの高度なパラメータをチェックすると考えられるため、特定のユースケースに依存します。したがって、プログラマは特定の要件を含めるために PEP Proxy ソースコードを変更する必要があります。
所望のパラメータを用いて、XACML