diff options
Diffstat (limited to 'docs')
21 files changed, 6 insertions, 835 deletions
diff --git a/docs/auth/README.md b/docs/auth/README.md deleted file mode 100644 index fde844e6e6..0000000000 --- a/docs/auth/README.md +++ /dev/null @@ -1,12 +0,0 @@ -This folder describes third-party authentications supported by AWX. These authentications can be configured and enabled inside AWX. - -When a user wants to log into AWX, she can explicitly choose some of the supported authentications to log in instead of AWX's own authentication using username and password. Here is a list of such authentications: -* OIDC (OpenID Connect) - -On the other hand, the other authentication methods use the same types of login info (username and password), but authenticate using external auth systems rather than AWX's own database. If some of these methods are enabled, AWX will try authenticating using the enabled methods *before AWX's own authentication method*. - -## Notes: - * Enterprise users can only be created via the first successful login attempt from remote authentication backend. - * Enterprise users cannot be created/authenticated if non-enterprise users with the same name has already been created in AWX. - * AWX passwords of Enterprise users should always be empty and cannot be set by any user if there are enterprise backends enabled. - * If enterprise backends are disabled, an Enterprise user can be converted to a normal AWX user by setting password field. But this operation is irreversible (the converted AWX user can no longer be treated as Enterprise user). diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md deleted file mode 100644 index 6496adc81d..0000000000 --- a/docs/auth/oauth.md +++ /dev/null @@ -1,403 +0,0 @@ -## Introduction -OAuth2 is the AWX means of token-based authentication. Users -will be able to manage OAuth2 tokens as well as applications, a server-side representation of API -clients used to generate tokens. With OAuth2, a user can authenticate by passing a token as part of -the HTTP authentication header. The token can be scoped to have more restrictive permissions on top of -the base RBAC permissions of the user. Refer to [RFC 6749](https://tools.ietf.org/html/rfc6749) for -more details of OAuth2 specification. - -## Basic Usage - -To get started using OAuth2 tokens for accessing the browsable API using OAuth2, this document will walk through the steps of acquiring a token and using it. - -1. Make an application with `authorization_grant_type` set to 'password'. HTTP POST the following to the `/api/v2/applications/` endpoint (supplying your own `organization-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> -} -``` -2. Make a token with a POST to the `/api/v2/tokens/` endpoint: -``` -{ - "description": "My Access Token", - "application": <application-id>, - "scope": "write" -} -``` -This will return a `<token-value>` that you can use to authenticate with for future requests (this will not be shown again) - -3. Use token to access a resource. We will use `curl` to demonstrate this: -``` -curl -H "Authorization: Bearer <token-value>" -X GET https://<awx>/api/v2/users/ -``` -> The `-k` flag may be needed if you have not set up a CA yet and are using SSL. - -This token can be revoked by making a DELETE on the detail page for that token. All you need is that token's id. For example: -``` -curl -ku <user>:<password> -X DELETE https://<awx>/api/v2/tokens/<pk>/ -``` - -Similarly, using a token: -``` -curl -H "Authorization: Bearer <token-value>" -X DELETE https://<awx>/api/v2/tokens/<pk>/ -k -``` - - -## More Information - -#### Managing OAuth2 Applications and Tokens - -Applications and tokens can be managed as a top-level resource at `/api/v2/applications` and -`/api/v2/tokens`. These resources can also be accessed respective to the user at -`/api/v2/users/N/<resource>`. Applications can be created by making a POST to either `api/v2/applications` -or `/api/v2/users/N/applications`. - -Each OAuth2 application represents a specific API client on the server side. For an API client to use the API via an application token, -it must first have an application and issue an access token. - -Individual applications will be accessible via their primary keys: -`/api/v2/applications/<pk>/`. Here is a typical application: -``` -{ - "id": 1, - "type": "o_auth2_application", - "url": "/api/v2/applications/1/", - "related": { - "user": "/api/v2/users/1/", - "tokens": "/api/v2/applications/1/tokens/", - "activity_stream": "/api/v2/applications/1/activity_stream/" - }, - "summary_fields": { - "user": { - "id": 1, - "username": "root", - "first_name": "", - "last_name": "" - }, - "tokens": { - "count": 1, - "results": [ - { - "scope": "read", - "token": "*************", - "id": 2 - } - ] - } - }, - "created": "2018-02-20T23:06:43.215315Z", - "modified": "2018-02-20T23:06:43.215375Z", - "name": "Default application for root", - "user": 1, - "client_id": "BIyE720WAjr14nNxGXrBbsRsG0FkjgeL8cxNmIWP", - "client_secret": "OdO6TMNAYxUVv4HLitLOnRdAvtClEV8l99zlb8EJEZjlzVNaVVlWiKXicznLDeANwu5qRgeQRvD3AnuisQGCPXXRCx79W1ARQ5cSmc9mrU1JbqW7nX3IZYhLIFgsDH8u", - "client_type": "confidential", - "redirect_uris": "", - "authorization_grant_type": "password", - "skip_authorization": false -}, -``` -In the above example, `user` is the primary key of the user associated to this application and `name` is - a human-readable identifier for the application. The other fields, like `client_id` and -`redirect_uris`, are mainly used for OAuth2 authorization, which will be covered later in the 'Using -OAuth2 Token System' section. - -Fields `client_id` and `client_secret` are immutable identifiers of applications, and will be -generated during creation; Fields `user` and `authorization_grant_type`, on the other hand, are -*immutable on update*, meaning they are required fields on creation, but will become read-only after -that. - -**On RBAC side:** -- System admins will be able to see and manipulate all applications in the system; -- Organization admins will be able to see and manipulate all applications belonging to Organization - members; -- Other normal users will only be able to see, update and delete their own applications, but - cannot create any new applications. - -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/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 at -`/api/v2/tokens/<pk>/`. Here is a typical token: -``` -{ - "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" -}, -``` -For an OAuth2 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` - this field corresponds to the user the token is created for -* `expires` will be generated according to the 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; -- The System Administrator is able to see and manipulate every token in the system; -- Organization admins will be able to see and manipulate all tokens belonging to Organization - members; - System Auditors can see all tokens and applications -- Other normal users will only be able to see and manipulate their own tokens. -> Note: Users can only see the token or refresh-token _value_ at the time of creation ONLY. - -#### Using OAuth2 Token System for Personal Access Tokens (PAT) -The most common usage of OAuth2 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. For example: -``` -curl -ku <user>:<password> -H "Content-Type: application/json" -X POST \ --d '{"description":"Tower CLI", "application":null, "scope":"write"}' \ -https://<awx>/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://<awx>/api/v2/credentials/ -``` - -According to OAuth2 specification, users should be able to acquire, revoke and refresh an access -token. In AWX the equivalent, and 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. RFC 6749 elaborates -on those topics, but in summary, an OAuth2 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 -is also responsible for token refresh, and token revoke can be done by the dedicated token revoke endpoint. - -In AWX, our OAuth2 system is built on top of -[Django Oauth Toolkit](https://django-oauth-toolkit.readthedocs.io/en/latest/), which provides full -support on standard authorization, token revoke and refresh. AWX implements them and puts related -endpoints under `/api/o/` endpoint. Detailed examples on the most typical usage of those endpoints -are available as description text of `/api/o/`. See below for information on Application Access Token usage. -> Note: The `/api/o/` endpoints can only be used for application tokens, and are not valid for personal access tokens. - - -#### Token Scope Mask Over RBAC System - -The scope of an OAuth2 token is a space-separated string composed of keywords like 'read' and 'write'. -These keywords are configurable and used to specify permission level of the authenticated API client. -For the initial OAuth2 implementation, we use the most simple scope configuration, where the only -valid scope keywords are 'read' and 'write'. - -Read and write scopes provide a mask layer over the RBAC permission system of AWX. In specific, a -'write' scope gives the authenticated user the full permissions the RBAC system provides, while 'read' -scope gives the authenticated user only read permissions the RBAC system provides. - -For example, if a user has admin permission to a job template, he/she can both see and modify, launch -and delete the job template if authenticated via session or basic auth. On the other hand, if the user -is authenticated using OAuth2 token, and the related token scope is 'read', the user can only see but -not manipulate or launch the job template, despite being an admin. If the token scope is -'write' or 'read write', she can take full advantage of the job template as its admin. Note that 'write' -implies 'read' as well. - - -## Application Functions - -This page lists OAuth2 utility endpoints used for authorization, token refresh and revoke. -Note endpoints other than `/api/o/authorize/` are not meant to be used in browsers and do not -support HTTP GET. The endpoints here strictly follow -[RFC specs for OAuth2](https://tools.ietf.org/html/rfc6749), so please use that for detailed -reference. Below are some examples to demonstrate the typical usage of these endpoints in -AWX context (note that the AWX net location defaults to `http://localhost:8013` in these examples). - - -#### Application Using `authorization code` Grant Type - -This application grant type is intended to be used when the application is executing on the server. To create -an application named `AuthCodeApp` with the `authorization-code` grant type, -make a POST to the `/api/v2/applications/` endpoint: -```text -{ - "name": "AuthCodeApp", - "user": 1, - "client_type": "confidential", - "redirect_uris": "http://<awx>/api/v2", - "authorization_grant_type": "authorization-code", - "skip_authorization": false -} -``` -You can test the authorization flow out with this new application by copying the `client_id` and URI link into the -homepage [here](http://django-oauth-toolkit.herokuapp.com/consumer/) and click submit. This is just a simple test -application `Django-oauth-toolkit` provides. - -From the client app, the user makes a GET to the Authorize endpoint with the `response_type`, -`client_id`, `redirect_uris`, and `scope`. AWX will respond with the authorization `code` and `state` -to the `redirect_uri` specified in the application. The client application will then make a POST to the -`api/o/token/` endpoint on AWX with the `code`, `client_id`, `client_secret`, `grant_type`, and `redirect_uri`. -AWX will respond with the `access_token`, `token_type`, `refresh_token`, and `expires_in`. For more -information on testing this flow, refer to [django-oauth-toolkit](http://django-oauth-toolkit.readthedocs.io/en/latest/tutorial/tutorial_01.html#test-your-authorization-server). - - -#### Application Using `password` Grant Type - -This is also called the `resource owner credentials grant`. This is for use by users who have -native access to the web app. This should be used when the client is the Resource owner. Suppose -we have an application `Default Application` with grant type `password`: -```text -{ - "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 -} -``` - -Login is not required for `password` grant type, so we can simply use `curl` to acquire a personal access token -via `/api/o/token/`: -```bash -curl -X POST \ - -d "grant_type=password&username=<username>&password=<password>&scope=read" \ - -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569e -IaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ - http://<awx>/api/o/token/ -i -``` -In the above POST request, parameters `username` and `password` are the username and password of the related -AWX user of the underlying application, and the authentication information is of format -`<client_id>:<client_secret>`, where `client_id` and `client_secret` are the corresponding fields of -underlying application. - -Upon success, the access token, refresh token and other information are given in the response body in JSON -format: -```text -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"} -``` - - -## Token Functions - -#### Refresh an Existing Access Token - -Suppose we have an existing access token with refresh token provided: -```text -{ - "id": 35, - "type": "access_token", - ... - "user": 1, - "token": "omMFLk7UKpB36WN2Qma9H3gbwEBSOc", - "refresh_token": "AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z", - "application": 6, - "expires": "2017-12-06T03:46:17.087022Z", - "scope": "read write" -} -``` -The `/api/o/token/` endpoint is used for refreshing the access token: -```bash -curl -X POST \ - -d "grant_type=refresh_token&refresh_token=AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z" \ - -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ - http://<awx>/api/o/token/ -i -``` -In the above POST request, `refresh_token` is provided by `refresh_token` field of the access token -above. The authentication information is of format `<client_id>:<client_secret>`, where `client_id` -and `client_secret` are the corresponding fields of underlying related application of the access token. - -Upon success, the new (refreshed) access token with the same scope information as the previous one is -given in the response body in JSON format: -```text -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"} -``` -Internally, the refresh operation deletes the existing token and a new token is created immediately -after, with information like scope and related application identical to the original one. We can -verify by checking the new token is present and the old token is deleted at the `/api/v2/tokens/` endpoint. - - -#### Revoke an Access Token - -##### Alternatively Revoke Using the /api/o/revoke-token/ Endpoint - -Revoking an access token by this method is the same as deleting the token resource object, but it allows you to delete a token by providing its token value, and the associated `client_id` (and `client_secret` if the application is `confidential`). For example: -```bash -curl -X POST -d "token=rQONsve372fQwuc2pn76k3IHDCYpi7" \ - -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ - http://<awx>/api/o/revoke_token/ -i -``` -`200 OK` means a successful delete. - -We can verify the effect by checking if the token is no longer present -at `/api/v2/tokens/`. - - -## Acceptance Criteria - -* All CRUD operations for OAuth2 applications and tokens should function as described. -* RBAC rules applied to OAuth2 applications and tokens should behave as described. -* A default application should be auto-created for each new user. -* Incoming requests using unexpired OAuth2 token correctly in authentication header should be able - to successfully authenticate themselves. -* Token scope mask over RBAC should work as described. -* AWX configuration setting `OAUTH2_PROVIDER` should be configurable and function as described. -* `/api/o/` endpoint should work as expected. In specific, all examples given in the description - help text should be working (a user following the steps should get expected result). diff --git a/docs/auth/session.md b/docs/auth/session.md deleted file mode 100644 index 1f0f68914a..0000000000 --- a/docs/auth/session.md +++ /dev/null @@ -1,91 +0,0 @@ -## Introduction - -Session-based authentication is the main authentication method, and auth tokens have been replaced by OAuth 2 tokens. - -Session authentication is a safer way of utilizing HTTP(S) cookies. Theoretically, the user can provide authentication information, like username and password, as part of the -`Cookie` header, but this method is vulnerable to cookie hijacks, where crackers can see and steal user -information from the cookie payload. - -Session authentication, on the other hand, sets a single `awx_sessionid` cookie. The `awx_sessionid` -is _a random string which will be mapped to user authentication information by the server_. Crackers who -hijack cookies will only get the `awx_sessionid` itself, which does not imply any critical user info, is valid only for -a limited time, and can be revoked at any time. - -> Note: The CSRF token will by default allow HTTP. To increase security, the `CSRF_COOKIE_SECURE` setting should -> be set to True. - -## Usage - -In session authentication, users log in using the `/api/login/` endpoint. A GET to `/api/login/` displays the -login page of API browser: - - - -Users should enter correct username and password before clicking on the 'LOG IN' button, which fires a POST -to `/api/login/` to actually log the user in. The return code of a successful login is 302, meaning upon -successful login, the browser will be redirected; the redirected destination is determined by the `next` form -item described below. - -It should be noted that the POST body of `/api/login/` is _not_ in JSON, but in HTTP form format. Four items should -be provided in the form: - -- `username`: The username of the user trying to log in. -- `password`: The password of the user trying to log in. -- `next`: The path of the redirect destination, in API browser `"/api/"` is used. -- `csrfmiddlewaretoken`: The CSRF token, usually populated by using Django template `{% csrf_token %}`. - -The `awx_session_id` is provided as a return `Set-Cookie` header. Here is a typical one: - -``` -Set-Cookie: awx_sessionid=lwan8l5ynhrqvps280rg5upp7n3yp6ds; expires=Tue, 21-Nov-2017 16:33:13 GMT; httponly; Max-Age=1209600; Path=/ -``` - -In addition, when the `awx_sessionid` a header called `X-API-Session-Cookie-Name` this header will only be displayed once on a successful logging and denotes the name of the session cookie name. By default this is `awx_sessionid` but can be changed (see below). - -Any client should follow the standard rules of [cookie protocol](https://tools.ietf.org/html/rfc6265) to -parse that header to obtain information about the session, such as session cookie name (`awx_sessionid`), -session cookie value, expiration date, duration, etc. - -The name of the cookie is configurable by Tower Configuration setting `SESSION_COOKIE_NAME` under the category `authentication`. It is a string. The default session cookie name is `awx_sessionid`. - -The duration of the cookie is configurable by Tower Configuration setting `SESSION_COOKIE_AGE` under -category `authentication`. It is an integer denoting the number of seconds the session cookie should -live. The default session cookie age is two weeks. - -After a valid session is acquired, a client should provide the `awx_sessionid` as a cookie for subsequent requests -in order to be authenticated. For example: - -``` -Cookie: awx_sessionid=lwan8l5ynhrqvps280rg5upp7n3yp6ds; ... -``` - -User should use the `/api/logout/` endpoint to log out. In the API browser, a logged-in user can do that by -simply clicking logout button on the nav bar. Under the hood, the click issues a GET to `/api/logout/`. -Upon success, the server will invalidate the current session and the response header will indicate for the client -to delete the session cookie. The user should no longer try using this invalid session. - -The duration of a session is constant. However, a user can extend the expiration date of a valid session -by performing session acquire with the session provided. - -A Tower configuration setting, `SESSIONS_PER_USER` under category `authentication`, is used to set the -maximum number of valid sessions a user can have at the same time. For example, if `SESSIONS_PER_USER` -is set to three and the same user is logged in from five different places, the earliest two sessions created will be invalidated. Tower will try -broadcasting, via websocket, to all available clients. The websocket message body will contain a list of -invalidated sessions. If a client finds its session in that list, it should try logging out. - -Unlike tokens, sessions are meant to be short-lived and UI-only; therefore, whenever a user's password -is updated, all sessions she owned will be invalidated and deleted. - -## Acceptance Criteria - -- Users should be able to log in via the `/api/login/` endpoint by correctly providing all necessary fields. -- Logged-in users should be able to authenticate themselves by providing correct session auth info. -- Logged-in users should be able to log out via `/api/logout/`. -- The duration of a session cookie should be configurable by `SESSION_COOKIE_AGE`. -- The maximum number of concurrent login for one user should be configurable by `SESSIONS_PER_USER`, - and over-limit user sessions should be warned by websocket. -- When a user's password is changed, all her sessions should be invalidated and deleted. -- User should not be able to authenticate by HTTPS(S) request nor websocket connection using invalid - sessions. -- No existing behavior, like job runs, inventory updates or callback receiver, should be affected - by session auth. diff --git a/docs/credentials/extract_credentials.md b/docs/credentials/extract_credentials.md index 12fe0fea5c..e8394198a5 100644 --- a/docs/credentials/extract_credentials.md +++ b/docs/credentials/extract_credentials.md @@ -15,7 +15,7 @@ If necessary, credentials and encrypted settings can be extracted using the AWX $ awx-manage shell_plus >>> from awx.main.utils import decrypt_field >>> print(decrypt_field(Credential.objects.get(name="my private key"), "ssh_key_data")) # Example for a credential ->>> print(decrypt_field(Setting.objects.get(key='SOCIAL_AUTH_OIDC_SECRET'), 'value')) # Example for a setting +>>> print(decrypt_field(Setting.objects.get(key='setting'), 'value')) # Example for a setting ``` If you are running a kubernetes based deployment, you can execute awx-manage like this: diff --git a/docs/docsite/rst/administration/awx-manage.rst b/docs/docsite/rst/administration/awx-manage.rst index a468a4633d..3de9e6cb81 100644 --- a/docs/docsite/rst/administration/awx-manage.rst +++ b/docs/docsite/rst/administration/awx-manage.rst @@ -146,7 +146,7 @@ Use this command to clear tokens which have already been revoked. Refer to `Djan ``expire_sessions`` ^^^^^^^^^^^^^^^^^^^^^^^^ -Use this command to terminate all sessions or all sessions for a specific user. Consider using this command when a user changes role in an organization, is removed from assorted groups in LDAP/AD, or the administrator wants to ensure the user can no longer execute jobs due to membership in these groups. +Use this command to terminate all sessions or all sessions for a specific user. Consider using this command when a user changes role in an organization, is removed from assorted groups in AD, or the administrator wants to ensure the user can no longer execute jobs due to membership in these groups. :: diff --git a/docs/docsite/rst/administration/configure_awx.rst b/docs/docsite/rst/administration/configure_awx.rst index 3087ab31c0..3c7c8fecf5 100644 --- a/docs/docsite/rst/administration/configure_awx.rst +++ b/docs/docsite/rst/administration/configure_awx.rst @@ -10,24 +10,10 @@ AWX Configuration You can configure various AWX settings within the Settings screen in the following tabs: -.. image:: ../common/images/ug-settings-menu-screen.png - :alt: Screenshot of the AWX settings menu screen. - Each tab contains fields with a **Reset** button, allowing you to revert any value entered back to the default value. **Reset All** allows you to revert all the values to their factory default values. **Save** applies changes you make, but it does not exit the edit dialog. To return to the Settings screen, click **Settings** from the left navigation bar or use the breadcrumbs at the top of the current view. - -Authentication -================= -.. index:: - single: social authentication - single: authentication - pair: configuration; authentication - -.. include:: ./configure_awx_authentication.rst - - .. _configure_awx_jobs: Jobs @@ -66,7 +52,7 @@ The System tab allows you to define the base URL for the AWX host, configure ale 2. The right side of the Settings window is a set of configurable System settings. Select from the following options: - **Miscellaneous System settings**: enable activity streams, specify the default execution environment, define the base URL for the AWX host, enable AWX administration alerts, set user visibility, define analytics, specify usernames and passwords, and configure proxies. - - **Miscellaneous Authentication settings**: configure options associated with authentication methods (built-in or SSO), sessions (timeout, number of sessions logged in, tokens), and social authentication mapping. + - **Miscellaneous Authentication settings**: configure options associated with authentication methods and sessions (timeout, number of sessions logged in, tokens). - **Logging settings**: configure logging options based on the type you choose: .. image:: ../common/images/configure-awx-system-logging-types.png diff --git a/docs/docsite/rst/administration/configure_awx_authentication.rst b/docs/docsite/rst/administration/configure_awx_authentication.rst deleted file mode 100644 index fdcf35d478..0000000000 --- a/docs/docsite/rst/administration/configure_awx_authentication.rst +++ /dev/null @@ -1,7 +0,0 @@ -1. From the left navigation bar, click **Settings**. - -2. The left side of the Settings window is a set of configurable Authentication settings. Select from the following options: - -Different authentication types require you to enter different information. Be sure to include all the information as required. - -3. Click **Save** to apply the settings or **Cancel** to abandon the changes.
\ No newline at end of file diff --git a/docs/docsite/rst/administration/ent_auth.rst b/docs/docsite/rst/administration/ent_auth.rst deleted file mode 100644 index aaec518c58..0000000000 --- a/docs/docsite/rst/administration/ent_auth.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _ag_ent_auth: - -Setting up Enterprise Authentication -================================================== - - -.. index:: - single: enterprise authentication - single: authentication - -This section describes setting up authentication for the following enterprise systems: - -.. contents:: - :local: - -- Enterprise users can only be created via the first successful login attempt from remote authentication backend. -- Enterprise users cannot be created/authenticated if non-enterprise users with the same name has already been created in AWX. -- AWX passwords of enterprise users should always be empty and cannot be set by any user if there are enterprise backend-enabled. -- If enterprise backends are disabled, an enterprise user can be converted to a normal AWX user by setting the password field. However, this operation is irreversible, as the converted AWX user can no longer be treated as enterprise user. diff --git a/docs/docsite/rst/administration/index.rst b/docs/docsite/rst/administration/index.rst index 247bc6db4a..7a4ac043da 100644 --- a/docs/docsite/rst/administration/index.rst +++ b/docs/docsite/rst/administration/index.rst @@ -39,10 +39,7 @@ Need help or want to discuss AWX including the documentation? See the :ref:`Comm configure_awx isolation_variables oauth2_token_auth - social_auth - ent_auth authentication_timeout - kerberos_auth session_limits custom_rebranding troubleshooting diff --git a/docs/docsite/rst/administration/kerberos_auth.rst b/docs/docsite/rst/administration/kerberos_auth.rst deleted file mode 100644 index 96f5855b74..0000000000 --- a/docs/docsite/rst/administration/kerberos_auth.rst +++ /dev/null @@ -1,117 +0,0 @@ -User Authentication with Kerberos -================================== - -.. index:: - pair: user authentication; Kerberos - pair: Kerberos; Active Directory (AD) - -User authentication via Active Directory (AD), also referred to as authentication through Kerberos, is supported through AWX. - -To get started, first set up the Kerberos packages in AWX so that you can successfully generate a Kerberos ticket. To install the packages, use the following steps: - -:: - - yum install krb5-workstation - yum install krb5-devel - yum install krb5-libs - -Once installed, edit the ``/etc/krb5.conf`` file, as follows, to provide the address of the AD, the domain, etc.: - -:: - - [logging] - default = FILE:/var/log/krb5libs.log - kdc = FILE:/var/log/krb5kdc.log - admin_server = FILE:/var/log/kadmind.log - - [libdefaults] - default_realm = WEBSITE.COM - dns_lookup_realm = false - dns_lookup_kdc = false - ticket_lifetime = 24h - renew_lifetime = 7d - forwardable = true - - [realms] - WEBSITE.COM = { - kdc = WIN-SA2TXZOTVMV.website.com - admin_server = WIN-SA2TXZOTVMV.website.com - } - - [domain_realm] - .website.com = WEBSITE.COM - website.com = WEBSITE.COM - -After the configuration file has been updated, you should be able to successfully authenticate and get a valid token. -The following steps show how to authenticate and get a token: - -:: - - [root@ip-172-31-26-180 ~]# kinit username - Password for username@WEBSITE.COM: - [root@ip-172-31-26-180 ~]# - - Check if we got a valid ticket. - - [root@ip-172-31-26-180 ~]# klist - Ticket cache: FILE:/tmp/krb5cc_0 - Default principal: username@WEBSITE.COM - - Valid starting Expires Service principal - 01/25/16 11:42:56 01/25/16 21:42:53 krbtgt/WEBSITE.COM@WEBSITE.COM - renew until 02/01/16 11:42:56 - [root@ip-172-31-26-180 ~]# - -Once you have a valid ticket, you can check to ensure that everything is working as expected from command line. To test this, make sure that your inventory looks like the following: - -:: - - [windows] - win01.WEBSITE.COM - - [windows:vars] - ansible_user = username@WEBSITE.COM - ansible_connection = winrm - ansible_port = 5986 - -You should also: - -- Ensure that the hostname is the proper client hostname matching the entry in AD and is not the IP address. - -- In the username declaration, ensure that the domain name (the text after ``@``) is properly entered with regard to upper- and lower-case letters, as Kerberos is case sensitive. For AWX, you should also ensure that the inventory looks the same. - - -.. note:: - - If you encounter a ``Server not found in Kerberos database`` error message, and your inventory is configured using FQDNs (**not IP addresses**), ensure that the service principal name is not missing or mis-configured. - - -Now, running a playbook should run as expected. You can test this by running the playbook as the ``awx`` user. - -Once you have verified that playbooks work properly, integration with AWX is easy. Generate the Kerberos ticket as the ``awx`` user and AWX should automatically pick up the generated ticket for authentication. - -.. note:: - - The python ``kerberos`` package must be installed. Ansible is designed to check if ``kerberos`` package is installed and, if so, it uses kerberos authentication. - - -AD and Kerberos Credentials ------------------------------- - -Active Directory only: - -- If you are only planning to run playbooks against Windows machines with AD usernames and passwords as machine credentials, you can use "user@<domain>" format for the username and an associated password. - -With Kerberos: - -- If Kerberos is installed, you can create a machine credential with the username and password, using the "user@<domain>" format for the username. - - -Working with Kerberos Tickets -------------------------------- - -Ansible defaults to automatically managing Kerberos tickets when both the username and password are specified in the machine credential for a host that is configured for kerberos. A new ticket is created in a temporary credential cache for each host, before each task executes (to minimize the chance of ticket expiration). The temporary credential caches are deleted after each task, and will not interfere with the default credential cache. - -To disable automatic ticket management (e.g., to use an existing SSO ticket or call ``kinit`` manually to populate the default credential cache), set ``ansible_winrm_kinit_mode=manual`` via the inventory. - -Automatic ticket management requires a standard kinit binary on the control host system path. To specify a different location or binary name, set the ``ansible_winrm_kinit_cmd`` inventory variable to the fully-qualified path to an MIT krbv5 kinit-compatible binary. diff --git a/docs/docsite/rst/administration/oauth2_token_auth.rst b/docs/docsite/rst/administration/oauth2_token_auth.rst index 7ab83a16e6..d99604cf6f 100644 --- a/docs/docsite/rst/administration/oauth2_token_auth.rst +++ b/docs/docsite/rst/administration/oauth2_token_auth.rst @@ -449,11 +449,6 @@ Revoking an access token by this method is the same as deleting the token resour The special OAuth 2 endpoints only support using the ``x-www-form-urlencoded`` **Content-type**, so as a result, none of the ``api/o/*`` endpoints accept ``application/json``. -.. note:: - - The **Allow External Users to Create Oauth2 Tokens** (``ALLOW_OAUTH2_FOR_EXTERNAL_USERS`` in the API) setting is disabled by default. External users refer to users authenticated externally with services like SSO services. This setting ensures external users cannot *create* their own tokens. If you enable then disable it, any tokens created by external users in the meantime will still exist, and are not automatically revoked. - - Alternatively, you can use the ``manage`` utility, :ref:`ag_manage_utility_revoke_tokens`, to revoke tokens as described in the :ref:`ag_token_utility` section. diff --git a/docs/docsite/rst/administration/security_best_practices.rst b/docs/docsite/rst/administration/security_best_practices.rst index e5d7395593..14d62cb989 100644 --- a/docs/docsite/rst/administration/security_best_practices.rst +++ b/docs/docsite/rst/administration/security_best_practices.rst @@ -79,12 +79,6 @@ Existing security functionality Do not disable SELinux, and do not disable AWX’s existing multi-tenant containment. Use AWX’s role-based access control (RBAC) to delegate the minimum level of privileges required to run automation. Use Teams in AWX to assign permissions to groups of users rather than to users individually. See :ref:`rbac-ug` in the |atu|. -External account stores -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Maintaining a full set of users just in AWX can be a time-consuming task in a large organization, prone to error. AWX supports connecting to external account sources via certain :ref:`OAuth providers <ag_social_auth>`. Using this eliminates a source of error when working with permissions. - - .. _ag_security_django_password: Django password policies diff --git a/docs/docsite/rst/administration/social_auth.rst b/docs/docsite/rst/administration/social_auth.rst deleted file mode 100644 index 603bf5ee1b..0000000000 --- a/docs/docsite/rst/administration/social_auth.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _ag_social_auth: - -Setting up Social Authentication -================================== - -.. index:: - single: social authentication - single: authentication - -Authentication methods help simplify logins for end users--offering single sign-ons using existing login information to sign into a third party website rather than creating a new login account specifically for that website. - -Account authentication can be configured in the AWX User Interface and saved to the PostgreSQL database. For instructions, refer to the :ref:`ag_configure_awx` section. - -.. _ag_org_team_maps: - -Organization and Team Mapping ---------------------------------- - -.. index:: - single: organization mapping - pair: authentication; organization mapping - pair: authentication; team mapping - single: team mapping - -Organization mapping -~~~~~~~~~~~~~~~~~~~~~ - -You will need to control which users are placed into which organizations based on their username and email address (mapping out your organization admins/users from social or enterprise-level authentication accounts). - -Dictionary keys are organization names. Organizations will be created, if not already present and if the license allows for multiple organizations. Otherwise, the single default organization is used regardless of the key. - -Values are dictionaries defining the options for each organization's membership. For each organization, it is possible to specify which users are automatically users of the organization and also which users can administer the organization. - -**admins**: None, True/False, string or list/tuple of strings. - - - If **None**, organization admins will not be updated. - - If **True**, all users using account authentication will automatically be added as admins of the organization. - - If **False**, no account authentication users will be automatically added as admins of the organization. - - If a string or list of strings, specifies the usernames and emails for users who will be added to the organization. Strings beginning and ending with ``/`` will be compiled into regular expressions; modifiers ``i`` (case-insensitive) and ``m`` (multi-line) may be specified after the ending ``/``. - -**remove_admins**: True/False. Defaults to **True**. - - - When **True**, a user who does not match is removed from the organization's administrative list. - -**users**: None, True/False, string or list/tuple of strings. Same rules apply as for **admins**. - -**remove_users**: True/False. Defaults to **True**. Same rules apply as for **remove_admins**. - - -:: - - { - "Default": { - "users": true - }, - "Test Org": { - "admins": ["admin@example.com"], - "users": true - }, - "Test Org 2": { - "admins": ["admin@example.com", "/^awx-[^@]+?@.*$/i"], - "users": "/^[^@].*?@example\\.com$/" - } - } - -Organization mappings may be specified separately for each account authentication backend. If defined, these configurations will take precedence over the global configuration above. - -:: - -Team mapping -~~~~~~~~~~~~~~ - -Team mapping is the mapping of team members (users) from social auth accounts. Keys are team names (will be created if not present). Values are dictionaries of options for each team's membership, where each can contain the following parameters: - -**organization**: string. The name of the organization to which the team -belongs. The team will be created if the combination of organization and -team name does not exist. The organization will first be created if it -does not exist. If the license does not allow for multiple organizations, -the team will always be assigned to the single default organization. - -**users**: None, True/False, string or list/tuple of strings. - - - If **None**, team members will not be updated. - - If **True**/**False**, all social auth users will be added/removed as team members. - - If a string or list of strings, specifies expressions used to match users. User will be added as a team member if the username or email matches. Strings beginning and ending with ``/`` will be compiled into regular expressions; modifiers ``i`` (case-insensitive) and ``m`` (multi-line) may be specified after the ending ``/``. - -**remove**: True/False. Defaults to **True**. When **True**, a user who does not match the rules above is removed from the team. - -:: - - { - "My Team": { - "organization": "Test Org", - "users": ["/^[^@]+?@test\\.example\\.com$/"], - "remove": true - }, - "Other Team": { - "organization": "Test Org 2", - "users": ["/^[^@]+?@test\\.example\\.com$/"], - "remove": false - } - } - - -Team mappings may be specified separately for each account authentication backend, based on which of these you setup. When defined, these configurations take precedence over the global configuration above. - -:: - - SOCIAL_AUTH_GITHUB_TEAM_MAP = {} - SOCIAL_AUTH_GITHUB_ORG_TEAM_MAP = {} - SOCIAL_AUTH_GITHUB_TEAM_TEAM_MAP = {} - -Uncomment the line below (i.e. set ``SOCIAL_AUTH_USER_FIELDS`` to an empty list) to prevent new user accounts from being created. Only users who have previously logged in to AWX using social or enterprise-level authentication or have a user account with a matching email address will be able to login. - -:: - - SOCIAL_AUTH_USER_FIELDS = [] - diff --git a/docs/docsite/rst/common/images/ug-settings-menu-screen-authentication.png b/docs/docsite/rst/common/images/ug-settings-menu-screen-authentication.png Binary files differdeleted file mode 100644 index ab98c73d5d..0000000000 --- a/docs/docsite/rst/common/images/ug-settings-menu-screen-authentication.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-settings-menu-screen.png b/docs/docsite/rst/common/images/ug-settings-menu-screen.png Binary files differdeleted file mode 100644 index 081d0db8b0..0000000000 --- a/docs/docsite/rst/common/images/ug-settings-menu-screen.png +++ /dev/null diff --git a/docs/docsite/rst/common/settings-menu.rst b/docs/docsite/rst/common/settings-menu.rst index b47179ea49..cfce9c5df6 100644 --- a/docs/docsite/rst/common/settings-menu.rst +++ b/docs/docsite/rst/common/settings-menu.rst @@ -5,9 +5,6 @@ pair: settings menu; configure the controller -To enter the Settings window for AWX, click **Settings** from the left navigation bar. This page allows you to modify your AWX configuration, such as settings associated with authentication, jobs, system, and user interface. - -.. image:: ../common/images/ug-settings-menu-screen.png - :alt: The main settings window for AWX. +To enter the Settings window for AWX, click **Settings** from the left navigation bar. This page allows you to modify your AWX configuration, such as settings associated with jobs, system, and user interface. For more information on configuring these settings, refer to :ref:`ag_configure_awx` section of the |ata|.
\ No newline at end of file diff --git a/docs/docsite/rst/quickstart/examine_dashboard.rst b/docs/docsite/rst/quickstart/examine_dashboard.rst index 00bfcde955..cbe645e614 100644 --- a/docs/docsite/rst/quickstart/examine_dashboard.rst +++ b/docs/docsite/rst/quickstart/examine_dashboard.rst @@ -42,9 +42,6 @@ The very last item in the navigation bar is **Settings**, which provides access The Settings page allows administrators to configure authentication, jobs, system-level attributes, and customize the user interface. Refer to :ref:`ag_configure_awx` section for more detail. -.. image:: ../common/images/ug-settings-menu-screen.png - - Regardless of the window or action you're performing, the very top of each page next to the your user icon is the About (|about|) icon, which provides you the versions of AWX and Ansible you are currently running. .. |about| image:: ../common/images/help-about-icon.png diff --git a/docs/docsite/rst/release_notes/known_issues.rst b/docs/docsite/rst/release_notes/known_issues.rst index d92590a02b..0d51430bd9 100644 --- a/docs/docsite/rst/release_notes/known_issues.rst +++ b/docs/docsite/rst/release_notes/known_issues.rst @@ -27,8 +27,6 @@ Known Issues pair: known issues; Ansible Azure dependencies pair: known issues; authentication (reactive user) pair: known issues; user cannot log in using authentication - pair: known issues; login problems with social authentication - pair: known issues; OAuth account recreation pair: known issues; login via http pair: known issues; web sockets in safari pair: known issues; browser auto-complete @@ -173,12 +171,6 @@ Database server installed on nodes All nodes in the cluster get a database server even if the nodes do not have a database. This is unexpected and may take up space. -Reactivating OAuth authentication accounts which have been deleted -=================================================================== - -Once a user who logs in using social authentication has been deleted, the user will not be able to login again or be recreated until the system administrator runs a ``cleanup_deleted`` action with ``days=0`` to allow users to login again. Once ``cleanup_deleted`` has been run, AWX must be restarted. Accounts which have been deleted prior to having the ``cleanup_deleted`` action run will receive a "Your account is inactive" message upon trying to login. - - Using vaulted variables in inventory sourced from a project =========================================================== diff --git a/docs/docsite/rst/userguide/glossary.rst b/docs/docsite/rst/userguide/glossary.rst index f55659f69c..d0279cdfb7 100644 --- a/docs/docsite/rst/userguide/glossary.rst +++ b/docs/docsite/rst/userguide/glossary.rst @@ -61,7 +61,7 @@ Glossary A collection of hosts against which Jobs may be launched. Inventory Script - A very simple program (or a complicated one) that looks up hosts, group membership for hosts, and variable information from an external resource--whether that be a SQL database, a CMDB solution, or something like LDAP. This concept was adapted from Puppet (where it is called an “External Nodes Classifier”) and works more or less exactly the same way. + A very simple program (or a complicated one) that looks up hosts, group membership for hosts, and variable information from an external resource--whether that be a SQL database or a CMDB solution. This concept was adapted from Puppet (where it is called an “External Nodes Classifier”) and works more or less exactly the same way. Inventory Source Information about a cloud or other script that should be merged into the current inventory group, resulting in the automatic population of Groups, Hosts, and variables about those groups and hosts. diff --git a/docs/docsite/rst/userguide/projects.rst b/docs/docsite/rst/userguide/projects.rst index 73c37515bd..5a715d7b51 100644 --- a/docs/docsite/rst/userguide/projects.rst +++ b/docs/docsite/rst/userguide/projects.rst @@ -473,7 +473,7 @@ Before AWX can use |ah| as the default source for collections content, you need - **Galaxy Server URL** = ``https://cloud.redhat.com/api/automation-hub/`` - - **AUTH SEVER URL** = ``https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`` + - **AUTH SERVER URL** = ``https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`` 4. To use a private |ah|, create an |ah| credential using a token retrieved from the Repo Management dashboard of your local |ah| and pointing to the published repo URL as shown: diff --git a/docs/tower_configuration.md b/docs/tower_configuration.md index a5aea85c91..69bf73f3fb 100644 --- a/docs/tower_configuration.md +++ b/docs/tower_configuration.md @@ -5,26 +5,6 @@ AWX configuration gives AWX users the ability to adjust multiple runtime paramet #### To Use: The REST endpoint for CRUD operations against AWX configurations can be found at `/api/v2/settings/`. GETing to that endpoint will return a list of available AWX configuration categories and their URLs, such as `"system": "/api/v2/settings/system/"`. The URL given to each category is the endpoint for CRUD operations against individual settings under that category. -Here is a typical AWX configuration category GET response: -``` -GET /api/v2/settings/oidc/ -HTTP 200 OK -Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS -Content-Type: application/json -Vary: Accept -X-API-Node: tower -X-API-Query-Count: 6 -X-API-Query-Time: 0.004s -X-API-Time: 0.026s - -{ - "SOCIAL_AUTH_OIDC_KEY": null, - "SOCIAL_AUTH_OIDC_SECRET": "", - "SOCIAL_AUTH_OIDC_OIDC_ENDPOINT": "", - "SOCIAL_AUTH_OIDC_VERIFY_SSL": true -} -``` - The returned body is a JSON of key-value pairs, where the key is the name of the AWX configuration setting, and the value is the value of that setting. To update the settings, simply update setting values and PUT/PATCH to the same endpoint. #### To Develop: |
