19. トークンベースの認証¶

19.1.1. アプリケーションのアクセスルール¶

アプリケーションのアクセスルールは以下のとおりです。

• システム管理者は、システム内の全アプリケーションを表示し、操作できます。

• 組織の管理者は、組織メンバーに属するアプリケーションすべてを表示し、操作できます。

• 他のユーザーは、自身のアプリケーションの表示、更新、削除が可能ですが、新規アプリケーションは作成できません。

Tokens, on the other hand, are resources used to actually authenticate incoming requests and mask the permissions of the underlying user. There are two ways to create a token:

• POST to the /api/v2/tokens/ endpoint with application and scope fields to point to the related application and specify token scope

• POST to the /api/v2/applications/<pk>/tokens/ endpoint with the scope field (the parent application will be automatically linked)

Individual tokens are accessible via their primary keys: /api/<version>/tokens/<pk>/. Here is an example of a typical token:

{
    "id": 4,
    "type": "o_auth2_access_token",
    "url": "/api/v2/tokens/4/",
    "related": {
        "user": "/api/v2/users/1/",
        "application": "/api/v2/applications/1/",
        "activity_stream": "/api/v2/tokens/4/activity_stream/"
},
    "summary_fields": {
        "application": {
            "id": 1,
            "name": "Default application for root",
            "client_id": "mcU5J5uGQcEQMgAZyr5JUnM3BqBJpgbgL9fLOVch"
        },
        "user": {
            "id": 1,
            "username": "root",
            "first_name": "",
            "last_name": ""
        }
    },
    "created": "2018-02-23T14:39:32.618932Z",
    "modified": "2018-02-23T14:39:32.643626Z",
    "description": "App Token Test",
    "user": 1,
    "token": "*************",
    "refresh_token": "*************",
    "application": 1,
    "expires": "2018-02-24T00:39:32.618279Z",
    "scope": "read"
},

OAuth 2 トークンでは、完全に編集可能なフィールドは scope と description だけです。以下のように、application フィールドは更新時に編集不可で、他のフィールドはすべて編集できず、作成時に自動生成されます。

• user フィールドは、作成したトークンの対象ユーザーと同じです。今回は、トークンを作成したユーザーもこれになります。

• expires は、Tower の設定 OAUTH2_PROVIDER に基づいて生成されます。

• token および refresh_token は、クラッシュなしの乱数文字列として自動生成されます。

アプリケーショントークンとパーソナルアクセストークンは両方、/api/v2/tokens/ エンドポイントに表示されます。パーソナルアクセストークンの application フィールドは常に null です。これは、2 種類のトークンを区別するのに適した方法です。

19.1.2. トークンのアクセスルール¶

トークンのアクセスルールは以下のとおりです。

• ユーザーは、関連のアプリケーションを表示できる場合にはトークンを作成でき、自身の個人トークンも作成可能です。

• システム管理者は、システム内の全トークンを表示し、操作できます。

• 組織の管理者は、組織メンバーに属する全トークンの表示と操作が可能です。

• システム監査者は全トークンおよびアプリケーションの表示が可能です。

• 他の通常ユーザーは自身のトークンのみの表示と操作が可能です。

19.2.1. RBAC システム全体のトークンスコープのマスク¶

OAuth 2 トークンのスコープは、有効なスコープキーワード「read」と「write」で構成されるスペース区切りの文字列です。これらのキーワードは、設定可能で、認証済みの API クライアントのパーミッションレベルを指定するのに使用します。Read (読み取り) および Write (書き込み) スコープを設定することで、Ansible Tower のロールベースアクセス制御 (RBAC: Role-Based Access Control) パーミッションシステムにマスク層を提供します。具体的には、「write」スコープでは、RBAC システムが提供する全パーミッションを認証済みのユーザーに付与し、「read」スコープでは RBAC システムが提供する読み取りパーミッションのみを認証済みのユーザーに付与します。「write」パーミッションには、「read」も含まれている点に注意してください。

たとえば、ジョブテンプレートに管理者権限がある場合には、セッションまたは Basic 認証で認証済みであればジョブテンプレートの表示、変更、起動、削除が可能です。反対に、OAuth 2 トークンを使用して認証しており、関連のトークンスコープが 'read' の場合は、管理者であってもジョブテンプレートの表示はできますが、操作や起動はできません。トークンスコープが 'write' または 'read write' の場合は、管理者としてジョブテンプレートをすべて活用できます。

トークンを取得して使用するには、まずアプリケーショントークンを作成します。

1. アプリケーションの authorization_grant_type を password に設定します。以下の HTTP POST 要求を /api/v2/applications/ エンドポイントに実行します (独自の組織 ID を指定)。

{
    "name": "Admin Internal Application",
    "description": "For use by secure services & clients. ",
    "client_type": "confidential",
    "redirect_uris": "",
    "authorization_grant_type": "password",
    "skip_authorization": false,
    "organization": <organization-id>
}

2. トークンを作成して、POST 要求を /api/v2/tokens/ エンドポイントに実行します。

{
    "description": "My Access Token",
    "application": <application-id>,
    "scope": "write"
}

これで、今後の要求の認証に使用できるように <token-value> を返します (これは今後表示されません)。

3. このトークンを使用してリソースにアクセスします。以下は、例として curl を使用します。

curl -H "Authorization: Bearer <token-value>" -H "Content-Type: application/json" -X GET https://<tower>/api/v2/users/

CA をまだ設定しておらず、SSL を使用する場合には、-k フラグが必要な場合があります。

トークンを取り消すには、そのトークンに対して、トークンの ID を使用し、詳細ページで DELETE 要求を実行します。以下に例を示します。

curl -ku <user>:<password> -X DELETE https://<tower>/api/v2/tokens/<pk>/

同様に、トークンを使用する場合:

curl -H "Authorization: Bearer <token-value>" -X DELETE https://<tower>/api/v2/tokens/<pk>/ -k

19.3.1. authorization code 付与タイプを使用したアプリケーション¶

アクセストークンを外部アプリケーションまたはサービスに直接発行する必要がある場合は、アプリケーションの authorization code 付与タイプを使用する必要があります。authorization-code の付与タイプを使用して AuthCodeApp という名前のアプリケーションを作成するには、以下のようにして、/api/v2/applications/ エンドポイントに対して POST を実行します。

{
    "name": "AuthCodeApp",
    "user": 1,
    "client_type": "confidential",
    "redirect_uris": "http://<tower>/api/v2",
    "authorization_grant_type": "authorization-code",
    "skip_authorization": false
}


.. _`Django-oauth-toolkit simple test application`: http://django-oauth-toolkit.herokuapp.com/consumer/

response_type、client_id、redirect_uris および scope で、クライアントアプリケーションから authorize エンドポイントに、GET 要求を実行すると発生するワークフロー

1. Tower は、アプリケーションに指定されている redirect_uri に対して、認可コードとステータスで応答します。

2. 次にクライアントアプリケーションは、code、client_id、client_secret、grant_type および redirect_uri を指定して、Tower の api/o/token/ エンドポイントに、POST 要求を実行します。

3. Tower は、access_token、token_type、refresh_token および expires_in で応答します。

このフローのテストは、「 Django's Test Your Authorization Server 」ツールキットを参照してください。

Tower の設定の System 設定から、認可コードが有効な期間を秒単位で指定します。

この期間を過ぎてからアクセストークンを要求すると失敗します。「RFC6749 」の推奨をもとに、この期間は、600 秒 (10 分) にデフォルト設定されています。

認可コードの付与タイプを使用して Ansible Tower とのアプリの統合を設定する最適な方法は、これらのクロスサイト要求の送信元をホワイトリストに設定することです。より一般的に説明すると、アクセストークンを提供する対象である、Tower と統合するサービスやアプリケーションをホワイトリスト化する必要があります。そのためには、管理者に依頼して、以下のようにこのホワイトリストをローカルの Tower の設定に追加してもらいます。

CORS_ORIGIN_REGEX_WHITELIST = [
    r"http://django-oauth-toolkit.herokuapp.com*",
    r"http://www.example.com*"
]

ここで、http://django-oauth-toolkit.herokuapp.com および http://www.example.com は Tower にアクセスするのにトークンを必要とするアプリケーションです。

19.3.2. password 付与タイプを使用したアプリケーション¶

このタイプは、resource owner credentials grant とも呼ばれます。これは、Web アプリケーションにネイティブアクセスのあるユーザーに最適で、クライアントがリソースの所有者である場合に使用すると良いでしょう。以下は、付与タイプが password の 'Default Application' のアプリケーションを前提としています。

{
    "id": 6,
    "type": "application",
    ...
    "name": "Default Application",
    "user": 1,
    "client_id": "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l",
    "client_secret": "fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo",
    "client_type": "confidential",
    "redirect_uris": "",
    "authorization_grant_type": "password",
    "skip_authorization": false
}

password の付与タイプにはロギングは必要ないので、curl を使用して /api/v2/tokens/ エンドポイントからパーソナルアクセストークンを取得するだけです。

curl -k --user <user>:<password> -H "Content-type: application/json" \
-X POST \
--data '{
    "description": "Token for Nagios Monitoring app",
    "application": 1,
    "scope": "write"
}' \
https://<tower>/api/v2/tokens/

成功すると、JSON 形式でアクセストークンを含めて応答が表示され、トークンと他の情報が更新されます。

HTTP/1.1 200 OK
Server: nginx/1.12.2
Date: Tue, 05 Dec 2017 16:48:09 GMT
Content-Type: application/json
Content-Length: 163
Connection: keep-alive
Content-Language: en
Vary: Accept-Language, Cookie
Pragma: no-cache
Cache-Control: no-store
Strict-Transport-Security: max-age=15768000

{"access_token": "9epHOqHhnXUcgYK8QanOmUQPSgX92g", "token_type": "Bearer", "expires_in": 315360000000, "refresh_token": "jMRX6QvzOTf046KHee3TU5mT3nyXsz", "scope": "read"}

19.4.1. 既存のアクセストークンの更新¶

以下の例には、提供された更新トークンと既存のアクセストークンが示されています。

{
    "id": 35,
    "type": "access_token",
    ...
    "user": 1,
    "token": "omMFLk7UKpB36WN2Qma9H3gbwEBSOc",
    "refresh_token": "AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z",
    "application": 6,
    "expires": "2017-12-06T03:46:17.087022Z",
    "scope": "read write"
}

/api/o/token/ エンドポイントは、アクセストークンの更新に使用します。

curl -X POST \
    -d "grant_type=refresh_token&refresh_token=AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z" \
    -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \
    http://<tower>/api/o/token/ -i

上記の POST 要求では、refresh_token は、その上にあるアクセストークンの refresh_token フィールドから渡されます。認証情報の形式は <client_id>:<client_secret> で、client_id と client_secret は、配下にあるアクセストークンの関連アプリケーションの対応するフィールドに置き換えます。

成功すると、JSON 形式で以前のものと同じスコープ情報を含む、新しい (更新済み) アクセストークンを含めて応答が表示されます。

HTTP/1.1 200 OK
Server: nginx/1.12.2
Date: Tue, 05 Dec 2017 17:54:06 GMT
Content-Type: application/json
Content-Length: 169
Connection: keep-alive
Content-Language: en
Vary: Accept-Language, Cookie
Pragma: no-cache
Cache-Control: no-store
Strict-Transport-Security: max-age=15768000

{"access_token": "NDInWxGJI4iZgqpsreujjbvzCfJqgR", "token_type": "Bearer", "expires_in": 315360000000, "refresh_token": "DqOrmz8bx3srlHkZNKmDpqA86bnQkT", "scope": "read write"}

基本的に、更新の操作では、元のトークンを削除した直後に、元のトークンと同じスコープと関連のアプリケーションを持つ新規トークンを作成することで、既存のトークンを置き換えます。/api/v2/tokens/ エンドポイントに、新しいトークンがあり、以前のトークンが削除されていることを確認してください。

19.4.2. アクセストークンの取り消し¶

同様に、/api/o/revoke-token/ エンドポイントを使用してアクセストークンを取り消すことができます。

この方法でアクセストークンを取り消すのも、トークンリソースオブジェクトを削除するのも同じですが、トークンの値と関連の client_id (およアプリケーションが confidential の場合には client_secret) を指定してトークンを削除することができます。

curl -X POST -d "token=rQONsve372fQwuc2pn76k3IHDCYpi7" \
-u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \
http://<tower>/api/o/revoke_token/ -i

または、manage ユーティリティー 「 revoke_oauth2_tokens」を使用して、「トークンおよびセッション管理 」セクションに記載されているように、トークンを呼び出すことができます。

この設定は、Ansible Tower ユーザーインターフェースからシステムレベルで構成できます。

成功すると、200 OK の応答が表示されます。トークンが /api/v2/tokens/ エンドポイントに存在するかどうかをチェックして、削除されていることを確認します。