diff options
Diffstat (limited to 'docs')
5 files changed, 4 insertions, 453 deletions
diff --git a/docs/docsite/rst/administration/configure_awx_authentication.rst b/docs/docsite/rst/administration/configure_awx_authentication.rst index dd7d188be8..f90576f918 100644 --- a/docs/docsite/rst/administration/configure_awx_authentication.rst +++ b/docs/docsite/rst/administration/configure_awx_authentication.rst @@ -1,4 +1,4 @@ -Through the AWX user interface, you can set up a simplified login through various authentication types: GitHub, Google, LDAP, RADIUS, and SAML. After you create and register your developer application with the appropriate service, you can set up authorizations for them. +Through the AWX user interface, you can set up a simplified login through various authentication types: GitHub, Google, LDAP, and RADIUS. After you create and register your developer application with the appropriate service, you can set up authorizations for them. 1. From the left navigation bar, click **Settings**. @@ -9,7 +9,6 @@ Through the AWX user interface, you can set up a simplified login through variou - :ref:`ag_auth_google_oauth2` - :ref:`LDAP settings <ag_auth_ldap>` - :ref:`ag_auth_radius` -- :ref:`ag_auth_saml` - :ref:`ag_auth_tacacs` Different authentication types require you to enter different information. Be sure to include all the information as required. diff --git a/docs/docsite/rst/administration/ent_auth.rst b/docs/docsite/rst/administration/ent_auth.rst index dbf897378a..73039f4677 100644 --- a/docs/docsite/rst/administration/ent_auth.rst +++ b/docs/docsite/rst/administration/ent_auth.rst @@ -17,7 +17,7 @@ This section describes setting up authentication for the following enterprise sy For LDAP authentication, see :ref:`ag_auth_ldap`. -Azure, RADIUS, SAML, and TACACS+ users are categorized as 'Enterprise' users. The following rules apply to Enterprise users: +Azure, RADIUS, and TACACS+ users are categorized as 'Enterprise' users. The following rules apply to Enterprise users: - 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. @@ -91,435 +91,6 @@ AWX can be configured to centrally use RADIUS as a source for authentication inf 5. Click **Save** when done. -.. _ag_auth_saml: - -SAML settings ----------------- - -.. index:: - pair: authentication; SAML Service Provider - - -SAML allows the exchange of authentication and authorization data between an Identity Provider (IdP - a system of servers that provide the Single Sign On service) and a Service Provider (in this case, AWX). AWX can be configured to talk with SAML in order to authenticate (create/login/logout) AWX users. User Team and Organization membership can be embedded in the SAML response to AWX. - -.. image:: ../common/images/configure-awx-auth-saml-topology.png - :alt: Diagram depicting SAML topology for AWX. - -The following instructions describe AWX as the service provider. - -To setup SAML authentication: - -1. Click **Settings** from the left navigation bar. - -2. On the left side of the Settings window, click **SAML settings** from the list of Authentication options. - -3. The **SAML Assertion Consume Service (ACS) URL** and **SAML Service Provider Metadata URL** fields are pre-populated and are non-editable. Contact the Identity Provider administrator and provide the information contained in these fields. - -4. Click **Edit** and set the **SAML Service Provider Entity ID** to be the same as the **Base URL of the service** field that can be found in the Miscellaneous System settings screen by clicking **Settings** from the left navigation bar. Through the API, it can be viewed in the ``/api/v2/settings/system``, under the ``TOWER_URL_BASE`` variable. The Entity ID can be set to any one of the individual AWX cluster nodes, but it is good practice to set it to the URL of the Service Provider. Ensure that the Base URL matches the FQDN of the load balancer (if used). - -.. note:: - - The Base URL is different for each node in a cluster. Commonly, a load balancer will sit in front of many AWX cluster nodes to provide a single entry point, the AWX Cluster FQDN. The SAML Service Provider must be able establish an outbound connection and route to the AWX Cluster Node or the AWX Cluster FQDN set in the SAML Service Provider Entity ID. - -In this example, the Service Provider is the AWX cluster, and therefore, the ID is set to the AWX Cluster FQDN. - -.. image:: ../common/images/configure-awx-auth-saml-spentityid.png - :alt: Configuring SAML Service Provider Entity ID in AWX. - -5. Create a server certificate for the Ansible cluster. Typically when an Ansible cluster is configured, AWX nodes will be configured to handle HTTP traffic only and the load balancer will be an SSL Termination Point. In this case, an SSL certificate is required for the load balancer, and not for the individual AWX Cluster Nodes. SSL can either be enabled or disabled per individual AWX node, but should be disabled when using an SSL terminated load balancer. It is recommended to use a non-expiring self signed certificate to avoid periodically updating certificates. This way, authentication will not fail in case someone forgets to update the certificate. - -.. note:: - - The **SAML Service Provider Public Certificate** field should contain the entire certificate, including the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". - -If you are using a CA bundle with your certificate, include the entire bundle in this field. - -.. image:: ../common/images/configure-awx-auth-saml-cert.png - :alt: Configuring SAML Service Provider Public Certificate in AWX. - -As an example for public certs: - -:: - - -----BEGIN CERTIFICATE—— - ... cert text ... - -----END CERTIFICATE—— - -6. Create an optional private key for AWX to use as a service provider (SP) and enter it in the **SAML Service Provider Private Key** field. - -As an example for private keys: - -:: - - -----BEGIN PRIVATE KEY-- - ... key text ... - -----END PRIVATE KEY—— - - -7. Provide the IdP with some details about the AWX cluster during the SSO process in the **SAML Service Provider Organization Info** field. - -:: - - { - "en-US": { - "url": "http://www.example.com", - "displayname": "Example", - "name": "example" - } - } - -For example: - -.. image:: ../common/images/configure-awx-auth-saml-org-info.png - :alt: Configuring SAML Organization information in AWX. - -.. note:: - These fields are required in order to properly configure SAML within AWX. - -8. Provide the IdP with the technical contact information in the **SAML Service Provider Technical Contact** field. Do not remove the contents of this field. - -:: - - { - "givenName": "Some User", - "emailAddress": "suser@example.com" - } - -For example: - -.. image:: ../common/images/configure-awx-auth-saml-techcontact-info.png - :alt: Configuring SAML Technical Contact information in AWX. - -9. Provide the IdP with the support contact information in the **SAML Service Provider Support Contact** field. Do not remove the contents of this field. - -:: - - { - "givenName": "Some User", - "emailAddress": "suser@example.com" - } - -For example: - -.. image:: ../common/images/configure-awx-auth-saml-suppcontact-info.png - :alt: Configuring SAML Support Contact information in AWX. - -10. In the **SAML Enabled Identity Providers** field, provide information on how to connect to each Identity Provider listed. AWX expects the following SAML attributes in the example below: - -:: - - Username(urn:oid:0.9.2342.19200300.100.1.1) - Email(urn:oid:0.9.2342.19200300.100.1.3) - FirstName(urn:oid:2.5.4.42) - LastName(urn:oid:2.5.4.4) - -If these attributes are not known, map existing SAML attributes to lastname, firstname, email and username. - -Configure the required keys for each IDp: - - - ``attr_user_permanent_id`` - the unique identifier for the user. It can be configured to match any of the attribute sent from the IdP. Usually, it is set to ``name_id`` if ``SAML:nameid`` attribute is sent to the AWX node or it can be the username attribute, or a custom unique identifier. - - ``entity_id`` - the Entity ID provided by the Identity Provider administrator. The admin creates a SAML profile for AWX and it generates a unique URL. - - ``url`` - the Single Sign On (SSO) URL AWX redirects the user to, when SSO is activated. - - ``x509_cert`` - the certificate provided by the IdP admin generated from the SAML profile created on the Identity Provider. Remove the ``--BEGIN CERTIFICATE--`` and ``--END CERTIFICATE--`` headers, then enter the cert as one non-breaking string. - - Multiple SAML IdPs are supported. Some IdPs may provide user data using attribute names that differ from the default OIDs (https://github.com/omab/python-social-auth/blob/master/social/backends/saml.py). The SAML ``NameID`` is a special attribute used by some Identity Providers to tell the Service Provider (AWX cluster) what the unique user identifier is. If it is used, set the ``attr_user_permanent_id`` to ``name_id`` as shown in the example. Other attribute names may be overridden for each IdP as shown below. - -:: - - { - "myidp": { - "entity_id": "https://idp.example.com", - "url": "https://myidp.example.com/sso", - "x509cert": "" - }, - "onelogin": { - "entity_id": "https://app.onelogin.com/saml/metadata/123456", - "url": "https://example.onelogin.com/trust/saml2/http-post/sso/123456", - "x509cert": "", - "attr_user_permanent_id": "name_id", - "attr_first_name": "User.FirstName", - "attr_last_name": "User.LastName", - "attr_username": "User.email", - "attr_email": "User.email" - } - } - -.. image:: ../common/images/configure-awx-auth-saml-idps.png - :alt: Configuring SAML Identity Providers (IdPs) in AWX. - -.. warning:: - - Do not create a SAML user that shares the same email with another user (including a non-SAML user). Doing so will result in the accounts being merged. Be aware that this same behavior exists for System Admin users, thus a SAML login with the same email address as the System Admin user will login with System Admin privileges. For future reference, you can remove (or add) Admin Privileges based on SAML mappings, as described in subsequent steps. - - -.. note:: - - The IdP provides the email, last name and firstname using the well known SAML urn. The IdP uses a custom SAML attribute to identify a user, which is an attribute that AWX is unable to read. Instead, AWX can understand the unique identifier name, which is the URN. Use the URN listed in the SAML “Name” attribute for the user attributes as shown in the example below. - - .. image:: ../common/images/configure-awx-auth-saml-idps-urn.png - :alt: Configuring SAML Identity Providers (IdPs) in AWX using URNs. - -11. Optionally provide the **SAML Organization Map**. For further detail, see :ref:`ag_org_team_maps`. - -12. AWX can be configured to look for particular attributes that contain Team and Organization membership to associate with users when they log into AWX. The attribute names are defined in the **SAML Organization Attribute Mapping** and the **SAML Team Attribute Mapping** fields. - -**Example SAML Organization Attribute Mapping** - -Below is an example SAML attribute that embeds user organization membership in the attribute *member-of*. - -:: - - <saml2:AttributeStatement> - <saml2:Attribute FriendlyName="member-of" Name="member-of" - NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> - <saml2:AttributeValue>Engineering</saml2:AttributeValue> - <saml2:AttributeValue>IT</saml2:AttributeValue> - <saml2:AttributeValue>HR</saml2:AttributeValue> - <saml2:AttributeValue>Sales</saml2:AttributeValue> - </saml2:Attribute> - <saml2:Attribute FriendlyName="admin-of" Name="admin-of" - NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> - <saml2:AttributeValue>Engineering</saml2:AttributeValue> - </saml2:Attribute> - </saml2:AttributeStatement> - - -Below is the corresponding AWX configuration. - -:: - - { - "saml_attr": "member-of", - "saml_admin_attr": "admin-of", - "remove": true, - "remove_admins": false - } - - -``saml_attr``: is the SAML attribute name where the organization array can be found and ``remove`` is set to **True** to remove a user from all organizations before adding the user to the list of Organizations. To keep the user in whatever Organization(s) they are in while adding the user to the Organization(s) in the SAML attribute, set ``remove`` to **False**. - -``saml_admin_attr``: Similar to the ``saml_attr`` attribute, but instead of conveying organization membership, this attribute conveys admin organization permissions. - -**Example SAML Team Attribute Mapping** - -Below is another example of a SAML attribute that contains a Team membership in a list. - -:: - - <saml:AttributeStatement> - <saml:Attribute - xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500" - x500:Encoding="LDAP" - NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" - Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" - FriendlyName="eduPersonAffiliation"> - <saml:AttributeValue - xsi:type="xs:string">member</saml:AttributeValue> - <saml:AttributeValue - xsi:type="xs:string">staff</saml:AttributeValue> - </saml:Attribute> - </saml:AttributeStatement> - - -:: - - { - "saml_attr": "eduPersonAffiliation", - "remove": true, - "team_org_map": [ - { - "team": "member", - "organization": "Default1" - }, - { - "team": "staff", - "organization": "Default2" - } - ] - } - -- ``saml_attr``: The SAML attribute name where the team array can be found. -- ``remove``: Set ``remove`` to **True** to remove user from all Teams before adding the user to the list of Teams. To keep the user in whatever Team(s) they are in while adding the user to the Team(s) in the SAML attribute, set ``remove`` to **False**. -- ``team_org_map``: An array of dictionaries of the form ``{ "team": "<AWX Team Name>", "organization": "<AWX Org Name>" }`` that defines mapping from AWX Team -> AWX Organization. This is needed because the same named Team can exist in multiple Organizations in AWX. The organization to which a team listed in a SAML attribute belongs to, would be ambiguous without this mapping. - -You could create an alias to override both Teams and Orgs in the **SAML Team Attribute Mapping**. This option becomes very handy in cases when the SAML backend sends out complex group names, like in the example below: - -:: - - { - "remove": false, - "team_org_map": [ - { - "team": "internal:unix:domain:admins", - "organization": "Default", - "team_alias": "Administrators" - }, - { - "team": "Domain Users", - "organization_alias": "OrgAlias", - "organization": "Default" - } - ], - "saml_attr": "member-of" - } - -Once the user authenticates, AWX creates organization and team aliases, as expected. - - -13. Optionally provide team membership mapping in the **SAML Team Map** field. For further detail, see :ref:`ag_org_team_maps`. - -14. Optionally provide security settings in the **SAML Security Config** field. This field is the equivalent to the ``SOCIAL_AUTH_SAML_SECURITY_CONFIG`` field in the API. Refer to the `OneLogin's SAML Python Toolkit`_ for further detail. - -.. _`OneLogin's SAML Python Toolkit`: https://github.com/onelogin/python-saml#settings - -AWX uses the ``python-social-auth`` library when users log in through SAML. This library relies on the ``python-saml`` library to make available the settings for the next two optional fields, **SAML Service Provider Extra Configuration Data** and **SAML IDP to EXTRA_DATA Attribute Mapping**. - -15. The **SAML Service Provider Extra Configuration Data** field is equivalent to the ``SOCIAL_AUTH_SAML_SP_EXTRA`` in the API. Refer to the `python-saml library documentation`_ to learn about the valid service provider extra (``SP_EXTRA``) parameters. - -.. _`python-saml library documentation`: https://github.com/onelogin/python-saml#settings - -16. The **SAML IDP to EXTRA_DATA Attribute Mapping** field is equivalent to the ``SOCIAL_AUTH_SAML_EXTRA_DATA`` in the API. See Python's `SAML Advanced Settings`_ documentation for more information. - -.. _`SAML Advanced Settings`: https://python-social-auth.readthedocs.io/en/latest/backends/saml.html#advanced-settings - -.. _ag_auth_saml_user_flags_attr_map: - -17. The **SAML User Flags Attribute Mapping** field allows you to map SAML roles and attributes to special user flags. The following attributes are valid in this field: - -- ``is_superuser_role``: Specifies one or more SAML roles which will grant a user the superuser flag -- ``is_superuser_attr``: Specifies a SAML attribute which will grant a user the superuser flag -- ``is_superuser_value``: Specifies one or more values required for ``is_superuser_attr`` that is required for the user to be a superuser -- ``remove_superusers``: Boolean indicating if the superuser flag should be removed for users or not. Defaults to ``true``. (See below for more details) -- ``is_system_auditor_role``: Specifies one or more SAML roles which will grant a user the system auditor flag -- ``is_system_auditor_attr``: Specifies a SAML attribute which will grant a user the system auditor flag -- ``is_system_auditor_value``: Specifies one or more values required for ``is_system_auditor_attr`` that is required for the user to be a system auditor -- ``remove_system_auditors``: Boolean indicating if the system_auditor flag should be removed for users or not. Defaults to ``true``. (See below for more details) - - -The ``role`` and ``value`` fields are lists and are `or` logic. So if you specify two roles: `[ "Role 1", "Role 2" ]` and the SAML user has either role the logic will consider them to have the required role for the flag. This is the same with the ``value`` field, if you specify: `[ "Value 1", "Value 2"]` and the SAML user has either value for their attribute the logic will consider their attribute value to have matched. - -If ``role`` and ``attr`` are both specified for either ``superuser`` or ``system_auditor``, the settings for ``attr`` will take precedence over a ``role``. System Admin and System Auditor roles are evaluated at login for a SAML user. If you grant a SAML user one of these roles through the UI and not through the SAML settings, the roles will be removed on the user's next login unless the ``remove`` flag is set to false. The remove flag, if ``false``, will never allow the SAML adapter to remove the corresponding flag from a user. The following table describes how the logic works. - -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Has one or more roles | Has Attr | Has one or more Attr Values | Remove Flag | Previous Flag | Is Flagged | -+=======================+===========+=============================+=============+===============+============+ -| No | No | N/A | True | False | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | No | N/A | False | False | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | No | N/A | True | True | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | No | N/A | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | No | N/A | True | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | No | N/A | False | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | No | N/A | True | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | No | N/A | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Yes | True | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Yes | False | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Yes | True | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Yes | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | No | True | False | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | No | False | False | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | No | True | True | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | No | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Unset | True | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Unset | False | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Unset | True | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| No | Yes | Unset | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Yes | True | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Yes | False | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Yes | True | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Yes | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | No | True | False | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | No | False | False | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | No | True | True | No | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | No | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Unset | True | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Unset | False | False | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Unset | True | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ -| Yes | Yes | Unset | False | True | Yes | -+-----------------------+-----------+-----------------------------+-------------+---------------+------------+ - -Each time a SAML user authenticates to AWX, these checks will be performed and the user flags will be altered as needed. If ``System Administrator`` or ``System Auditor`` is set for a SAML user within the UI, the SAML adapter will override the UI setting based on the rules above. If you would prefer that the user flags for SAML users do not get removed when a SAML user logs in, you can set the ``remove_`` flag to ``false``. With the remove flag set to ``false``, a user flag set to ``true`` through either the UI, API or SAML adapter will not be removed. However, if a user does not have the flag, and the above rules determine the flag should be added, it will be added, even if the flag is ``false``. - -Example:: - - { - "is_superuser_attr": "blueGroups", - "is_superuser_role": ["is_superuser"], - "is_superuser_value": ["cn=My-Sys-Admins,ou=memberlist,ou=mygroups,o=myco.com"], - "is_system_auditor_attr": "blueGroups", - "is_system_auditor_role": ["is_system_auditor"], - "is_system_auditor_value": ["cn=My-Auditors,ou=memberlist,ou=mygroups,o=myco.com"] - } - -18. Click **Save** when done. - -19. To verify that the authentication was configured correctly, load the auto-generated URL found in the **SAML Service Provider Metadata URL** into a browser. It should output XML output, otherwise, it is not configured correctly. - - Alternatively, logout of AWX and the login screen will now display the SAML logo to indicate it as a alternate method of logging into AWX. - - .. image:: ../common/images/configure-awx-auth-saml-logo.png - :alt: AWX login screen displaying the SAML logo for authentication. - - -Transparent SAML Logins -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. index:: - pair: authentication; SAML - pair: SAML; transparent - -For transparent logins to work, you must first get IdP-initiated logins to work. To achieve this: - -1. Set the ``RelayState`` on the IdP to the key of the IdP definition in the ``SAML Enabled Identity Providers`` field as previously described. In the example given above, ``RelayState`` would need to be either ``myidp`` or ``onelogin``. - -2. Once this is working, specify the redirect URL for non-logged-in users to somewhere other than the default AWX login page by using the **Login redirect override URL** field in the Miscellaneous Authentication settings window of the **Settings** menu, accessible from the left navigation bar. This should be set to ``/sso/login/saml/?idp=<name-of-your-idp>`` for transparent SAML login, as shown in the example. - -.. image:: ../common/images/configure-awx-system-login-redirect-url.png - :alt: Configuring the login redirect URL in AWX Miscellaneous Authentication Settings. - -.. note:: - - The above is a sample of a typical IdP format, but may not be the correct format for your particular case. You may need to reach out to your IdP for the correct transparent redirect URL as that URL is not the same for all IdPs. - -3. After transparent SAML login is configured, to log in using local credentials or a different SSO, go directly to ``https://<your-awx-server>/login``. This provides the standard AWX login page, including SSO authentication buttons, and allows you to log in with any configured method. - - -Enabling Logging for SAML -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can enable logging messages for the SAML adapter the same way you can enable logging for LDAP. Refer to the :ref:`ldap_logging` section. - - .. _ag_auth_tacacs: TACACS+ settings diff --git a/docs/docsite/rst/administration/security_best_practices.rst b/docs/docsite/rst/administration/security_best_practices.rst index 8a75fa73b9..8695082fbf 100644 --- a/docs/docsite/rst/administration/security_best_practices.rst +++ b/docs/docsite/rst/administration/security_best_practices.rst @@ -82,7 +82,7 @@ Do not disable SELinux, and do not disable AWX’s existing multi-tenant contain 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 :ref:`LDAP <ag_auth_ldap>`, :ref:`SAML 2.0 <ag_auth_saml>`, and certain :ref:`OAuth providers <ag_social_auth>`. Using this eliminates a source of error when working with permissions. +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 :ref:`LDAP <ag_auth_ldap>` and certain :ref:`OAuth providers <ag_social_auth>`. Using this eliminates a source of error when working with permissions. .. _ag_security_django_password: diff --git a/docs/docsite/rst/administration/social_auth.rst b/docs/docsite/rst/administration/social_auth.rst index b9c33cde2c..9979fb0d39 100644 --- a/docs/docsite/rst/administration/social_auth.rst +++ b/docs/docsite/rst/administration/social_auth.rst @@ -11,12 +11,10 @@ Authentication methods help simplify logins for end users--offering single sign- 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. -Account authentication in AWX can be configured to centrally use OAuth2, while enterprise-level account authentication can be configured for :ref:`Azure <ag_auth_azure>`, :ref:`RADIUS <ag_auth_radius>`, :ref:`SAML <ag_auth_saml>`, or even :ref:`LDAP <ag_auth_ldap>` as a source for authentication information. See :ref:`ag_ent_auth` for more detail. +Account authentication in AWX can be configured to centrally use OAuth2, while enterprise-level account authentication can be configured for :ref:`Azure <ag_auth_azure>`, :ref:`RADIUS <ag_auth_radius>`, or even :ref:`LDAP <ag_auth_ldap>` as a source for authentication information. See :ref:`ag_ent_auth` for more detail. For websites, such as Microsoft Azure, Google or GitHub, that provide account information, account information is often implemented using the OAuth standard. OAuth is a secure authorization protocol which is commonly used in conjunction with account authentication to grant 3rd party applications a "session token" allowing them to make API calls to providers on the user’s behalf. -Security Assertion Markup Language (:ref:`SAML <ag_auth_saml>`) is an XML-based, open-standard data format for exchanging account authentication and authorization data between an identity provider and a service provider. - The :ref:`RADIUS <ag_auth_radius>` distributed client/server system allows you to secure networks against unauthorized access and can be implemented in network environments requiring high levels of security while maintaining network access for remote users. @@ -341,7 +339,6 @@ Organization mappings may be specified separately for each account authenticatio SOCIAL_AUTH_GITHUB_ORGANIZATION_MAP = {} SOCIAL_AUTH_GITHUB_ORG_ORGANIZATION_MAP = {} SOCIAL_AUTH_GITHUB_TEAM_ORGANIZATION_MAP = {} - SOCIAL_AUTH_SAML_ORGANIZATION_MAP = {} Team mapping @@ -387,7 +384,6 @@ Team mappings may be specified separately for each account authentication backen SOCIAL_AUTH_GITHUB_TEAM_MAP = {} SOCIAL_AUTH_GITHUB_ORG_TEAM_MAP = {} SOCIAL_AUTH_GITHUB_TEAM_TEAM_MAP = {} - SOCIAL_AUTH_SAML_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. diff --git a/docs/docsite/rst/release_notes/known_issues.rst b/docs/docsite/rst/release_notes/known_issues.rst index 26f89394ef..ae685f152c 100644 --- a/docs/docsite/rst/release_notes/known_issues.rst +++ b/docs/docsite/rst/release_notes/known_issues.rst @@ -27,7 +27,6 @@ Known Issues pair: known issues; session limit pair: known issues; Ansible Azure dependencies pair: known issues; authentication (reactive user) - pair: known issues; SAML issues pair: known issues; user cannot log in using authentication pair: known issues; login problems with social authentication pair: known issues; OAuth account recreation @@ -111,20 +110,6 @@ Potential security issue using ``X_FORWARDED_FOR`` in ``REMOTE_HOST_HEADERS`` If placing AWX nodes behind some sort of proxy, this may pose a security issue. This approach assumes traffic is always flowing exclusively through your load balancer, and that traffic that circumvents the load balancer is suspect to ``X-Forwarded-For`` header spoofing. -Server error when accessing SAML metadata via hostname -========================================================= - -When AWX is accessed via hostname only (e.g. https://my-little-awx), trying to read the SAML metadata from /sso/metadata/saml/ generates a ``sp_acs_url_invalid`` server error. - -A configuration in which uses SAML when accessing AWX via hostname only instead of an FQDN, is not supported. Doing so will generate an error that is captured in the browser with full traceback information. - - -SAML authentication revokes admin role upon login -================================================== - -Older versions of AWX, the SAML adapter did not evaluate the System Auditor or System Admin roles for a user logging in. Because of this, the login process would not change a user's system roles that were granted through the User Interface. The adapter now has a setting called **SAML User Flags Attribute Mapping** to grant users logging in these roles based on either SAML attributes or roles, and the adapter defaults to removing these roles if unspecified akin to the LDAP adapter. Refer to the :ref:`logic table <ag_auth_saml_user_flags_attr_map>` that shows the relationship between how the role, attribute, and attribute value settings are configured and whether or not a user will be granted the System Admin/Auditor roles. - - Live events status indicators =============================== |