18. 토큰 기반 인증¶
OAuth 2는 토큰 기반 인증에 사용됩니다. 토큰을 생성하는 데 사용되는 API 클라이언트의 서버 측 표현체인 애플리케이션뿐만 아니라 OAuth 토큰도 관리할 수 있습니다. OAuth 토큰을 HTTP 인증 헤더에 포함하면 사용자는 자신을 인증할 수 있으며 기본 RBAC 권한 외에도 제한적인 권한의 수준을 조정할 수 있습니다. OAuth 2 사양에 대한 자세한 내용은 `RFC 6749`_를 참조하십시오.
manage 유틸리티를 사용하여 토큰을 생성하는 방법에 대한 자세한 내용은 토큰 및 세션 관리 섹션을 참조하십시오.
18.1. OAuth 2 애플리케이션 및 토큰 관리¶
애플리케이션과 토큰은 /api/<version>/applications 및 /api/<version>/tokens``에서 최상위 리소스로 관리할 수 있습니다. ``/api/<version>/users/N/<resource>``에서 사용자를 기준으로 이러한 리소스에 액세스할 수도 있습니다. ``api/<version>/applications 또는 ``/api/<version>/users/N/applications``에 **POST**를 수행하면 애플리케이션을 생성할 수 있습니다.
각 OAuth 2 애플리케이션은 서버 측의 특정 API 클라이언트를 나타냅니다. API 클라이언트가 애플리케이션 토큰을 통해 API를 사용하려면 먼저 애플리케이션이 있어야 하며 액세스 토큰을 발행해야 합니다. 개별 애플리케이션은 기본 키인 ``/api/<version>/applications/<pk>/``를 통해 액세스할 수 있습니다. 다음은 일반적인 애플리케이션의 예제입니다.
{
"id": 1,
"type": "o_auth2_application",
"url": "/api/v2/applications/2/",
"related": {
"tokens": "/api/v2/applications/2/tokens/"
},
"summary_fields": {
"organization": {
"id": 1,
"name": "Default",
"description": ""
},
"user_capabilities": {
"edit": true,
"delete": true
},
"tokens": {
"count": 0,
"results": []
}
},
"created": "2018-07-02T21:16:45.824400Z",
"modified": "2018-07-02T21:16:45.824514Z",
"name": "My Application",
"description": "",
"client_id": "Ecmc6RjjhKUOWJzDYEP8TZ35P3dvsKt0AKdIjgHV",
"client_secret": "7Ft7ym8MpE54yWGUNvxxg6KqGwPFsyhYn9QQfYHlgBxai74Qp1GE4zsvJduOfSFkTfWFnPzYpxqcRsy1KacD0HH0vOAQUDJDCidByMiUIH4YQKtGFM1zE1dACYbpN44E",
"client_type": "confidential",
"redirect_uris": "",
"authorization_grant_type": "password",
"skip_authorization": false,
"organization": 1
}
위 예제에서와 같이 name``은 사람이 읽을 수 있는 애플리케이션 식별자입니다. 나머지 필드(예: ``client_id, redirect_uris)는 나중에 :ref:`ag_use_oauth_pat`에서 설명하는 OAuth2 인증에 주로 사용됩니다.
client_id 및 client_secret 필드의 값은 생성 과정에서 만들어지며 편집할 수 없는 애플리케이션 식별자이지만 organization 및 ``authorization_grant_type``은 생성 시 필요하며 편집할 수 없게 됩니다.
18.1.1. 애플리케이션 액세스 규칙¶
애플리케이션 액세스 규칙은 다음과 같습니다.
시스템 관리자는 시스템의 모든 애플리케이션을 보고 조작할 수 있습니다.
조직 관리자는 조직 멤버에 속하는 모든 애플리케이션을 보고 조작할 수 있습니다.
다른 사용자는 고유한 애플리케이션을 보거나 업데이트 및 삭제할 수만 있고 새 애플리케이션을 생성할 수는 없습니다.
한편, 토큰은 들어오는 요청을 실제로 인증하고 기본 사용자의 권한을 마스킹하는 데 사용되는 리소스입니다. 토큰을 생성하는 방법에는 다음 두 가지가 있습니다.
application및scope필드를 사용해/api/v2/tokens/끝점에 POST를 수행하여 관련 애플리케이션을 가리키고 토큰 범위를 지정scope필드를 사용해/api/v2/applications/<pk>/tokens/끝점에 POST를 수행하여 상위 애플리케이션을 자동으로 연결
개별 토큰은 기본 키인 ``/api/<version>/tokens/<pk>/``를 통해 액세스할 수 있습니다. 다음은 일반적인 토큰의 예제입니다.
{
"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필드는 토큰이 생성된 사용자이며, 이 경우 토큰을 생성하는 사용자이기도 합니다.
애플리케이션 토큰과 개인 액세스 토큰은 둘 다 /api/v2/tokens/ 끝점에 표시됩니다. 개인 액세스 토큰의 application 필드는 항상 **null**입니다. 이런 특성에 따라 두 유형의 토큰을 쉽게 구별할 수 있습니다.
18.1.2. 토큰 액세스 규칙¶
토큰 액세스 규칙은 다음과 같습니다.
사용자가 관련 애플리케이션을 볼 수 있는 경우 토큰을 생성할 수 있으며, 개인 토큰을 직접 생성할 수도 있습니다.
시스템 관리자는 시스템의 모든 토큰을 보고 조작할 수 있습니다.
조직 관리자는 조직 멤버에 속하는 모든 토큰을 보고 조작할 수 있습니다.
시스템 감사자는 모든 토큰과 애플리케이션을 볼 수 있습니다.
다른 일반 사용자는 고유한 토큰만 보고 조작할 수 있습니다.
참고
사용자는 생성 시에만 토큰을 보거나 토큰 값을 새로 고칠 수 있습니다.
18.2. PAT(개인 액세스 토큰)에 OAuth 2 토큰 시스템 사용¶
OAuth 2 토큰을 얻는 가장 쉽고 일반적인 방법은 아래 예제에서와 같이 /api/v2/users/<userid>/personal_tokens/ 끝점에 개인 액세스 토큰을 생성하는 것입니다.
curl -XPOST -k -H "Content-type: application/json" -d '{"description":"Personal controller CLI token", "application":null, "scope":"write"}' https://<USERNAME>:<PASSWORD>@<CONTROLLER_SERVER>/api/v2/users/<USER_ID>/personal_tokens/ | python -m json.tool
설치된 경우 ``jq``를 통해 JSON 출력을 파이프할 수도 있습니다.
다음은 개인 토큰을 사용하여 curl로 API 끝점에 액세스하는 예제입니다.
curl -k -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -X POST -d '{}' https://controller/api/v2/job_templates/5/launch/
|at|에서는 OAuth 2 시스템이 Django Oauth Toolkit`_을 기반으로 하므로 토큰 권한 부여, 취소, 새로 고침을 위한 전용 끝점을 제공합니다. 이러한 끝점은 `/api/v2/users/<USER_ID>/personal_tokens/`` 끝점 아래에서 찾을 수 있으며, 해당 끝점의 몇 가지 일반적인 사용 예제도 자세하게 제공됩니다. 이와 같은 특수 OAuth 2 끝점은 x-www-form-urlencoded Content-type 사용만 지원하므로 api/o/* 끝점은 ``application/json``을 허용하지 않습니다.
참고
애플리케이션 유형에 null``을 지정하여 ``/api/o/token 끝점으로 토큰을 요청할 수도 있습니다.
또는 컨트롤러 사용자 인터페이스를 통해 사용자를 위한 add tokens 작업을 수행할 수 있으며, 해당하는 경우 액세스 토큰 및 관련 새로 고침 토큰의 만료를 구성할 수 있습니다.
18.2.1. RBAC 시스템 위의 토큰 범위 마스크¶
OAuth 2 토큰의 범위는 유효한 범위 키워드인 ‘read’와 ‘write’로 구성된 공백 구분 문자열입니다. 이러한 키워드는 구성 가능하며, 인증된 API 클라이언트의 권한 수준을 지정하는 데 사용됩니다. read 및 write 범위는 |at|의 RBAC(역할 기반 액세스 제어) 권한 시스템 위에 마스크 계층을 제공합니다. 구체적으로 ‘write’ 범위는 RBAC 시스템에서 제공하는 전체 권한을 인증된 사용자에게 부여하는 반면, ‘read’ 범위는 RBAC 시스템에서 제공하는 읽기 권한만 인증된 사용자에게 부여합니다. 즉, ‘write’에는 ‘read’도 포함됩니다.
예를 들어 작업 템플릿에 대한 관리 권한이 있으면, 세션 또는 기본 인증을 통해 인증된 경우 작업 템플릿을 보거나 수정, 시작, 삭제할 수 있습니다. 반대로, OAuth 2 토큰을 사용하여 인증되었으며 관련 토큰 범위가 ‘read’인 경우 관리자라도 작업 템플릿을 볼 수만 있고 조작하거나 시작할 수는 없습니다. 토큰 범위가 ‘write’ 또는 ‘read write’인 경우 관리자 권한으로 작업 템플릿을 최대한 활용할 수 있습니다.
토큰을 얻어서 사용하려면 먼저 애플리케이션 토큰을 생성합니다.
authorization_grant_type``을 ``password``로 설정하여 애플리케이션을 만듭니다. ``/api/v2/applications/끝점에 다음을 HTTP POST합니다. 이때 고유한 조직 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>
}
토큰을 만들고
/api/v2/tokens/끝점에 POST합니다.
{
"description": "My Access Token",
"application": <application-id>,
"scope": "write"
}
그러면 향후 요청 시 인증에 사용할 수 있는 <token-value>가 반환됩니다. 이 값은 다시 표시되지 않습니다.
토큰을 사용하여 리소스에 액세스합니다. 다음 예제에서는 curl을 사용합니다.
curl -H "Authorization: Bearer <token-value>" -H "Content-Type: application/json" -X GET https://<controller>/api/v2/users/
아직 CA를 설정하지 않았으며 SSL을 사용하는 경우 -k 플래그가 필요할 수 있습니다.
토큰을 취소하려면 해당 토큰의 세부 정보 페이지에서 토큰 ID를 사용하여 DELETE를 수행할 수 있습니다. 예를 들어 다음과 같습니다.
curl -ku <user>:<password> -X DELETE https://<controller>/api/v2/tokens/<pk>/
마찬가지로, 토큰을 사용하는 경우 다음과 같습니다.
curl -H "Authorization: Bearer <token-value>" -X DELETE https://<controller>/api/v2/tokens/<pk>/ -k
18.3. 애플리케이션 기능¶
이 페이지에는 인증, 토큰 새로 고침, 취소에 사용되는 OAuth 2 유틸리티 끝점이 나와 있습니다. /api/o/ 끝점은 브라우저에서 사용할 수 없으며 HTTP GET을 지원하지 않습니다. 여기에 규정된 끝점은 OAuth 2의 RFC 사양을 엄격하게 따르므로 자세한 내용은 이 사양을 참조하십시오. 다음은 특히 다양한 권한 부여 유형을 사용하여 애플리케이션을 생성할 때 컨트롤러에서 이러한 끝점을 사용하는 일반적인 예제입니다.
인증 코드
암호
참고
컨트롤러 사용자 인터페이스를 사용하여 여기서 설명하는 모든 애플리케이션 기능을 수행할 수 있습니다. 자세한 내용은 |atu|의 Applications 섹션을 참조하십시오.
18.3.1. authorization code 권한 부여 유형을 사용하는 애플리케이션¶
외부 애플리케이션 또는 서비스에 액세스 토큰을 직접 발행해야 하는 경우 애플리케이션 authorization code 권한 부여 유형을 사용해야 합니다.
참고
애플리케이션을 사용할 때 액세스 토큰을 얻으려면
authorization code유형만 사용해야 합니다. 외부 웹앱을 |at|와 통합하는 경우 해당 웹앱에서 다른 웹앱의 사용자를 대신하여 OAuth2 토큰을 생성해야 할 수도 있습니다.authorization code권한 부여 유형을 사용하여 컨트롤러에서 애플리케이션을 생성하는 것이 좋으며 그 이유는 다음과 같습니다.
외부 애플리케이션에서 사용자 인증 정보를 통해 컨트롤러에서 사용자 토큰을 얻을 수 있습니다.
특정 애플리케이션에 발행되는 분류된 토큰을 사용하므로 해당 토큰을 쉽게 관리할 수 있습니다. 예를 들어 시스템의 모든 토큰을 취소하지 않고도 애플리케이션과 연결된 모든 토큰을 취소할 수 있습니다.
authorization-code 권한 부여 유형을 사용하여 *AuthCodeApp*이라는 애플리케이션을 생성하려면 /api/v2/applications/ 끝점에 POST를 수행합니다.
{
"name": "AuthCodeApp",
"user": 1,
"client_type": "confidential",
"redirect_uris": "http://<controller>/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**을 발행할 때 발생하는 워크플로우는 다음과 같습니다.
컨트롤러가 애플리케이션에서 지정된 ``redirect_uri``에 인증 코드와 상태로 응답합니다.
그런 다음, 클라이언트 애플리케이션이
code,client_id,client_secret,grant_type,redirect_uri``를 사용하여 컨트롤러의 ``api/o/token/끝점에 **POST**를 수행합니다.컨트롤러가
access_token,token_type,refresh_token, ``expires_in``으로 응답합니다.
위의 워크플로우를 테스트하려면 Django’s Test Your Authorization Server 툴킷을 참조하십시오.
시스템 설정 화면에서 인증 코드가 유효한 시간(초)을 지정할 수 있습니다.
이 기간 후에 액세스 토큰을 요청하면 실패합니다. 기간의 기본값은 RFC6749 권장 사항에 따라 600초(10분)입니다.
인증 코드 권한 부여 유형을 사용하여 |at|와 앱의 통합을 설정하는 가장 좋은 방법은 해당 사이트 간 요청의 출처를 허용 목록에 추가하는 것입니다. 좀 더 일반적으로 살펴보면 액세스 토큰을 제공하려는 컨트롤러와 통합 중인 서비스 또는 애플리케이션을 허용 목록에 추가해야 합니다. 이렇게 하려면 관리자가 이 허용 목록을 로컬 컨트롤러 설정에 추가하도록 합니다.
CORS_ALLOWED_ORIGIN_REGEXES = [
r"http://django-oauth-toolkit.herokuapp.com*",
r"http://www.example.com*"
]
위 예제에서 ``http://django-oauth-toolkit.herokuapp.com``과 ``http://www.example.com``은 컨트롤러에 액세스하는 데 사용할 토큰이 있어야 하는 애플리케이션입니다.
18.3.2. password 권한 부여 유형을 사용하는 애플리케이션¶
password 권한 부여 유형 또는 Resource owner password-based 권한 부여 유형은 웹앱에 대한 기본 액세스 권한이 있는 사용자에게 적합하며, 클라이언트가 리소스 소유자일 때 사용해야 합니다. 다음 예제에서는 권한 부여 유형 ``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://<controller>/api/v2/tokens/
참고
특수 OAuth 2 끝점은 x-www-form-urlencoded Content-type 사용만 지원하므로 api/o/* 끝점은 ``application/json``을 허용하지 않습니다.
성공할 경우에는 액세스 토큰, 새로 고침 토큰, 기타 정보를 포함하는 응답이 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"}
18.4. 애플리케이션 토큰 기능¶
이 섹션에서는 토큰과 연결된 새로 고침 및 취소 기능에 대해 설명합니다. 아래의 모든 작업(/api/o/ 끝점에서 토큰 새로 고침 및 취소)은 현재 애플리케이션 토큰을 사용해야만 수행할 수 있습니다.
18.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://<controller>/api/o/token/ -i
위의 POST 요청에서 refresh_token``은 그 위에 있는 액세스 토큰의 ``refresh_token 필드에서 제공합니다. 인증 정보는 <client_id>:<client_secret> 포맷으로 표시됩니다. 여기서 ``client_id``와 ``client_secret``은 액세스 토큰에 있는 관련된 기본 애플리케이션의 해당 필드입니다.
참고
특수 OAuth 2 끝점은 x-www-form-urlencoded Content-type 사용만 지원하므로 api/o/* 끝점은 ``application/json``을 허용하지 않습니다.
성공할 경우에는 범위 정보가 이전 액세스 토큰과 동일한 새로 고친 액세스 토큰을 포함하는 응답이 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/ 끝점에 새 토큰이 있고 이전 토큰이 삭제되었는지 확인합니다.
18.4.2. 액세스 토큰 취소¶
마찬가지로, /api/o/revoke-token/ 끝점을 사용하여 액세스 토큰을 취소할 수 있습니다.
이 방법으로 액세스 토큰을 취소하는 경우 토큰 리소스 오브젝트를 삭제하는 것과 동일하지만, 토큰 값과 관련 client_id``(및 애플리케이션이 ``confidential``인 경우 ``client_secret)를 제공하여 토큰을 삭제할 수 있습니다. 예를 들어 다음과 같습니다.
curl -X POST -d "token=rQONsve372fQwuc2pn76k3IHDCYpi7" \
-u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \
http://<controller>/api/o/revoke_token/ -i
참고
특수 OAuth 2 끝점은 x-www-form-urlencoded Content-type 사용만 지원하므로 api/o/* 끝점은 ``application/json``을 허용하지 않습니다.
참고
외부 사용자가 Oauth2 토큰을 생성할 수 있도록 허용 (API의 ALLOW_OAUTH2_FOR_EXTERNAL_USERS) 설정은 기본적으로 비활성화되어 있습니다. 외부 사용자는 LDAP와 같은 서비스 또는 다른 SSO 서비스를 사용하여 외부에서 인증된 사용자를 가리킵니다. 이 설정은 외부 사용자가 고유한 토큰을 *생성*할 수 없도록 합니다. 설정을 활성화했다가 비활성화하는 경우 외부 사용자가 그동안 생성한 토큰은 모두 유지되며 자동으로 취소되지 않습니다.
또는 manage 유틸리티인 ag_manage_utility_revoke_tokens`를 사용하여 :ref:`ag_token_utility 섹션에 설명된 대로 토큰을 취소할 수 있습니다.
이 설정은 automation controller 사용자 인터페이스를 통해 시스템 수준에서 구성할 수 있습니다.
성공할 경우에는 200 OK 응답이 표시됩니다. /api/v2/tokens/ 끝점에 토큰이 있는지 검사하여 삭제 상태를 확인합니다.