10. API를 사용한 인증 방법¶

10.1. 세션 인증¶

세션 인증은 |at|의 API 또는 UI에 직접 로그인하여 리소스(인벤토리, 프로젝트, 작업 템플릿)를 수동으로 생성하고 브라우저에서 작업을 시작하는 데 사용됩니다. 이 방법을 사용하면 해당 HTTP 요청뿐만 아니라 Chrome 또는 Firefox와 같은 브라우저에서 UI 또는 API를 탐색할 때 장기간 로그인 상태를 유지할 수 있습니다. 사용자가 로그인하면 세션 쿠키가 생성되어 사용자가 |at| 내의 다른 페이지로 이동할 때 로그인 상태를 유지할 수 있습니다. 다음은 세션에서 클라이언트와 서버 간에 발생하는 통신을 나타냅니다.

curl 툴을 사용하면 컨트롤러에 로그인할 때 발생하는 활동을 확인할 수 있습니다.

1. /api/login/ 끝점으로 이동하여 csrftoken 쿠키를 가져옵니다.

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

localhost       FALSE   /       FALSE   0   csrftoken
AswSFn5p1qQvaX4KoRZN6A5yer0Pq0VG2cXMTzZnzuhaY0L4tiidYqwf5PXZckuj

2. 사용자 이름, 암호 및 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 과 프로그래밍 방식의 통합은 OAuth 2 토큰 인증 를 참조하십시오.

일반적인 응답은 다음과 같습니다.

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 헤더에서 볼 수 있습니다.

10.2. 기본 인증¶

기본 인증(Basic Auth)은 상태 비저장이므로 base64로 인코딩된 username 및 password 은 인증 헤더를 통해 각 요청과 함께 보내야 합니다. 이는 curl 요청, python 스크립트 또는 API에 대한 개별 요청의 API 호출에 사용할 수 있습니다. OAuth 2 토큰 인증 가능한 경우 API에 액세스하는 것이 좋습니다.

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

기본 HTTP 인증 방식에 대한 자세한 내용은 `RFC 7617 <https://datatracker.ietf.org/doc/html/rfc7617>`_을 참조하십시오.

참고

컨트롤러 UI 설정 메뉴의 기타 인증 설정에서 보안 목적으로 Basic Auth를 비활성화할 수 있습니다.

10.3. OAuth 2 토큰 인증¶

OAuth(Open Authorization)는 토큰 기반 인증 및 권한 부여를 위한 오픈 표준입니다. OAuth 2 인증은 일반적으로 컨트롤러 API와 프로그래밍 방식으로 상호 작용할 때 사용됩니다. 기본 인증과 마찬가지로 OAuth 2 토큰은 인증 헤더를 통해 각 API 요청과 함께 제공됩니다. 기본 인증과 달리 OAuth 2 토큰에는 구성 가능한 시간 제한이 있으며 범위를 지정할 수 있습니다. 토큰은 구성 가능한 만료 시간이 있으며 한 사용자 또는 필요한 경우 관리자가 전체 automation controller 시스템에 대해 쉽게 취소할 수 있습니다. 이 작업은 :ref:에서 자세히 설명하거나`ag_manage_utility_revoke_tokens` Automation Controller Administration Guide 에 설명된 대로 API를 사용하여 다루는 액세스 토큰 취소 관리 명령을 사용하여 수행할 수 있습니다.

참고

기본적으로 SSO에서 생성한 사용자와 같은 외부 사용자는 보안을 위해 OAuth 토큰을 생성할 수 없습니다. 컨트롤러 UI 설정 메뉴의 기타 인증 설정에서 이 설정을 변경할 수 있습니다.

automation controller 에서 OAuth 2 액세스 토큰을 가져오는 다양한 방법은 다음과 같습니다.

• 개인 액세스 토큰 (PAT)

• 애플리케이션 토큰: 암호 부여 유형

• 애플리케이션 토큰: Implicit 권한 부여 유형

• 애플리케이션 토큰: 인증 코드 권한 부여 유형

위의 방법에 대한 자세한 내용은 |ata|의 :ref:`ag_oauth2_token_auth`을 참조하십시오.

먼저 사용자가 API에 OAuth 2 액세스 토큰을 생성하거나 UI의 사용자 토큰 탭에서 생성해야 합니다. UI를 통한 생성에 대한 자세한 내용은 :ref:`ug_users_tokens`에서 참조하십시오. 이 예에서는 API에서 토큰을 생성하려면 PAT 메서드를 사용합니다. 토큰 생성 시 사용자는 범위를 설정할 수 있습니다.

토큰 인증은 아래의 PAT(관련 애플리케이션 제외)를 생성하는 경우와 같이 Python 스크립트 또는 curl과 같은 automation controller API의 프로그래밍 방식으로 사용하는 데 가장 적합합니다.

Curl 예

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

이 호출은 다음과 같은 JSON 데이터를 반환합니다.

token 속성 값은 automation controller 리소스에 대한 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 <https://pypi.org/project/awxkit/>`_은 HTTP 요청을 사용하여 |at| API에 쉽게 액세스할 수 있는 오픈 소스 툴입니다. awxkit은 ``awxkit login` 명령을 사용하여 사용자를 대신하여 PAT를 얻을 수 있습니다. 자세한 내용은 `AWX Command Line Interface <https://docs.ansible.com/automation-controller/latest/html/controllercli/index.html>`_에서 참조하십시오.

외부 애플리케이션 통합 컨텍스트에서 automation controller 에서 OAuth 2를 사용하는 방법에 대한 자세한 내용은 Automation Controller Administration Guide 의 토큰 기반 인증 를 참조하십시오.

사용자 정의 요청을 작성해야 하는 경우 다음 예제와 같이 `Python library requests <https://pypi.org/project/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 인증¶

SSO(Single Sign-On) 인증 방법은 사용자의 인증이 Google SSO, Azure SSO, SAML 또는 GitHub와 같이 automation controller 외부에 수행되므로 다른 방법과 근본적으로 다릅니다. 예를 들어 GitHub SSO를 사용하여 GitHub는 컨트롤러에 제공한 사용자 이름과 암호를 기반으로 ID를 확인하는 단일 정보 소스입니다.

중앙 ID 공급자가 있는 대규모 조직 내에서 |at|를 사용하여 SSO 인증을 구성할 수 있습니다. 컨트롤러에서 SSO 메서드를 구성하면 해당 SSO의 버튼이 로그인 화면에 표시됩니다. 해당 버튼을 클릭하면 ID 공급자(이 경우 GitHub)로 리디렉션됩니다. ID 공급자가 사용자를 성공적으로 확인하는 경우 컨트롤러는 GitHub 사용자에 연결된 사용자를 만들고(이 SSO 메서드를 통해 처음 로그인하는 경우) 로그인합니다.

지원되는 다양한 유형의 SSO 인증 방법에 대해서는 :ref:에서`ag_social_auth` :ref:및`ag_ent_auth` Automation Controller Administration Guide 를 참조하십시오.