External-Mirrors/awx
2
0
Fork 0
mirror of https://github.com/ansible/awx.git synced 2026-01-11 01:57:35 -03: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
Show Stats 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
(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
`GET /api/v2/me/oauth/tokens/?token=0lVJJkolFTwYawHyGkk7NTmSKdzBen`
`GET /api/v2/tokens/?token=0lVJJkolFTwYawHyGkk7NTmSKdzBen`
```text
HTTP 200 OK
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
verify by checking the new token is present
```text
GET /api/v2/me/oauth/tokens/?token=NDInWxGJI4iZgqpsreujjbvzCfJqgR
GET /api/v2/tokens/?token=NDInWxGJI4iZgqpsreujjbvzCfJqgR
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
@ -208,7 +208,7 @@ X-API-Time: 0.021s
```
and the old token is deleted.
```text
GET /api/v2/me/oauth/tokens/?token=omMFLk7UKpB36WN2Qma9H3gbwEBSOc
GET /api/v2/tokens/?token=omMFLk7UKpB36WN2Qma9H3gbwEBSOc
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
@ -234,7 +234,7 @@ an existing token to revoke:
{
"id": 30,
"type": "access_token",
"url": "/api/v2/me/oauth/tokens/30/",
"url": "/api/v2/tokens/30/",
...
"user": null,
"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.
```text
GET /api/v2/me/oauth/tokens/?token=rQONsve372fQwuc2pn76k3IHDCYpi7
GET /api/v2//tokens/?token=rQONsve372fQwuc2pn76k3IHDCYpi7
HTTP 200 OK
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
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
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.
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,
@ -120,13 +120,14 @@ Individual tokens will be accessible via their primary keys:
"scope": "read"
},
```
For an OAuth 2 token, the only fully mutable field is `scope`. The `application` field is *immutable
on update*, and all other fields are totally immutable, and will be auto-populated during creation:
`user` field will be the `user` field of related application; `expires` will be generated according
to Tower configuration setting `OAUTH2_PROVIDER`; `token` and `refresh_token` will be auto-generated
to be non-crashing random strings. Both application tokens and personal access tokens will be shown
at the `/api/v2/tokens/` endpoint. Personal access tokens can be identified by the applications field
being `null`.
For an OAuth 2 token, the only fully mutable fields are `scope` and `description`. The `application`
field is *immutable on update*, and all other fields are totally immutable, and will be auto-populated
during creation
* `user` field will be the `user` field of related application
* `expires` will be generated according to Tower configuration setting `OAUTH2_PROVIDER`
* `token` and `refresh_token` will be auto-generated to be non-clashing random strings.
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:
- 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)
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_
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`:
```
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
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
authorization information provided by applications (special application fields mentioned above).
There are dedicated endpoints for authorization and acquiring tokens. The `token` endpoint