mirror of
https://github.com/ansible/awx.git
synced 2026-02-01 09:38:10 -03:30
Removed UI-focused user docs from AWX. (#15641)
* Replaced with larger graphic.
* Revert "Replaced with larger graphic."
This reverts commit 1214b00052.
* Removed UI-focused user docs from AWX.
* Fixed indentation for release notes
* Removed/updated image files no longer needed.
This commit is contained in:
@@ -5,10 +5,8 @@ Authentication Methods Using the API
|
||||
.. index::
|
||||
pair: session; authentication
|
||||
pair: basic; authentication
|
||||
pair: OAuth 2 Token; authentication
|
||||
pair: SSO; authentication
|
||||
|
||||
This chapter describes different authentication methods, the best use case for each, and examples:
|
||||
This chapter describes basic and session authentication methods, the best use case for each, and examples:
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
@@ -18,7 +16,7 @@ AWX is designed for organizations to centralize and control their automation wit
|
||||
.. _api_session_auth:
|
||||
|
||||
Session Authentication
|
||||
-----------------------
|
||||
======================
|
||||
|
||||
Session authentication is used when logging in directly to AWX’s API or UI to manually create resources (inventory, project, job template) and launch jobs in the browser. With this method, you can remain logged in for a prolonged period of time, not just for that HTTP request, but for instance, when browsing the UI or API in a browser like Chrome or Firefox. When a user logs in, a session cookie is created, which enables the user to remain logged in when navigating to different pages within AWX. Below represents the communication that occurs between the client and server in a session.
|
||||
|
||||
@@ -46,7 +44,7 @@ Using the curl tool, you can see the activity that occurs when you log into AWX.
|
||||
--cookie 'csrftoken=K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \
|
||||
https://<awx-host>/api/login/ -k -D - -o /dev/null
|
||||
|
||||
All of this is done by the AWX when you log in to the UI or API in the browser, and should only be used when authenticating in the browser. For programmatic integration with AWX, see :ref:`api_oauth2_auth`.
|
||||
All of this is done by the AWX when you log in to the UI or API in the browser, and should only be used when authenticating in the browser.
|
||||
|
||||
A typical response might look like:
|
||||
|
||||
@@ -78,13 +76,36 @@ When a user is successfully authenticated with this method, the server will resp
|
||||
|
||||
.. note::
|
||||
|
||||
The session expiration time can be changed by specifying it in the ``SESSION_COOKIE_AGE`` parameter. Refer to :ref:`ag_session_limits` for further detail.
|
||||
The session expiration time can be changed by specifying it in the ``SESSION_COOKIE_AGE`` parameter. Refer to the next section, :ref:`api_session_limits` for further detail.
|
||||
|
||||
.. _api_session_limits:
|
||||
|
||||
Working with Session Limits
|
||||
----------------------------
|
||||
.. index::
|
||||
single: session limits
|
||||
single: session.py
|
||||
pair: SESSIONS_PER_USER; session limits
|
||||
pair: AUTH_BASIC_ENABLED; session limits
|
||||
|
||||
Setting a session limit allows administrators to limit the number of simultaneous sessions per user or per IP address.
|
||||
|
||||
A session is created for each browser that a user uses to log in, which forces the user to log out any extra sessions after they exceed the administrator-defined maximum.
|
||||
|
||||
Session limits may be important, depending on your particular setup. For example, perhaps you only want a single user on your system with a single login per device (where the user could log in on his work laptop, phone, or home computer). In such a case, you would want to create a session limit equal to 1 (one). If the user logs in on his laptop, for example, then logs in using his phone, his laptop session expires (times out) and only the login on the phone persists. Proactive session limits will kick the user out when the session is idle. The default value is **-1**, which disables the maximum sessions allowed altogether, meaning you can have as many sessions without an imposed limit.
|
||||
|
||||
While session counts can be very limited, they can also be expanded to cover as many session logins as are needed by your organization.
|
||||
|
||||
When a user logs in and their login results in other users being logged out, the session limit has been reached and those users who are logged out are notified as to why the logout occurred.
|
||||
|
||||
.. note::
|
||||
To make the best use of session limits, disable ``AUTH_BASIC_ENABLED`` by changing the value to ``False``, as it falls outside of the scope of session limit enforcement.
|
||||
|
||||
|
||||
Basic Authentication
|
||||
---------------------
|
||||
|
||||
Basic Authentication (Basic Auth) is stateless, thus the base64-encoded ``username`` and ``password`` must be sent along with each request via the Authorization header. This can be used for API calls from curl requests, python scripts, or individual requests to the API. :ref:`api_oauth2_auth` is recommended for accessing the API when at all possible.
|
||||
====================
|
||||
|
||||
Basic Authentication (Basic Auth) is stateless, thus the base64-encoded ``username`` and ``password`` must be sent along with each request via the Authorization header. This can be used for API calls from curl requests, python scripts, or individual requests to the API.
|
||||
Example with curl:
|
||||
|
||||
.. code-block:: text
|
||||
@@ -94,94 +115,3 @@ Example with curl:
|
||||
|
||||
For more information about the Basic HTTP Authentication scheme, see `RFC 7617 <https://datatracker.ietf.org/doc/html/rfc7617>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
You can disable the Basic Auth for security purposes from the Miscellaneous Authentication settings of the AWX UI Settings menu:
|
||||
|
||||
.. image:: ../common/images/configure-awx-auth-basic-off.png
|
||||
|
||||
.. _api_oauth2_auth:
|
||||
|
||||
OAuth 2 Token Authentication
|
||||
-----------------------------
|
||||
|
||||
OAuth (Open Authorization) is an open standard for token-based authentication and authorization. OAuth 2 authentication is commonly used when interacting with the AWX API programmatically. Like Basic Auth, an OAuth 2 token is supplied with each API request via the Authorization header. Unlike Basic Auth, OAuth 2 tokens have a configurable timeout and are scopable. Tokens have a configurable expiration time and can be easily revoked for one user or for the entire AWX system by an admin if needed. This can be done with the :ref:`ag_manage_utility_revoke_tokens` management command, which is covered in more detail in |ata| or by using the API as explained in :ref:`ag_oauth2_token_revoke`.
|
||||
|
||||
.. note::
|
||||
|
||||
By default, external users such as those created by SSO are not allowed to generate OAuth tokens for security purposes. This can be changed from the Miscellaneous Authentication settings of the AWX UI Settings menu:
|
||||
|
||||
.. image:: ../common/images/configure-awx-external-tokens-off.png
|
||||
|
||||
The different methods for obtaining OAuth 2 Access Tokens in AWX are:
|
||||
|
||||
- Personal access tokens (PAT)
|
||||
- Application Token: Password grant type
|
||||
- Application Token: Implicit grant type
|
||||
- Application Token: Authorization Code grant type
|
||||
|
||||
For more information on the above methods, see :ref:`ag_oauth2_token_auth` in the |ata|.
|
||||
|
||||
|
||||
First, a user needs to create an OAuth 2 Access Token in the API or in their User’s **Tokens** tab in the UI. For further detail on creating them through the UI, see :ref:`ug_users_tokens`. For the purposes of this example, use the PAT method for creating a token in the API. Upon token creation, the user can set the scope.
|
||||
|
||||
.. note::
|
||||
|
||||
The expiration time of the token can be configured system-wide. See :ref:`ag_use_oauth_pat` for more detail.
|
||||
|
||||
Token authentication is best used for any programmatic use of the AWX API, such as Python scripts or tools like curl, as in the example for creating a PAT (without an associated application) below.
|
||||
|
||||
**Curl Example**
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
curl -u user:password -k -X POST https://<awx-host>/api/v2/tokens/
|
||||
|
||||
|
||||
This call will return JSON data like:
|
||||
|
||||
.. image:: ../common/images/api_oauth2_json_returned_token_value.png
|
||||
|
||||
The value of the ``token`` property is what you can now use to perform a GET request for an AWX resource, e.g., Hosts.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
curl -k -X POST \
|
||||
-H “Content-Type: application/json”
|
||||
-H “Authorization: Bearer <oauth2-token-value>” \
|
||||
https://<awx-host>/api/v2/hosts/
|
||||
|
||||
Similarly, you can launch a job by making a POST to the job template that you want to launch.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
curl -k -X POST \
|
||||
-H "Authorization: Bearer <oauth2-token-value>" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data '{"limit" : "ansible"}' \
|
||||
https://<awx-host>/api/v2/job_templates/14/launch/
|
||||
|
||||
|
||||
**Python Example**
|
||||
|
||||
`awxkit <https://pypi.org/project/awxkit/>`_ is an open source tool that makes it easy to use HTTP requests to access the AWX API.
|
||||
You can have awxkit acquire a PAT on your behalf by using the ``awxkit login`` command. Refer to the :ref:`api_start` for more detail.
|
||||
|
||||
For more information on how to use OAuth 2 in AWX in the context of integrating external applications, see :ref:`ag_oauth2_token_auth` in the |ata|.
|
||||
|
||||
If you need to write custom requests, you can write a Python script using `Python library requests <https://pypi.org/project/requests/>`_, like in this example:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
import requests
|
||||
oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA' # your token value from AWX
|
||||
url = 'https://<awx-host>/api/v2/users/'
|
||||
payload = {}
|
||||
headers = {'Authorization': 'Bearer ' + oauth2_token_value,}
|
||||
|
||||
# makes request to awx user endpoint
|
||||
response = requests.request('GET', url, headers=headers, data=payload,
|
||||
allow_redirects=False, verify=False)
|
||||
|
||||
# prints json returned from awx with formatting
|
||||
print(json.dumps(response.json(), indent=4, sort_keys=True))
|
||||
|
||||
191
docs/docsite/rst/rest_api/awx-manage.rst
Normal file
191
docs/docsite/rst/rest_api/awx-manage.rst
Normal file
@@ -0,0 +1,191 @@
|
||||
.. _ag_manage_utility:
|
||||
|
||||
The *awx-manage* Utility
|
||||
-------------------------------
|
||||
|
||||
.. index::
|
||||
single: awx-manage
|
||||
|
||||
The ``awx-manage`` utility is used to access detailed internal information of AWX. Commands for ``awx-manage`` should run as the ``awx`` user only.
|
||||
|
||||
.. warning::
|
||||
Running awx-manage commands via playbook is not recommended or supported.
|
||||
|
||||
Inventory Import
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. index::
|
||||
single: awx-manage; inventory import
|
||||
|
||||
``awx-manage`` is a mechanism by which an AWX administrator can import inventory directly into AWX, for those who cannot use Custom Inventory Scripts.
|
||||
|
||||
To use ``awx-manage`` properly, you must first create an inventory in AWX to use as the destination for the import.
|
||||
|
||||
For help with ``awx-manage``, run the following command: ``awx-manage inventory_import [--help]``
|
||||
|
||||
The ``inventory_import`` command synchronizes an AWX inventory object with a text-based inventory file, dynamic inventory script, or a directory of one or more of the above as supported by core Ansible.
|
||||
|
||||
When running this command, specify either an ``--inventory-id`` or ``--inventory-name``, and the path to the Ansible inventory source (``--source``).
|
||||
|
||||
::
|
||||
|
||||
awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1
|
||||
|
||||
By default, inventory data already stored in AWX blends with data from the external source. To use only the external data, specify ``--overwrite``. To specify that any existing hosts get variable data exclusively from the ``--source``, specify ``--overwrite_vars``. The default behavior adds any new variables from the external source, overwriting keys that already exist, but preserves any variables that were not sourced from the external data source.
|
||||
|
||||
::
|
||||
|
||||
awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1 --overwrite
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Edits and additions to Inventory host variables persist beyond an inventory sync as long as ``--overwrite_vars`` is **not** set.
|
||||
|
||||
|
||||
Cleanup of old data
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. index::
|
||||
single: awx-manage, data cleanup
|
||||
|
||||
``awx-manage`` has a variety of commands used to clean old data from AWX. The AWX administrators can use the Management Jobs interface for access or use the command line.
|
||||
|
||||
- ``awx-manage cleanup_jobs [--help]``
|
||||
|
||||
This permanently deletes the job details and job output for jobs older than a specified number of days.
|
||||
|
||||
- ``awx-manage cleanup_activitystream [--help]``
|
||||
|
||||
|
||||
Cluster management
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. index::
|
||||
single: awx-manage; cluster management
|
||||
|
||||
.. note::
|
||||
Do not run other ``awx-manage`` commands unless instructed by Red Hat Ansible personnel.
|
||||
|
||||
|
||||
.. _ag_token_utility:
|
||||
|
||||
Token and session management
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. index::
|
||||
single: awx-manage; token management
|
||||
single: awx-manage; session management
|
||||
|
||||
AWX supports the following commands for OAuth2 token management:
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
|
||||
``create_oauth2_token``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use this command to create OAuth2 tokens (specify actual username for ``example_user`` below):
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage create_oauth2_token --user example_user
|
||||
|
||||
New OAuth2 token for example_user: j89ia8OO79te6IAZ97L7E8bMgXCON2
|
||||
|
||||
Make sure you provide a valid user when creating tokens. Otherwise, you will get an error message that you tried to issue the command without specifying a user, or supplying a username that does not exist.
|
||||
|
||||
|
||||
.. _ag_manage_utility_revoke_tokens:
|
||||
|
||||
|
||||
``revoke_oauth2_tokens``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use this command to revoke OAuth2 tokens (both application tokens and personal access tokens (PAT)). By default, it revokes all application tokens (but not their associated refresh tokens), and revokes all personal access tokens. However, you can also specify a user for whom to revoke all tokens.
|
||||
|
||||
To revoke all existing OAuth2 tokens:
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage revoke_oauth2_tokens
|
||||
|
||||
To revoke all OAuth2 tokens & their refresh tokens:
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage revoke_oauth2_tokens --revoke_refresh
|
||||
|
||||
To revoke all OAuth2 tokens for the user with ``id=example_user`` (specify actual username for ``example_user`` below):
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage revoke_oauth2_tokens --user example_user
|
||||
|
||||
To revoke all OAuth2 tokens and refresh token for the user with ``id=example_user``:
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage revoke_oauth2_tokens --user example_user --revoke_refresh
|
||||
|
||||
|
||||
|
||||
``cleartokens``
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use this command to clear tokens which have already been revoked. Refer to `Django's Oauth Toolkit documentation on cleartokens`_ for more detail.
|
||||
|
||||
.. _`Django's Oauth Toolkit documentation on cleartokens`: https://django-oauth-toolkit.readthedocs.io/en/latest/management_commands.html
|
||||
|
||||
|
||||
``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 AD, or the administrator wants to ensure the user can no longer execute jobs due to membership in these groups.
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage expire_sessions
|
||||
|
||||
|
||||
This command terminates all sessions by default. The users associated with those sessions will be consequently logged out. To only expire the sessions of a specific user, you can pass their username using the ``--user`` flag (specify actual username for ``example_user`` below):
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage expire_sessions --user example_user
|
||||
|
||||
|
||||
|
||||
``clearsessions``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use this command to delete all sessions that have expired. Refer to `Django's documentation on clearsessions`_ for more detail.
|
||||
|
||||
.. _`Django's documentation on clearsessions`: https://docs.djangoproject.com/en/2.1/topics/http/sessions/#clearing-the-session-store
|
||||
|
||||
|
||||
|
||||
Analytics gathering
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. index::
|
||||
single: awx-manage; data collection
|
||||
single: awx-manage; analytics gathering
|
||||
|
||||
|
||||
Use this command to gather analytics on-demand outside of the predefined window (default is 4 hours):
|
||||
|
||||
::
|
||||
|
||||
$ awx-manage gather_analytics --ship
|
||||
|
||||
|
||||
For customers with disconnected environments who want to collect usage information about unique hosts automated across a time period, use this command:
|
||||
|
||||
::
|
||||
|
||||
awx-manage host_metric --since YYYY-MM-DD --until YYYY-MM-DD --json
|
||||
|
||||
|
||||
The parameters ``--since`` and ``--until`` specify date ranges and are optional, but one of them has to be present. The ``--json`` flag specifies the output format and is optional.
|
||||
@@ -29,6 +29,7 @@ Need help or want to discuss AWX including the documentation? See the :ref:`Comm
|
||||
access_resources
|
||||
read_only_fields
|
||||
authentication
|
||||
awx-manage
|
||||
api_ref
|
||||
|
||||
.. intro
|
||||
|
||||
Reference in New Issue
Block a user