External-Mirrors/awx
2
0
Fork 0
mirror of https://github.com/ansible/awx.git synced 2026-05-13 12:27:37 -02:30
Code Issues Packages Projects Releases Wiki Activity

fix oauth docs

Browse Source
This commit is contained in:
adamscmRH
2018-03-08 12:31:40 -05:00
parent fd7c078a8b
commit 9b195bc80f
2 changed files with 22 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
awx/api/templates/api/api_o_auth_authorization_root_view.md
View File

@@ -51,7 +51,7 @@ Vary:Accept-Language, Cookie
By inspecting the fragment part of redirect URL given by `Location` header, we can get access token By inspecting the fragment part of redirect URL given by `Location` header, we can get access token
(given by `access_token` key) as well as other standard fields specified in OAuth spec. Internally (given by `access_token` key) as well as other standard fields specified in OAuth spec. Internally
an OAuth token is created under the given application. Verify by an OAuth token is created under the given application. Verify by
`GET /api/v2/me/oauth/tokens/?token=0lVJJkolFTwYawHyGkk7NTmSKdzBen` `GET /api/v2/tokens/?token=0lVJJkolFTwYawHyGkk7NTmSKdzBen`
```text ```text
HTTP 200 OK HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS Allow: GET, POST, HEAD, OPTIONS
@@ -176,7 +176,7 @@ Internally, the refresh operation deletes the existing token and a new token is
after, with information like scope and related application identical to the original one. We can after, with information like scope and related application identical to the original one. We can
verify by checking the new token is present verify by checking the new token is present
```text ```text
GET /api/v2/me/oauth/tokens/?token=NDInWxGJI4iZgqpsreujjbvzCfJqgR GET /api/v2/tokens/?token=NDInWxGJI4iZgqpsreujjbvzCfJqgR
HTTP 200 OK HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS Allow: GET, POST, HEAD, OPTIONS
@@ -208,7 +208,7 @@ X-API-Time: 0.021s
``` ```
and the old token is deleted. and the old token is deleted.
```text ```text
GET /api/v2/me/oauth/tokens/?token=omMFLk7UKpB36WN2Qma9H3gbwEBSOc GET /api/v2/tokens/?token=omMFLk7UKpB36WN2Qma9H3gbwEBSOc
HTTP 200 OK HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS Allow: GET, POST, HEAD, OPTIONS
@@ -234,7 +234,7 @@ an existing token to revoke:
{ {
"id": 30, "id": 30,
"type": "access_token", "type": "access_token",
"url": "/api/v2/me/oauth/tokens/30/", "url": "/api/v2/tokens/30/",
... ...
"user": null, "user": null,
"token": "rQONsve372fQwuc2pn76k3IHDCYpi7", "token": "rQONsve372fQwuc2pn76k3IHDCYpi7",
@@ -265,7 +265,7 @@ Strict-Transport-Security: max-age=15768000
``` ```
We can verify the effect by checking if the token is no longer present. We can verify the effect by checking if the token is no longer present.
```text ```text
GET /api/v2/me/oauth/tokens/?token=rQONsve372fQwuc2pn76k3IHDCYpi7 GET /api/v2//tokens/?token=rQONsve372fQwuc2pn76k3IHDCYpi7
HTTP 200 OK HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS Allow: GET, POST, HEAD, OPTIONS

29
docs/auth/oauth.md
View File

@@ -81,11 +81,11 @@ On RBAC side:
Tokens, on the other hand, are resources used to actually authenticate incoming requests and mask the Tokens, on the other hand, are resources used to actually authenticate incoming requests and mask the
permissions of the underlying user. Tokens can be created by POSTing to `/api/v2/tokens/` permissions of the underlying user. Tokens can be created by POSTing to `/api/v2/tokens/`
endpoint by providing `application` and `scope` fields to point to related application and specify endpoint by providing `application` and `scope` fields to point to related application and specify
token scope; or POSTing to `/api/applications/<pk>/tokens/` by providing only `scope`, while token scope; or POSTing to `/api/v2/applications/<pk>/tokens/` by providing only `scope`, while
the parent application will be automatically linked. the parent application will be automatically linked.
Individual tokens will be accessible via their primary keys: Individual tokens will be accessible via their primary keys:
`/api/<version>/me/oauth/tokens/<primary key of a token>/`. Here is a typical token: `/api/<version>/tokens/<primary key of a token>/`. Here is a typical token:
``` ```
{ {
"id": 4, "id": 4,
@@ -120,13 +120,14 @@ Individual tokens will be accessible via their primary keys:
"scope": "read" "scope": "read"
}, },
``` ```
For an OAuth 2 token, the only fully mutable field is `scope`. The `application` field is *immutable For an OAuth 2 token, the only fully mutable fields are `scope` and `description`. The `application`
on update*, and all other fields are totally immutable, and will be auto-populated during creation: field is *immutable on update*, and all other fields are totally immutable, and will be auto-populated
`user` field will be the `user` field of related application; `expires` will be generated according during creation
to Tower configuration setting `OAUTH2_PROVIDER`; `token` and `refresh_token` will be auto-generated * `user` field will be the `user` field of related application
to be non-crashing random strings. Both application tokens and personal access tokens will be shown * `expires` will be generated according to Tower configuration setting `OAUTH2_PROVIDER`
at the `/api/v2/tokens/` endpoint. Personal access tokens can be identified by the applications field * `token` and `refresh_token` will be auto-generated to be non-clashing random strings.
being `null`. Both application tokens and personal access tokens will be shown at the `/api/v2/tokens/`
endpoint. Personal access tokens can be identified by the `application` field being `null`.
On RBAC side: On RBAC side:
- A user will be able to create a token if they are able to see the related application; - A user will be able to create a token if they are able to see the related application;
@@ -139,8 +140,12 @@ On RBAC side:
#### Using OAuth 2 token system as a Personal Access Token (PAT) #### Using OAuth 2 token system as a Personal Access Token (PAT)
The most common usage of OAuth 2 is authenticating users. The `token` field of a token is used The most common usage of OAuth 2 is authenticating users. The `token` field of a token is used
as part of the HTTP authentication header, in the format `Authorization: Bearer <token field value>`. This _Bearer_ as part of the HTTP authentication header, in the format `Authorization: Bearer <token field value>`. This _Bearer_
token can be obtained by doing a curl to the `/api/o/token/` endpoint as shown in `api_o_auth_authorization_root_view.md`. token can be obtained by doing a curl to the `/api/o/token/` endpoint. For example:
```
curl -ku root:reverse -H "Content-Type: application/json" -X POST \
-d '{"description":"Tower CLI","application":null,"scope":"read"}' \
https://localhost:8043/api/v2/users/1/personal_tokens/ | python -m json.tool
```
Here is an example of using that PAT to access an API endpoint using `curl`: Here is an example of using that PAT to access an API endpoint using `curl`:
``` ```
curl -H "Authorization: Bearer kqHqxfpHGRRBXLNCOXxT5Zt3tpJogn" http://localhost:8013/api/v2/credentials/ curl -H "Authorization: Bearer kqHqxfpHGRRBXLNCOXxT5Zt3tpJogn" http://localhost:8013/api/v2/credentials/
@@ -150,7 +155,7 @@ According to OAuth 2 specification, users should be able to acquire, revoke and
token. In AWX the equivalent, and the easiest, way of doing that is creating a token, deleting token. In AWX the equivalent, and the easiest, way of doing that is creating a token, deleting
a token, and deleting a token quickly followed by creating a new one. a token, and deleting a token quickly followed by creating a new one.
The specification also provides standard ways of doing this though. RFC 6749 elaborates The specification also provides standard ways of doing this. RFC 6749 elaborates
on those topics, but in summary, an OAuth 2 token is officially acquired via authorization using on those topics, but in summary, an OAuth 2 token is officially acquired via authorization using
authorization information provided by applications (special application fields mentioned above). authorization information provided by applications (special application fields mentioned above).
There are dedicated endpoints for authorization and acquiring tokens. The `token` endpoint There are dedicated endpoints for authorization and acquiring tokens. The `token` endpoint