10. API を使用した認証方法¶

この章では、数多くの企業向け認証方法、それぞれの最適な使用例、および例について説明します。

セッション認証
Basic 認証
OAuth2 トークン認証
SSO 認証

Automation controller は、組織が自動化を一元化して制御するために設計されており、すぐに使用できる制御用のビジュアルダッシュボードを使用して、より深いレベルで他のツールと統合するための REST API を提供します。Automation controller は多数の認証方法をサポートして、コントローラーを既存のツールやプロセスに簡単に組み込み、適切なユーザーがコントローラーのリソースにアクセスできるようにします。

10.1. セッション認証 ¶

セッション認証は、automation controller の API または UI に直接ログインして、ブラウザー上でリソース (インベントリー、プロジェクト、ジョブテンプレート) を手動で作成し、ジョブを起動するときに使用します。この方法では、その HTTP リクエストだけでなく、たとえば Chrome や Firefox などのブラウザーで UI または API を閲覧する際にも、長時間ログインしたままにすることができます。ユーザーがログインすると、セッションクッキーが作成され、ユーザーが automation controller 内の別のページに移動してもログイン状態が維持されたままになります。以下は、セッションでクライアントとサーバーの間に発生する通信を表したものです。

curl ツールを使用すると、コントローラーにログインしたときに発生するアクティビティーを確認することができます。

csrftoken クッキーを取得するには、/api/login/ のエンドポイントに GET します。

curl -k -c - https://<controller-host>/api/login/

localhost       FALSE   /       FALSE   0   csrftoken
AswSFn5p1qQvaX4KoRZN6A5yer0Pq0VG2cXMTzZnzuhaY0L4tiidYqwf5PXZckuj

ユーザー名、パスワード、および X-CSRFToken=<token-value> を指定して /api/login/ エンドポイントに POST します。

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
--referer https://<controller-host>/api/login/ \
-H 'X-CSRFToken: K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
--data 'username=root&password=reverse' \
--cookie 'csrftoken=K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
https://<controller-host>/api/login/ -k -D - -o /dev/null

これらはすべて、ブラウザーで UI や API にログインする際に automation controller によって行われ、ブラウザーで認証する場合にのみ使用する必要があります。automation controller とのプログラムによる統合については、OAuth2 トークン認証を参照してください。

一般的な応答は次のようになります。

Server: nginx
Date: <current date>
Content-Type: text/html; charset=utf-8
Content-Length: 0
Connection: keep-alive
Location: /accounts/profile/
X-API-Session-Cookie-Name: awx_sessionid
Expires: <date>
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
Vary: Cookie, Accept-Language, Origin
Session-Timeout: 1800
Content-Language: en
X-API-Total-Time: 0.377s
X-API-Request-Id: 700826696425433fb0c8807cd40c00a0
Access-Control-Expose-Headers: X-API-Request-Id
Set-Cookie: userLoggedIn=true; Path=/
Set-Cookie: current_user=<user cookie data>; Path=/
Set-Cookie: csrftoken=<csrftoken>; Path=/; SameSite=Lax
Set-Cookie: awx_sessionid=<your session id>; expires=<date>; HttpOnly; Max-Age=1800; Path=/; SameSite=Lax
Strict-Transport-Security: max-age=15768000

ユーザーがこの方法で正常に認証されると、サーバーは X-API-Session-Cookie-Name というヘッダーで応答し、セッションクッキーの設定された名前を示します。デフォルト値は awx_session_id で、これは後で Set-Cookie ヘッダーで見ることができます。

注釈

セッションの有効期限は、SESSION_COOKIE_AGE パラメーターで指定することで変更可能です。詳細は、セッション制限の使用を参照してください。

10.2. Basic 認証 ¶

Basic 認証 (Basic Auth) はステートレスであるため、base64 エンコードされた username と password を Authorization ヘッダーを介して各リクエストとともに送信する必要があります。これは、curl リクエスト、python スクリプト、または API への個別のリクエストからの API 呼び出しに使用できます。API にアクセスする場合は、可能な限り OAuth2 トークン認証を使用することを推奨します。

curl の例:

curl -X GET -H 'Authorization: Basic dXNlcjpwYXNzd29yZA==’ https://<controller-host>/api/v2/credentials -k -L

# the --user flag adds this Authorization header for us
curl -X GET --user 'user:password' https://<controller-host>/api/v2/credentials -k -L

Basic HTTP 認証スキームの詳細は、RFC 7617 を参照してください。

注釈

コントローラーの UI 設定メニューのその他の認証設定から、セキュリティー目的で Basic 認証を無効にすることができます。

_images/configure-tower-auth-basic-off.png

10.3. OAuth2 トークン認証 ¶

OAuth (Open Authorization) は、トークンベースの認証と承認のためのオープンな標準規格です。OAuth 2 認証は、プログラムでコントローラー API と対話するときに一般的に使用されます。Basic 認証と同様に、OAuth 2 トークンは Authorization ヘッダーを介して各 API リクエストで提供されます。Basic 認証とは異なり、OAuth 2 トークンには設定可能なタイムアウトがあり、スコープも可能です。トークンには設定可能な有効期限があり、必要に応じて、管理者が 1 人のユーザーまたは automation controller システム全体に対して簡単に失効させることができます。これは、Automation Controller Administration Guide で詳しく説明されている revoke_oauth2_tokens 管理コマンドを使用するか、アクセストークンの取り消しで説明されている API を使用して行うことができます。

注釈

デフォルトでは、SSO によって作成されたユーザーなどの外部ユーザーは、セキュリティー上の目的で OAuth トークンを生成できません。これは、コントローラーの UI 設定メニューのその他の認証設定から変更することができます。

_images/configure-tower-external-tokens-off.png

以下のようなさまざまな方法で、|at|で OAuth 2 Access Token を取得することができます。

パーソナルアクセストークン (PAT)
アプリケーショントークン: パスワード付与タイプ
アプリケーショントークン: 暗黙の付与タイプ
アプリケーショントークン: 認証コード付与タイプ

上記の方法の詳細については、Automation Controller Administration Guide のトークンベースの認証を参照してください。

まず、ユーザーは API または UI のユーザーの トークン タブで OAuth 2 アクセストークンを作成する必要があります。UI を使用してそれらを作成する方法の詳細は、ユーザー: トークンを参照してください。この例では、API でトークンを作成するために PAT メソッドを使用します。トークンの作成時に、ユーザーはスコープを設定することができます。

注釈

トークンの有効期限は、システム全体で設定できます。詳細は、パーソナルアクセストークン (PAT) 向けの OAuth2 トークンシステムの使用を参照してください。

PAT (関連アプリケーションなし) を作成する以下の例のように、トークン認証は、automation controller API をプログラムで使用する場合 (Python スクリプトや curl のようなツールなど) に最適です。

Curl の例

curl -u user:password -k -X POST https://<controller-host>/api/v2/tokens/

この呼び出しは、以下のような JSON データを返します。

_images/api_oauth2_json_returned_token_value.png

token プロパティーの値は、automation controller リソース (例:Hosts) に対する GET リクエストを実行するために現時点で使用できるものです。

curl -k -X POST \
  -H “Content-Type: application/json”
  -H “Authorization: Bearer <oauth2-token-value>” \
  https://<controller-host>/api/v2/hosts/

同様に、起動したいジョブテンプレートに対して POST を行うことで、ジョブを起動することができます。

curl -k -X POST \
  -H "Authorization: Bearer <oauth2-token-value>" \
  -H "Content-Type: application/json" \
  --data '{"limit" : "ansible"}' \
  https://<controller-host>/api/v2/job_templates/14/launch/

Python の例

awxkit は、HTTP リクエストを使って簡単に automation controller API にアクセスできるようにするオープンソースツールです。awxkit login コマンドを使うことで、awxkit に PAT の取得を代行させることができます。詳細は、AWX Command Line Interface を参照してください。

外部アプリケーションを統合する際の automation controller における OAuth 2 の使用方法の詳細については、Automation Controller Administration Guide のトークンベースの認証を参照してください。

カスタムリクエストを書く必要がある場合は、この例のように、Python library requests を使って Python スクリプトを書くことができます。

import requests
oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA'   # your token value from controller
url = 'https://<controller-host>/api/v2/users/'
payload = {}
headers = {'Authorization': 'Bearer ' + oauth2_token_value,}

# makes request to controller user endpoint
response = requests.request('GET', url, headers=headers, data=payload,
allow_redirects=False, verify=False)

# prints json returned from controller with formatting
print(json.dumps(response.json(), indent=4, sort_keys=True))

10.4. SSO 認証 ¶

Single Sign-On (SSO) 認証方法は、Google SSO、Azure SSO、SAML、GitHub などのように、ユーザーの認証が automation controller の外部で行われるため、他の方法とは根本的に異なります。たとえば、GitHub SSO の場合、GitHub が信頼できる唯一の情報源であり、これがコントローラーに指定したユーザー名とパスワードに基づいて ID を検証します。

一元的なアイデンティティープロバイダーを持つ大規模な組織内部で、automation controller を使用して SSO 認証を設定することができます。コントローラーで SSO の方式を設定すると、ログイン画面に SSO 用のボタンが表示されるようになります。このボタンをクリックすると、アイデンティティープロバイダー (この場合は GitHub) にリダイレクトされ、そこで認証情報を提示することになります。アイデンティティープロバイダーによる認証が正常に行われると、コントローラーは GitHub ユーザーとリンクしたユーザーを作成し (この SSO 方式で初めてログインする場合)、ログインできるようになります。

サポートされているさまざまなタイプの SSO 認証方法については、Automation Controller Administration Guide のソーシャル認証の設定およびエンタープライズ認証の設定を参照してください。

10. API を使用した認証方法¶

10.1. セッション認証¶

10.2. Basic 認証¶

10.3. OAuth2 トークン認証¶

10.4. SSO 認証¶

10.1. セッション認証 ¶

10.2. Basic 認証 ¶

10.3. OAuth2 トークン認証 ¶

10.4. SSO 認証 ¶