FIWARE Banner

FIWARE Security License: MIT Support badge
Documentation

このチュートリアルでは、アプリケーションの作成方法と、ロールとパーミッションの割 り当て方法について説明します 。以前のチュートリアルで 作成したユーザと組織が必要であり、 正当なユーザだけがリソースにアクセスできるよ うにします。

このチュートリアルでは、Keyrock GUI を使用した対話の例や、Keyrock REST API へのアクセスに使用される cUrl コマンド 、Postman documentation も使用できます。

Run in Postman

認可とは何ですか?

"No matter what he does, every person on earth plays a central role in the history of the world. And normally he doesn't know it"

— Paulo Coelho (The Alchemist)

認可は、情報セキュリティに関連するリソースへのアクセス権/特権を指定する機能です 。より正式には、 "to authorize" (認可する) とはアクセス・ポリシーを定義すること です。FIWARE Keyrock Generic Enabler を介して ID 管理を制御すると、ロールに 割り当てられたパーミッションに基づいてユーザ・アクセスが許可されます。

Keyrock Generic Enabler によって保護されたすべてのアプリケーションは、一連の パーミッション、つまりアプリケーション内で実行可能な一連のパーミッションを定義で きます。たとえば、アプリケーション内で、スマートドアのロックを解除するためのコマ ンドを送信する機能は、Unlock Door パーミッションを得て保護することができます。 同様に、アラームを鳴らすためにコマンドを送る能力は Ring Bell パーミッションの 背後に確保され、価格を変更する能力は Price Change パーミッションの背後に確保さ れます。

これらのパーミッションは、一連のロールにグループ化されています。たとえば Unlock DoorRing Bell は、 両方ともセキュリティ・ロールに割り当てることが できます。後でそのロールが付与されたユーザは両方のパーミッションを取得することを 意味します。

パーミッションは重複して複数のロールに割り当てることができます。おそらく 、Ring Bell は、Price ChangeOrder Stock と一緒に管理ロールにも割り当て られます。

次に、ユーザまたは組織は 1 つ以上のロールに割り当てられます。各ユーザは、それぞ れのロールに対するすべてのパーミッションのすべてを取得します。たとえば、Alice は 、両方の管理とセキュリティのロールに割り当てられている場合、彼女は 、Unlock Door, Ring Bell, Price Change, Order Stock の 4 つのすべてのパ ーミッションを持ちます。

ロールの概念はユーザには分かりません。パーミッションがアプリケーション内でどのよ うに分割されるのではなく、付与 (grant) されているパーミッションの一覧のみがわか ります。

要約すると、パーミッションはアプリケーション内のリソースに対して実行可能なすべて のアクションですが、ロールはそのアプリケーションのユーザのタイプによって実行でき るアクションのグループです。

ID 管理の標準概念

Keyrock ID 管理データベースには、次の共通オブジェクトがあります :

  • User - 電子メールとパスワードを使用して自分自身を識別できる、登録済みの ユーザ。ユーザには、個別にまたはグループとして権利を割り当てることができます
  • Application - 一連のマイクロ・サービスで構成された任意のセキュアな FIWARE アプリケーション
  • Organization - 一連の権利を割り当てることができるユーザのグループ。組織 の権利を変更すると、その組織のすべてのユーザのアクセスが影響を受けます
  • OrganizationRole - ユーザは組織のメンバまたは管理者になることができます 。管理者は組織にユーザを追加または削除できます。メンバは組織のロールと権限を 取得するだけです。これにより、各組織はメンバに対して責任を持つことができ、ス ーパー管理者 (super-admin) がすべての権限を管理する必要がなくなります
  • Role - ロールは、一連のアクセス許可の説明的なバケットです。ロールは、単 一のユーザまたは組織に割り当てることができます。サインインしたユーザは、自分 のすべてのロールとその組織に関連付けられているすべてのロールのすべての権限を 取得します
  • Permission - システム内のリソース上で何かを行う能力

さらに、FIWARE アプリケーション内で、2 つの人以外のアプリケーション (non-human application) のオブジェクトを保護することができます。

  • IoTAgent - IoT センサとコンテキスト・ブローカー間のプロキシ
  • PEPProxy - ユーザの権利を確認する Generic Enabler 間での使用のためのミド ルウェア

オブジェクト間の関係は以下のようになります。赤でマークされたエンティティは、この チュートリアルで直接使用されています :

前提条件

Docker

Docker

物事を単純にするために、両方のコンポーネントが Docker を使用して実行されます。Docker は、さまざまコンポーネントをそれぞれの環境に 分離することを可能にするコンテナ・テクノロジです。

  • Docker Windows にインストールするには 、こちらの手順に従ってくださ い
  • Docker Mac にインストールするには 、こちらの手順に従ってください
  • Docker Linux にインストールするには 、こちらの手順に従ってください

Docker Compose は、マルチコンテナ Docker アプリケーションを定義して実行する ためのツールです 。YAML file ファイルは、アプリケーションのために必要なサービスを構成するために使用します。つ まり、すべてのコンテナ・サービスは 1 つのコマンドで呼び出すことができます 。Docker Compose は、デフォルトで Docker for Windows と Docker for Mac の一部と してインストールされますが、Linux ユーザ はここに記載されている手順に従う必要 があります。

Cygwin

シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは cygwin をダウンロードして、Windows 上の Linux ディスト リビューションと同様のコマンドライン機能を提供する必要があります。

アーキテクチャ

このイントロダクションでは 、Keyrock Identity Management Generic Enabler という 1 つの FIWARE コンポーネントのみを使用します。Keyrock 単独での使用は、アプリケーションが “Powered by FIWARE” と認定するには不十分で す。さらに、MySQL データベースにユーザ・データを保存する予定です。

全体的なアーキテクチャは、次の要素で構成されます :

  • 1 つの FIWARE Generic Enabler :

    • FIWARE Keyrock は補完的 な ID 管理システムを提供します :
      • アプリケーションとユーザのための認証システム
      • ID 管理のアドミニストレーションのための Web サイトのグラフィカル・フ ロントエンド
      • HTTP リクエストによる ID 管理用の同等の REST API
  • 1 つの MySQL データベース :

    • ユーザ ID、アプリケーション、ロール、およびパーミッションを保持するため に使用します

要素間のすべてのインタラクションは HTTP リクエストによって開始されるため、エンテ ィティはコンテナ化され、公開されたポートから実行されます。

チュートリアルの各セクションの具体的なアーキテクチャについては、以下で説明します 。

Keyrock の設定

keyrock:
    image: fiware/idm
    container_name: fiware-keyrock
    hostname: keyrock
    depends_on:
        - mysql-db
    ports:
        - "3005:3005"
        - "3443:3443"
    environment:
        - DEBUG=idm:*
        - DATABASE_HOST=mysql-db
        - IDM_DB_PASS_FILE=/run/secrets/my_secret_data
        - IDM_DB_USER=root
        - IDM_HOST=http://localhost:3005
        - IDM_PORT=3005
        - IDM_HTTPS_ENABLED=true
        - IDM_HTTPS_PORT=3443
        - IDM_ADMIN_USER=alice
        - IDM_ADMIN_EMAIL=alice-the-admin@test.com
        - IDM_ADMIN_PASS=test
    secrets:
        - my_secret_data

keyrock コンテナは、2 つのポートでリッスンしている、Web アプリケーション・サー バです :

  • Port 3005 は HTTP トラフィックで公開されているため、Web ページを表示して REST API とやりとりすることができます。
  • Port 3443 は Web サイトおよび REST API の HTTPS トラフィックを保護するため に公開されています

すべてのセキュアなアプリケーションで HTTPS を使用 する必要がありますが、これを正しく行うには Keyrock には信頼できる SSL 証 明書が必要です。デフォルトの証明書は自己認証されており、テスト目的で利用できま す。 証明書は、/opt/fiware-idm/certs の下にあるファイルを置き換えるためにボ リュームを付加することで上書きすることができます。

実稼働環境では、プレーンテキストを使用して機密情報を送信しないように、HTTPS 経 由ですべてのアクセスを行う必要があります。 また、設定された HTTPS リバース・プ ロキシの背後にあるプライベート・ネットワーク内で HTTP を使用することもできます 。

HTTP プロトコルを提供するポート 3005 は、デモンストレーションの目的でのみ公 開されており、このチュートリアルでのインタラクションを簡素化するために、ポート 3443 で HTTPS を使用することもあります。

Postman を使用しているときに HTTPS を使用して REST API にアクセスする場合は 、SSL 証明書の検証がオフであることを確認してください。HTTPS を使用して Web フ ロントエンドにアクセスする場合は、発行されたセキュリティ警告を受け入れてくださ い。

keyrock コンテナは、次に示す環境変数によってドライブされます :

キー 説明
IDM_DB_PASS idm 接続する MySQL データベースのパスワード。Docker Secrets によって保護されています。下記を参照してください
IDM_DB_USER root デフォルトの MySQL ユーザのユーザ名。プレーン・テキストです
IDM_HOST http://localhost:3005 Keyrock アプリケーション・サーバのホスト名。ユーザ登録時にアクティベーション e-mail で使用されます
IDM_PORT 3005 Keyrock アプリケーション・サーバで使用される HTTP トラフィックのためのポート。これは、衝突を避けるためにデフォルトの 3000 ポートから変更しています
IDM_HTTPS_ENABLED true HTTPS サポートを提供するかどうか。これは、オーバーライドされない限り、自己署名証明書を使用します
IDM_HTTPS_PORT 3443 HTTP トラフィック用の Keyrock アプリケーション・サーバで使用されるポート。デフォルトの 443 から変更されています。

この例では、Docker Secrets を使用して MySQL パ スワードを保護していることに注意してください。_FILE サフィックスを持つ IDM_DB_PASS を使用し、シークレット・ファイルの場所を参照します。これによりプ レーン・テキストの ENV 変数として、パスワードを公開することを避けることがで きます。Dockerfile イメージか docker inspect を使って読むことができる注入 変数 (an injected variable ) です。

次の変数のリストは、プロダクション・システムで _FILE サフィックスを持つシー クレットを使用して設定する必要があります :

  • IDM_SESSION_SECRET
  • IDM_ENCRYPTION_KEY
  • IDM_DB_PASS
  • IDM_DB_USER
  • IDM_ADMIN_ID
  • IDM_ADMIN_USER
  • IDM_ADMIN_EMAIL
  • IDM_ADMIN_PASS
  • IDM_EX_AUTH_DB_USER
  • IDM_EX_AUTH_DB_PASS

MySQL の設定

mysql-db:
    image: mysql:5.7
    hostname: mysql-db
    container_name: db-mysql
    expose:
        - "3306"
    ports:
        - "3306:3306"
    networks:
        ? default
    environment:
        - "MYSQL_ROOT_PASSWORD_FILE=/run/secrets/my_secret_data"
        - "MYSQL_ROOT_HOST=172.18.1.5"
    volumes:
        - mysql-db:/var/lib/mysql
    secrets:
        - my_secret_data

MySQL の設定

mysql-db コンテナは、単一ポートで待機しています :

  • Port 3306 は MySQL サーバのデフォルト・ポートです。これは公開されているの で、必要に応じて他のデータベース・ツールを実行してデータを表示することもでき ます

mysql-db コンテナは、次に示すような環境変数によってドライブされます :

キー 説明
MYSQL_ROOT_PASSWORD 123 Docker Secrets によって保護されている MySQL の root アカウントに設定されているパスワードを指定します。下記を参照してください
MYSQL_ROOT_HOST root デフォルトでは、MySQL は root'@'localhost アカウントを作成します。このアカウントはコンテナ内からのみ接続できます。この環境変数を設定すると、他のホストからのルート接続が可能になります。

起動

インストールを開始するには、次の手順を実行します :

git clone git@github.com:FIWARE/tutorials.Roles-Permissions.git
cd tutorials.Roles-Permissions

./services create

Docker イメージの最初の作成には最大 3 分かかります

その後、リポジトリ内で提供される services Bash スクリプトを実行することによって、コマンドラインからすべてのサービスを初期 化することができます :

./services <command>

ここで、<command> は、私たちがアクティベートしたいエクササイズに応じてかわりま す。

注: クリーンアップをやり直したい場合は、次のコマンド を使用して再起動することができます :

./services stop

登場人物 (Dramatis Personae)

次の test.com のメンバは、アプリケーション内に正当なアカウントを持っています。

  • Alice, 彼女は Keyrock アプリケーションの管理者になります
  • Bod, スーパー・マーケット・チェーンの地域マネージャ。彼の下に数人のマネージ ャがいます :
    • Manager1
    • Manager2
  • Charlie, スーパー・マーケット・チェーンのセキュリティ責任者。彼の下に数人の 警備員がいます。
    • Detective1
    • Detective2

次の example.com のメンバーはアカウントに登録しましたが、アクセスを許可する理 由はありません。

  • Eve - 盗聴者のイブ
  • Mallory - 悪意のある攻撃者のマロリー
  • Rob - 強盗のロブ

2 つの組織が Alice によって設定されました :

名前 説明 UUID
Security 店員のためのセキュリティ・グループ security-team-0000-0000-000000000000
Management ストア・マネージャのための管理グループ managers-team-0000-0000-000000000000

時間を節約するために 、以前のチュートリアルか らユーザと組織を作成するデータがダウンロードされ、起動時に自動的に MySQL データ ベースに保存されるため、UUIDs が変更されず、データを再入力する必要もありません。

ユーザと組織を作成する方法についてのあなたの記憶をリフレッシュするには、アカウン ト alice-the-admin@test.com を使用して、パスワード testhttp://localhost:3005/idm にログインできます。

組織のリストを見てください。

Keyrock MySQL データベースからの直接読み込み

すべての ID 管理のレコードと関連性は、MySQL データベース内に保持されます。以下の ように実行中の Docker コンテナを入力するとアクセスできます :

docker exec -it db-mysql bash
mysql -u <user> -p<password> idm

ここで、<user><password> は、docker-compose ファイル内で定義された値の MYSQL_ROOT_PASSWORDMYSQL_ROOT_USER に一致します。チュートリアルのデフォ ルト値は、通常 root、および secret です。

コマンドラインから SQL コマンドを入力することができます。例えば :

select id, username, email, password from user;

Keyrock MySQL データベースは、ユーザ、パスワードなどの格納を含むアプリケーシ ョン・セキュリティのあらゆる側面を扱います。アクセス権を定義し、OAuth2 認証プロ トコルを扱います。完全なデータベース関係図 はここに あります。

Keyrock 内の UUIDs

Keyrock 内のすべての IDs とトークンは変更される可能性があります。レコードを クエリするときは、以下の値を修正する必要があります。レコード IDs は Universally Unique Identifiers - UUIDs を使用します。

キー 説明 サンプル値
keyrock Keyrock サービスの場所の URL HTTP 用 localhost:3005, HTTPS 用localhost:3443
X-Auth-token ユーザとしてログインするときにヘッダで受け取ったトークン aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa = I am Alice
X-Subject-token サブジェクトについて問い合わせるときに渡すトークンで、代替はユーザ・トークンを繰り返ためのものです bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb = Asking about Bob
user-id user テーブルで見つかった既存ユーザの id bbbbbbbb-good-0000-0000-000000000000 - Bob's User Id
application-id oauth_client テーブルで見つかった、既存アプリケーションの id c978218d-ad63-4427-b12b-542b81299cfb
role-id role テーブルで見つかった、既存ロールの id d28baa00-839e-4b45-a6b2-1cec563942ee
permission-id permission テーブルで見つかった、既存パーミッションの id 6b6cd19c-9398-4834-9ba1-1616c57139c0
organization-id organization テーブルで見つかった、既存組織の id e424ed98-c966-46e3-b161-a165fd31bc01
organization-role-id owner または member のいずれかの組織内でユーザが持つロールのタイプ member
iot-agent-id iot テーブルで見つかった、既存 IoT Agent の id iot_sensor_f3d0245b-3330-4e64-a513-81bf4b0dae64
pep-proxy-id pep_proxy テーブルで見つかった、既存 PEP Proxy の id iot_sensor_f3d0245b-3330-4e64-a513-81bf4b0dae64

トークンは、一定期間後に期限切れになるように設計されています。使用している X-Auth-token 値の有効期限が切れている場合は、再度ログインして新しいトークンを 取得してください。このチュートリアルでは、ユーザごとに長く持続する一連のトークン が作成され、データベースに保存されるため、通常はトークンを更新する必要はありませ ん。

REST API 呼び出しによるログイン

アプリケーションに入るには、ユーザ名とパスワードを入力します。デフォルトのスーパ ー・ユーザ (super-user) は、alice-the-admin@test.comtest の値を持ってい ます。URL https://localhost:3443/v1/auth/tokens はセキュアなシステムでも動作す るはずです。

パスワードでトークンを作成

次の例では、Admin Super-User を使用してログインします :

1 リクエスト :

curl -iX POST \
  'http://localhost:3005/v1/auth/tokens' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "alice-the-admin@test.com",
  "password": "test"
}'

レスポンス :

HTTP/1.1 201 Created
X-Subject-Token: d848eb12-889f-433b-9811-6a4fbf0b86ca
Content-Type: application/json; charset=utf-8
Content-Length: 138
ETag: W/"8a-TVwlWNKBsa7cskJw55uE/wZl6L8"
Date: Mon, 30 Jul 2018 12:07:54 GMT
Connection: keep-alive
{
    "token": {
        "methods": ["password"],
        "expires_at": "2018-07-30T13:02:37.116Z"
    },
    "idm_authorization_config": {
        "level": "basic",
        "authzforce": false
    }
}

トークン情報を取得

このチュートリアルでは、長く持続する X-Auth-token=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa を使用して、Alice のふりをす ることができます。

時間制限されたトークンがあれば、ユーザに関する詳細情報を見つけることができます 。Bob に関する情報を検索するには、長く持続するトークン X-Subject-token=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb を使用します。

このリクエストは、トークン {{X-Auth-token}} で認可されたユーザ (Alice) は、ト ークン {{X-Subject-token}} を保持しているユーザ (Bob) について問い合わせている ことを示します。

2 リクエスト :

curl -iX GET \
  'http://localhost:3005/v1/auth/tokens' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' \
  -H 'X-Subject-token: bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'

レスポンス :

レスポンスは、関連するユーザの詳細を返します。Bob は 2026 年まで持続するトークン を保持していることがわかります。

{
    "access_token":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "expires":"2026-07-30T12:38:13.000Z",
    "valid":true,
    "User":{
        "id":"bbbbbbbb-good-0000-0000-000000000000",
        "username":"bob",
        "email":"bob-the-manager@test.com",
        "date_password":"2018-07-30T11:41:14.000Z",
        "enabled":true,
        "admin":false
    }

アプリケーションの管理

どの FIWARE アプリケーションも、マイクロサービスの集合体に分解することができます 。これらのマイクロサービスは、実際の世界の状態を読み取り、変更するために一緒に接 続します。これらのサービスに対するセキュリティは、これらのリソースに対するアクシ ョンを適切なパーミッションを持つユーザに制限することによって追加できます。したが って、許可されたアクションのセットを提供し、許可されたユーザ、またはユーザのグル ープ、すなわち組織のリストを保持するために、アプリケーションを定義する必要があり ます。

したがって、アプリケーションは、どのリソース上で何ができるのかを把握する概念的な バケツ (a conceptual bucket) です。

ビデオ : Keyrock GUI を使用したアプリケーションの作成

リンクをクリックすると 、Keyrock GUI を使用してアプリケーションを作成する方法を 示すビデオを見ることができます。

アプリケーションの CRUD アクション

標準の CRUD アクションは、/v1/applications エンドポイントの下の適切な HTTP 動 詞 (POST, GET, PATCH および DELETE) に割り当てられます。

アプリケーションを作成

ログインすると、ユーザにはホーム・スクリーンが提示されます。

GUI のホームページから、Register ボタンをクリックすると新しいアプリケーショ ンを作成できます。

REST API を使用して新しいアプリケーションを作成するには、保護する Web サービスの url などの OAuth 情報フィールド、および redirect_uri などとnamedescription などのアプリケーションの詳細を含む POST リクエストを /v1/applications エンドポイントに送信します。ここでユーザはその資格情報の正当 性をチェックされます。grant_types は 、後続のチュートリアル で 議論する、OAuth2 グラント・フローの利用可能なリストから選択されます。ヘッダには 、以前にログインしたユーザの X-Auth-token が含まれており、アプリケーション上で プロバイダのロールが自動的に付与されます。

3 リクエスト :

以下の例では、X-Auth-token=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa を持つ Alice は、3 つの異なるグラント・タイプ を受け入れる新しいアプリケーションを作成してい ます。

curl -iX POST \
  'http://localhost:3005/v1/applications' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' \
  -d '{
  "application": {
    "name": "Tutorial Application",
    "description": "FIWARE Application protected by OAuth2 and Keyrock",
    "redirect_uri": "http://tutorial/login",
    "url": "http://tutorial",
    "grant_type": [
      "authorization_code",
      "implicit",
      "password"
    ],
    "token_types": ["permanent"]
  }
}'

レスポンス :

レスポンスには、アプリケーションを保護するために使用できるクライアント Id と Secret が含まれています。

{
    "application": {
        "id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482",
        "secret": "aa2d0845-0a8e-4ae8-addf-3c87bcab19e1",
        "image": "default",
        "name": "Tutorial Application",
        "description": "FIWARE Application protected by OAuth2 and Keyrock",
        "redirect_uri": "http://tutorial/login",
        "url": "http://tutorial",
        "grant_type": "password,authorization_code,implicit",
        "response_type": "code,token"
    }
}

他のすべてのアプリケーションのリクエストに使用するアプリケーションの クライアン ト id をコピーします。上記の場合、id は 3782c5e3-88f9-481a-9b3c-2f2d6f604482 です。

アプリケーションの詳細を取得

/v1/applications/{{application-id}} エンドポイントの下のリソースに GET リクエ ストを行うと、その id の下にリストされているアプリケーションが返されます 。X-Auth-token がヘッダに必要です。

4 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

{
    "application": {
        "id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482",
        "name": "Tutorial Application",
        "description": "FIWARE Application protected by OAuth2 and Keyrock",
        "secret": "aa2d0845-0a8e-4ae8-addf-3c87bcab19e1",
        "url": "http://tutorial",
        "redirect_uri": "http://tutorial/login",
        "image": "default",
        "grant_type": "password,authorization_code,implicit",
        "response_type": "code,token",
        "client_type": null,
        "scope": null,
        "extra": null
    }
}

すべてのアプリケーションのリストを取得

ユーザは、関連付けられているアプリケーションのみを返すことが許可されます。アプリ ケーションをリストアップするには、/v1/applications エンドポイントへ X-Auth-token ヘッダを付けて、GET リクエストを行います。

5 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

{
    "applications": [
        {
            "id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482",
            "name": "Tutorial Application",
            "description": "FIWARE Application protected by OAuth2 and Keyrock",
            "image": "default",
            "url": "http://tutorial",
            "redirect_uri": "http://tutorial/login",
            "grant_type": "password,authorization_code,implicit",
            "response_type": "code,token",
            "client_type": null
        }
    ]
}

アプリケーションを更新

GUI 内では、アプリケーションを選択して、edit をクリックすることでユーザを更新 できます。これは、アプリケーション id がわかっているときに /v1/applications/{{applications-id}} エンドポイントに PATCH リクエストを出すこ とによって、コマンド・ラインから行うこともできます。ユーザは自身に関連付けられて いるアプリケーションを編集することができますので、X-Auth-token ヘッダも設定す る必要があります。

6 リクエスト :

curl -X PATCH \
  'http://localhost:3005/v1/applications/{{application-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}' \
  -d '{
  "application": {
    "name": "Tutorial New Name",
    "description": "This is a new description",
    "redirect_uri": "http://tutorial/login",
    "grant_type": [
      "authorization_code",
      "password"
    ]
  }
}'

レスポンス :

レスポンスには更新されたフィールドがリストされていますが、上で定義した redirect_uri が既に設定されていることに注意してください :

{
    "values_updated": {
        "name": "Tutorial New Name",
        "description": "This is a new description",
        "grant_type": "password,authorization_code",
        "response_type": "code"
    }
}

アプリケーションを削除

GUI 内で、ユーザはアプリケーションを選択して、edit をクリックしてからページの 一番下までスクロールし、Remove Application を選択することで、アプリケーショ ンを削除できます。これは、コマンド・ラインから 、/v1/applications/<applications-id> エンドポイントに DELETE リクエストを送信 することによっても実行できます。X-Auth-token ヘッダが、設定されなければなりま せん。

7 リクエスト :

curl -iX DELETE \
  'http://localhost:3005/v1/applications/{{applications-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

パーミッションの CRUD アクション

アプリケーションのパーミッションは、そのアプリケーション内のリソースに対して許可 されるアクションです。各リソースは URL (たとえば /price-change) で定義され、アク ションは任意の HTTP 動詞 (たとえば GET) です。

  • この組み合わせは、許可されたユーザのみが /price-change リソースにアクセス できるようにするために使用されます

XACML を使用してさらに高度なパーミッション・ルールを記述することができます。これ は別のチュートリアルの主題です。

パーミッションは常にアプリケーションにバインドされていることが強調されています。 抽象的なパーミッションはそれ自身では存在しません。標準パーミッションの CRUD アク ションは、/v1/applications/{{application-id}}/permissions エンドポイントの下の 適切な HTTP 動詞 (POST, GET, PATCH および DELETE) に割り当てられます。

  • ご覧のように、<application-id> 自体は URL に不可欠です

パーミッションは、通常、一度定義され、アプリケーションの作成時に設定されます。ユ ース・ケースの設計が、パーミッションを定期的に変更する必要があると判明した場合、 その定義は間違った層で定義されている可能性があります。複雑なアクセス制御規則を XACML 定義に落とし込むか、アプリケーションのビジネス・ロジックに移動するべきです 。 それらは、Keyrock 内で扱うべきではありません。

パーミッションを作成

GUI 内では、アプリケーションを選択し、Manage Roles をクリックし て、パーミッ ションのラベルの横にあるプラス記号を押すことで、アプリケーションにパーミッション を追加できます。

ウィザードに記入し、Save をクリックします。

REST API 経由で新しいパーミッションを作成するには、以前にログインしたユーザの X-Auth-token ヘッダとともに、アクションとリソースを含む /applications/{{application-id}}/permissions エンドポイントに POST リクエスト を送信します。

8 リクエスト :

curl -iX POST \
  'http://localhost:3005/v1/applications/{{application-id}}/permissions' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}' \
  -d '{
  "permission": {
    "name": "Access Price Changes",
    "action": "GET",
    "resource": "/price-change"
  }
}'

レスポンス :

レスポンスは、新しく作成されたパーミッションの詳細を返します。

{
    "permission": {
        "id": "c8ace792-d058-4650-9958-59753215e1cc",
        "is_internal": false,
        "name": "Access Price Changes",
        "action": "GET",
        "resource": "/price-change",
        "oauth_client_id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482"
    }
}

パーミッションの詳細を取得

/applications/{{application-id}}/permissions/{{permission-id}} エンドポイント は、その id の下にリストされているパーミッションを返します。X-Auth-token をヘ ッダに指定しなければなりません。

9 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/permissions/{{permission-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスは、リクエストされたパーミッションの詳細を返します。

{
    "permission": {
        "id": "c21983d5-58f9-4bcc-b2b0-f21819080ad0",
        "name": "Enable Alarm Bell",
        "description": null,
        "is_internal": false,
        "action": "POST",
        "resource": "/ring",
        "xml": null,
        "oauth_client_id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482"
    }
}

パーミッションをリストを取得

/v1/applications/{{application-id}}/permissions エンドポイントへの GET リクエ ストを行うことで、アプリケーションのパーミッションのリストを取得することができま す。

19 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/permissions' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

パーミッションの完全なリストには、以前に作成されたカスタム・パーミッションとデフ ォルトで使用可能なすべての標準パーミッションが含まれます。

{
    "permissions": [
        {
            "id": "c8ace792-d058-4650-9958-59753215e1cc",
            "name": "Access Price Changes",
            "description": null,
            "action": "GET",
            "resource": "/price-change",
            "xml": null
        },
        {
            "id": "c21983d5-58f9-4bcc-b2b0-f21819080ad0",
            "name": "Enable Alarm Bell",
            "description": null,
            "action": "POST",
            "resource": "/ring",
            "xml": null
        },
        ...etc
        {
            "id": "2",
            "name": "Manage the application",
            "description": null,
            "action": null,
            "resource": null,
            "xml": null
        },
        {
            "id": "1",
            "name": "Get and assign all internal application roles",
            "description": null,
            "action": null,
            "resource": null,
            "xml": null
        }
    ]
}

パーミッションを更新

既存のパーミッションの詳細を修正するには、PATCH リクエストを /applications/{{application-id}}/permissions/{permission-id}} エンドポイントに 送信します。

11 リクエスト :

curl -X PATCH \
  'http://localhost:3005/v1/applications/{{application-id}}/permissions/{{permission-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}' \
  -d '{
  "permission": {
    "name": "Ring Alarm Bell",
    "action": "POST",
    "resource": "/ring"
  }
}'

レスポンス :

レスポンスには、修正されたフィールドのリストが含まれています。

{
    "values_updated": {
        "name": "Ring Alarm Bell"
    }
}

パーミッションを削除

アプリケーションからパーミッションを削除すると、関連するロールからそのパーミッシ ョンが自動的に削除されます。

12 リクエスト :

curl -X DELETE \
  'http://keyrock/v1/applications/{{application_id}}/permissions/{{permission_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

ロールの CRUD アクション

上記のように、パーミッションはリソースに対する許容されるアクションです。ロールは 、パーミッションのグループ、言い換えればリソースのグループに対する一連の許可され たアクションで構成されます。ロールは通常、幅広い範囲の説明が与えられているため、 幅広いユーザまたは組織に割り当てることができます。たとえば、Reader ロールは一 連のデバイスにアクセスできますが、更新できません。

Keyrock には、あらかじめ定義された 2 つのロールがあります。

  • Purchaser
    • すべての公開アプリケーションのロールを取得し割り当てることができます
  • Provider
    • 公開の所有ロールのみを取得して割り当てることができます
    • すべての公開アプリケーションのロールを取得して割り当てることができます
    • 認可を管理することができます
    • ロールを管理することができます
    • アプリケーションを管理することができます
    • すべての内部アプリケーションのロールを取得して割り当てることができます

私たちのスーパー・マーケット・ストアの例を使用すると、管理者 Alice には 、Provider のロールが割り当てられ、管理やセキュリティのような、必要とされるア プリケーション固有の追加のロールを作成できます。

再び、ロールは常にアプリケーションに直接バインドされます。抽象的なロールはそれ自 身では存在しません。標準の CRUD アクションは 、/v1/applications/{{application-id}}/roles エンドポイントの下の適切な HTTP 動 詞 (POST, GET, PATCH および DELETE) に割り当てられます。

ロールを作成

GUI 内で、アプリケーションを選択し、Manage Roles をクリックし て、Role ラベ ルの隣にあるプラス記号を押すことで、ロールをアプリケーションに追加できます。

ウィザードに記入し、Save をクリックします。

REST API を介して新しいロールを作成するには、以前にログインしたユーザの X-Auth-token ヘッダと新しいロールの name を含む POST リクエストを /applications/{{application-id}}/roles エンドポイントに送信します。

13 リクエスト :

curl -X POST \
  'http://localhost:3005/v1/applications/{{application-id}}/roles' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}' \
  -d '{
  "role": {
    "name": "Management"
  }
}'

レスポンス :

作成されたロールの詳細が返されます。

{
    "role": {
        "id": "bc64fe78-f440-4ce0-815d-78b1d3d8b9a1",
        "is_internal": false,
        "name": "Management",
        "oauth_client_id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482"
    }
}

ロールの詳細を取得

/applications/{{application-id}}/roles/{{role-id}} エンドポイントは、その id の下にリストされているロールを返します。X-Auth-token をヘッダに指定しなければ なりません。

14 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/roles/{{role-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスは、リクエストされたロールの詳細を返します。

{
    "role": {
        "id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c",
        "name": "Security",
        "is_internal": false,
        "oauth_client_id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482"
    }
}

ロールのリストを取得

アプリケーションが提供するすべてのロールをリストするには 、/v1/applications/{{application-id}}/roles エンドポイントに GET リクエストを 行います。

15 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/roles' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

標準 ロールとカスタム・ロールの両方を含むアプリケーションに関連付けられたすべて のロールの概要が返されます。

{
    "roles": [
        {
            "id": "purchaser",
            "name": "Purchaser"
        },
        {
            "id": "provider",
            "name": "Provider"
        },
        {
            "id": "bc64fe78-f440-4ce0-815d-78b1d3d8b9a1",
            "name": "Management"
        },
        {
            "id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c",
            "name": "Security"
        }
    ]
}

ロールを更新

/applications/{{application-id}}/roles/{{role-id}} エンドポイントに PATCH リク エストを送信することで、ロールの名前を修正することができます。

16 リクエスト :

curl -iX PATCH \
  'http://localhost:3005/v1/applications/{{application-id}}/roles/{{role-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}' \
  -d '{
  "role": {
    "name": "Security Team"
  }
}'

レスポンス :

レスポンスには、修正されたフィールドのリストが含まれています。

{
    "values_updated": {
        "name": "Security Team"
    }
}

ロールを削除

アプリケーションのロールも削除することができます。これにより、どのユーザからもロ ールが削除されます。

17 リクエスト :

curl -iX DELETE \
  'http://localhost:3005/v1/applications/{{application-id}}/roles/{{role-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

各ロールへのパーミッションの割り当て

一連のアプリケーションのパーミッションと一連のアプリケーションのロールを作成した ら、次にロールに関連するパーミッションを割り当てます。つまり、Who can do What (誰が何をすることができる) を定義します。

ロールにパーミッションを追加

GUI 内で、ロールを選択し、保存する前にリストからパーミッションを確認します。

REST API を使用してアクセス許可を追加するために、次に示されるように、URL パスに <application-id>, <role-id>, <permission-id> を含め、ヘッダに X-Auth-Token を使用して自身を識別する、PUT リクエストを行います。

18 リクエスト :

curl -iX PUT \
  'http://localhost:3005/v1/applications/{{application-id}}/roles/{{role-id}}/permissions/{{permission-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスはロールのパーミッションを返します。

{
    "role_permission_assignments": {
        "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c",
        "permission_id": "c21983d5-58f9-4bcc-b2b0-f21819080ad0"
    }
}

ロールのパーミッションのリストを取得

アプリケーションのロールに割り当てられたすべてのパーミッションの完全なリストは 、/v1/applications/{{application-id}}/roles/{{role-id}}/permissions エンドポイ ントに GET リクエストを行うことで取得できます。

19 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/roles/{{role-id}}/permissions' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

{
    "role_permission_assignments": [
        {
            "id": "c21983d5-58f9-4bcc-b2b0-f21819080ad0",
            "is_internal": false,
            "name": "Ring Alarm Bell",
            "description": null,
            "action": "POST",
            "resource": "/ring",
            "xml": null
        },
        {
            "id": "2d611223-0b9e-4ffb-83b4-518e236890b6",
            "is_internal": false,
            "name": "Unlock",
            "description": "Unlock main entrance",
            "action": "POST",
            "resource": "/door/unlock",
            "xml": null
        }
    ]
}

ロールからパーミッションを削除

REST API を使用してパーミッションを削除するには、URL パスに <application-id>, <role-id><permission-id> を含め、ヘッダに X-Auth-Token を使用して自身 を識別する、 DELETE リクエストを行います。

29 リクエスト :

curl -X DELETE \
  'http://keyrock/v1/applications/{{application_id}}/roles/{{role_id}}/permissions/{{permission_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

アプリケーションのアクセスを認可

最後に、ユーザはアプリケーションにログインし、自分自身を識別し、ユーザが実行でき るパーミッションのリストを与えられます。ただし、パーミッションを保持し提供するユ ーザではなく、アプリケーションであることを強調する必要があります。ユーザは、付与 されたロールを介して集約されたパーミッションのリストに関連付けられているだけです 。

アプリケーションは、ユーザまたは組織のいずれかにロールを付与することができます。 組織の所有者は、ユーザのメンテナンスの責任をより広いグループに委任することができ るため、後者の方が常に望ましいはずです。

たとえば、スーパー・マーケットが別の店の警備員を得たとします。Alice は既に Security と呼ばれるロールを作成し、それをセキュリティ・チームに割り当てました 。Charlie はセキュリティ・チームの組織の所有者であり、新しい detective3 ユーザ をチームに追加することができます。detective3 は、アリスからのさらなる入力なし にチームのすべての権利を継承することができます。

個々のユーザにロールを付与する場合は、特別な場合に限定する必要があります。一部の ロールは非常に専門的で、メンバーを 1 人しか含まないため、組織を作成する必要はあ りません。これにより、アプリケーションを設定する際の管理上の負担は軽減されました が、他の変更 (アクセス権の削除など) は Alice 自身によって行われる必要があります 。委任はできません。

組織を認可

ロールは、アプリケーション自体の内部ですでに定義されていない限り、組織に付与する ことはできません。以前のチュートリアルで説明したように、組織を作成する必要があり ます。

組織にロールを付与

ロールは、アプリケーション自体の内部ですでに定義されていない限り、組織に付与する ことはできません。以前のチュートリアルで説明したように、組織を作成する必要があり ます。

ロールは、組織の members または owners のいずれかに付与することができます 。REST API を使用すると、次に示すように、URL パスに <application-id>, <organzation-id><role-id> を含め、ヘッダに X-Auth-Token を使用して自身 を識別する、 PUT リクエストを行うことで、ロールを付与することができます。

21 リクエスト :

この例では、組織のすべてのメンバにロールを追加します。

curl -X PUT \
  'http://localhost:3005/v1/applications/{{application-id}}/organizations/{{organization-id}}/roles/{{role-id}}/organization_roles/member' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスには、次のようなロールの割り当てが表示されます :

{
    "role_organization_assignments": {
        "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c",
        "organization_id": "security-team-0000-0000-000000000000",
        "oauth_client_id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482",
        "role_organization": "member"
    }
}

付与された組織ロールのリストを取得

組織に付与されたロールの完全なリストは 、/v1/applications/{{application-id}}/organizations/{{organization-id}}/roles エンドポイントに GET リクエストを行うことで取得できます。

22 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/organizations/{{organization-id}}/roles' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスには、組織に割り当てられたすべてのロールが表示されます。

{
    "role_organization_assignments": [
        {
            "organization_id": "security-team-0000-0000-000000000000",
            "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c"
        }
    ]
}

組織からロールを取り消す

REST API を使用してロールを取り消すには、URL パスに <application-id>, <organization-id><role-id> を含め、ヘッダに X-Auth-Token を使用して自 身を識別する、 DELETE リクエストを行います。

次の例では、組織の members に対して、ロールを取り消します。

23 リクエスト :

curl -iX DELETE \
  'http://localhost:3005/v1/applications/{{application-id}}/organizations/{{organization-id}}/roles/{{role-id}}/organization_roles/member' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

個々のユーザ・アカウントを認可

ロールがすでにアプリケーションに関連付けられていない限り、定義されたロールをユー ザに付与することはできません。

ユーザにロールを付与

GUI によるユーザ・アクセスの付与は、組織と同じ方法で実行できます。

REST API を使用すると、次に示すように、URL パスに <application-id>, <user-id><role-id> を含め、ヘッダに X-Auth-Token を使用して自身を識別 する、 PUT リクエストを行うことで、ロールを付与することができます。

24 リクエスト :

curl -iX PUT \
  'http://localhost:3005/v1/applications/{{application-id}}/users/{{user-id}}/roles/{{role-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

{
    "role_user_assignments": {
        "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c",
        "user_id": "bbbbbbbb-good-0000-0000-000000000000",
        "oauth_client_id": "3782c5e3-88f9-481a-9b3c-2f2d6f604482"
    }
}

付与されたユーザ・ロールのリストを取得

個々のユーザに付与されたロールをリスト表示するには 、v1/applications/{{application-id}}/users/{{user-id}}/roles エンドポイントに GET リクエストを行います。

25 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/users/{{user-id}}/roles' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスは、ユーザに割り当てられたすべてのロールを返します。

{
    "role_user_assignments": [
        {
            "user_id": "bbbbbbbb-good-0000-0000-000000000000",
            "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c"
        }
    ]
}

ユーザからロールを取り消す

組織と同様に、REST API を使用してロールを取り消すには、URL パスに <application-id>, <user-id><role-id> を含め、ヘッダに X-Auth-Token を使用して自身を識別する、 DELETE リクエストを行います。

26 リクエスト :

curl -X DELETE \
  'http://localhost:3005/v1/applications/{{application-id}}/users/{{user-id}}/roles/{{role-id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

アプリケーション付与のリストを取得

一連のロールを作成し、それらをユーザや組織に付与することによって、それらの間の関 連付けを行いました。REST API には、アプリケーションのすべての付与をリスト表示す る 2 つの便利なメソッドがあります。

認可された組織のリストを取得

アプリケーションの使用を認可されているすべての組織をリストするには 、/v1/applications/{{application-id}}/organizations エンドポイントに GET リク エストを行います。

27 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/organizations' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスは、アプリケーションにアクセスできるすべての組織と、割り当てられている ロールを返します。個々のメンバはリストされていません。

{
    "role_organization_assignments": [
        {
            "organization_id": "security-team-0000-0000-000000000000",
            "role_organization": "member",
            "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c"
        }
    ]
}

認可されたユーザのリストを取得

アプリケーションの使用を許可されている個々のユーザをすべてリスト表示するには 、/v1/applications/{{application-id}}/users エンドポイントに GET リクエストを 行います。

28 リクエスト :

curl -X GET \
  'http://localhost:3005/v1/applications/{{application-id}}/users' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-token: {{X-Auth-token}}'

レスポンス :

レスポンスは、アプリケーションにアクセスできる個々のユーザと、割り当てられたロー ルを返します。アクセス権を付与された組織のユーザはリストされていないことに注意し てください。

{
    "role_user_assignments": [
        {
            "user_id": "aaaaaaaa-good-0000-0000-000000000000",
            "role_id": "provider"
        },
        {
            "user_id": "bbbbbbbb-good-0000-0000-000000000000",
            "role_id": "64535f4d-04b6-4688-a9bb-81b8df7c4e2c"
        }
    ]
}

?このシリーズ の他のチュートリアルを読むことで見 つけることができます。


License

MIT © 2018-2019 FIWARE Foundation e.V.