Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 22. Setting up social authentication

Authentication methods simplify logins for end users, offering single sign-ons by using existing login information to sign in to a third party website rather than creating a new login account specifically for that website.

You can configure account authentication in the User Interface and save it to the PostgreSQL database.

You can configure account authentication in automation controller to centrally use OAuth2, while you can configure enterprise-level account authentication for SAML, RADIUS, or even LDAP as a source for authentication information.

For websites, such as Microsoft Azure, Google, or GitHub, which give account information, account information is often implemented by using the OAuth standard.

OAuth is a secure authorization protocol. It is commonly used in conjunction with account authentication to grant third party applications a "session token" allowing them to make API calls to providers on the user’s behalf.

Security Assertion Markup Language (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 RADIUS distributed client/server system enables you to secure networks against unauthorized access. You can implement this in network environments requiring high levels of security while maintaining network access for remote users.

Additional resources

For more information, see the Automation controller configuration section.

22.1. GitHub settings

To set up social authentication for GitHub, you must obtain an OAuth2 key and secret for a web application. To do this, you must first register the new application with GitHub at https://github.com/settings/developers.

To register the application, you must supply it with your homepage URL, which is the Callback URL shown in the Details tab of the GitHub default settings page. The OAuth2 key (Client ID) and secret (Client Secret) are used to supply the required fields in the UI.

Procedure

  1. From the navigation panel, select Settings.
  2. On the Settings page, select GitHub settings from the list of Authentication options.

  3. Select the GitHub Default tab if not already selected.

    The GitHub OAuth2 Callback URL field is already pre-populated and non-editable. When the application is registered, GitHub displays the Client ID and Client Secret.

  4. Click Edit and copy and paste the GitHub Client ID into the GitHub OAuth2 Key field.
  5. Copy and paste the GitHub Client Secret into the GitHub OAuth2 Secret field.
  6. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  7. Click Save.

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen now displays the GitHub logo to enable logging in with those credentials.

image

22.1.1. GitHub Organization settings

When defining account authentication with either an organization or a team within an organization, you should use the specific organization and team settings. Account authentication can be limited by an organization and by a team within an organization.

You can also choose to permit all by specifying non-organization or non-team based settings.

You can limit users who can login to the controller by limiting only those in an organization or on a team within an organization.

To set up social authentication for a GitHub Organization, you must obtain an OAuth2 key and secret for a web application. To do this, you must first register your organization-owned application at https://github.com/organizations/<yourorg>/settings/applications.

To register the application, you must supply it with your Authorization callback URL, which is the Callback URL shown in the Details page. Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) are used to supply the required fields in the UI.

Procedure

  1. From the navigation panel, select Settings.
  2. On the Settings page, select GitHub settings from the list of Authentication options.

  3. Select the GitHub Organization tab.

    The GitHub Organization OAuth2 Callback URL field is already pre-populated and non-editable.

    When the application is registered, GitHub displays the Client ID and Client Secret.

  4. Click Edit and copy and paste GitHub’s Client ID into the GitHub Organization OAuth2 Key field.
  5. Copy and paste GitHub’s Client Secret into the GitHub Organization OAuth2 Secret field.
  6. Enter the name of your GitHub organization, as used in your organization’s URL, for example, https://github.com/<yourorg>/ in the GitHub Organization Name field.
  7. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  8. Click Save.

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen displays the GitHub Organization logo to enable logging in with those credentials.

image

22.1.2. GitHub Team settings

To set up social authentication for a GitHub Team, you must obtain an OAuth2 key and secret for a web application. To do this, you must first register your team-owned application at https://github.com/organizations/<yourorg>/settings/applications. To register the application, you must supply it with your Authorization callback URL, which is the Callback URL shown in the Details page. Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) are used to supply the required fields in the UI.

Procedure

  1. Find the numeric team ID using the GitHub API. The Team ID is used to supply a required field in the UI.
  2. From the navigation panel, select Settings.
  3. On the Settings page, select GitHub settings from the list of Authentication options.

  4. Click the GitHub Team tab.

    The GitHub Team OAuth2 Callback URL field is already pre-populated and non-editable. When the application is registered, GitHub displays the Client ID and Client Secret.

  5. Click Edit and copy and paste GitHub’s Client ID into the GitHub Team OAuth2 Key field.
  6. Copy and paste GitHub’s Client Secret into the GitHub Team OAuth2 Secret field.
  7. Copy and paste GitHub’s team ID in the GitHub Team ID field.
  8. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  9. Click Save

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen displays the GitHub Team logo to enable logging in with those credentials.

image

22.1.3. GitHub Enterprise settings

To set up social authentication for a GitHub Enterprise, you must obtain a GitHub Enterprise URL, an API URL, OAuth2 key and secret for a web application.

To obtain the URLs, refer to the GitHub Enterprise administration documentation.

To obtain the key and secret, you must first register your enterprise-owned application at https://github.com/organizations/<yourorg>/settings/applications.

To register the application, you must supply it with your Authorization callback URL, which is the Callback URL shown in the Details page. Because it is hosted on site and not github.com, you must specify which authentication adapter it communicates with.

Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) are used to supply the required fields in the UI.

Procedure

  1. From the navigation panel, select Settings.
  2. On the Settings page, select GitHub settings from the list of Authentication options.

  3. Click the GitHub Enterprise tab.

    The GitHub Enterprise OAuth2 Callback URL field is already pre-populated and non-editable. When the application is registered, GitHub displays the Client ID and Client Secret.

  4. Click Edit to configure GitHub Enterprise settings.
  5. In the GitHub Enterprise URL field, enter the hostname of the GitHub Enterprise instance, for example, https://github.example.com.
  6. In the GitHub Enterprise API URL field, enter the API URL of the GitHub Enterprise instance, for example, https://github.example.com/api/v3.
  7. Copy and paste GitHub’s Client ID into the GitHub Enterprise OAuth2 Key field.
  8. Copy and paste GitHub’s Client Secret into the GitHub Enterprise OAuth2 Secret field.
  9. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  10. Click Save.

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen displays the GitHub Enterprise logo to enable logging in with those credentials.

image

22.1.4. GitHub Enterprise Organization settings

To set up social authentication for a GitHub Enterprise Organization, you must obtain a GitHub Enterprise Organization URL, an Organization API URL, an Organization OAuth2 key and secret for a web application.

To obtain the URLs, refer to the GitHub documentation on GitHub Enterprise administration.

To obtain the key and secret, you must first register your enterprise organization-owned application at https://github.com/organizations/<yourorg>/settings/applications

To register the application, you must supply it with your Authorization callback URL, which is the Callback URL shown in the Details page.

Because it is hosted on site and not github.com, you must specify which authentication adapter it communicates with.

Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) are used to supply the required fields in the UI.

Procedure

  1. From the navigation panel, select Settings.
  2. On the Settings page, select GitHub settings from the list of Authentication options.

  3. Click the GitHub Enterprise Organization tab.

    The GitHub Enterprise Organization OAuth2 Callback URL field is already pre-populated and non-editable. When the application is registered, GitHub displays the Client ID and Client Secret.

  4. Click Edit to configure GitHub Enterprise Organization settings.
  5. In the GitHub Enterprise Organization URL field, enter the hostname of the GitHub Enterprise Organization instance, for example, https://github.orgexample.com.
  6. In the GitHub Enterprise Organization API URL field, enter the API URL of the GitHub Enterprise Organization instance, for example, https://github.orgexample.com/api/v3.
  7. Copy and paste GitHub’s Client ID into the GitHub Enterprise Organization OAuth2 Key field.
  8. Copy and paste GitHub’s Client Secret into the GitHub Enterprise Organization OAuth2 Secret field.
  9. Enter the name of your GitHub Enterprise organization, as used in your organization’s URL, for example, https://github.com/<yourorg>/ in the GitHub Enterprise Organization Name field.
  10. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  11. Click Save.

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen displays the GitHub Enterprise Organization logo to enable logging in with those credentials.

image

22.1.5. GitHub Enterprise Team settings

To set up social authentication for a GitHub Enterprise team, you must obtain a GitHub Enterprise Organization URL, an Organization API URL, an Organization OAuth2 key and secret for a web application.

To obtain the URLs, refer to the GitHub documentation on GitHub Enterprise administration.

To obtain the key and secret, you must first register your enterprise team-owned application at https://github.com/organizations/<yourorg>/settings/applications.

To register the application, you must supply it with your Authorization callback URL, which is the Callback URL shown in the Details page. Because it is hosted on site and not github.com, you must specify which authentication adapter it communicates with.

Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2key (Client ID) and secret (Client Secret) are used to supply the required fields in the UI.

Procedure

  1. Find the numeric team ID using the GitHub API. The Team ID will be used to supply a required field in the UI.
  2. From the navigation panel, select Settings.
  3. On the Settings page, select GitHub settings from the list of Authentication options.

  4. Click the GitHub Enterprise Team tab.

    The GitHub Enterprise Team OAuth2 Callback URL field is already pre-populated and non-editable. When the application is registered, GitHub displays the Client ID and Client Secret.

  5. Click Edit to configure GitHub Enterprise Team settings.
  6. In the GitHub Enterprise Team URL field, enter the hostname of the GitHub Enterprise team instance, for example, https://github.teamexample.com.
  7. In the GitHub Enterprise Team API URL field, enter the API URL of the GitHub Enterprise team instance, for example, https://github.teamexample.com/api/v3.
  8. Copy and paste GitHub’s Client ID into the GitHub Enterprise Team OAuth2 Key field.
  9. Copy and paste GitHub’s Client Secret into the GitHub Enterprise Team OAuth2 Secret field.
  10. Copy and paste GitHub’s team ID in the GitHub Enterprise Team ID field.
  11. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  12. Click Save.

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen displays the GitHub Enterprise Teams logo to enable logging in with those credentials.

image

22.2. Google OAuth2 settings

To set up social authentication for Google, you must obtain an OAuth2 key and secret for a web application. To do this, you must first create a project and set it up with Google.

For instructions, see Setting up OAuth 2.0 in the Google API Console Help documentation.

If you have already completed the setup process, you can access those credentials by going to the Credentials section of the Google API Manager Console. The OAuth2 key (Client ID) and secret (Client secret) are used to supply the required fields in the UI.

Procedure

  1. From the navigation panel, select Settings.

  2. On the Settings page, select Google OAuth 2 settings from the list of Authentication options.

    The Google OAuth2 Callback URL field is already pre-populated and non-editable.

  3. The following fields are also pre-populated. If not, use the credentials Google supplied during the web application setup process, and look for the values with the same format as the ones shown in the example below:

    • Click Edit and copy and paste Google’s Client ID into the Google OAuth2 Key field.

    • Copy and paste Google’s Client secret into the Google OAuth2 Secret field.

      image

  4. To complete the remaining optional fields, refer to the tooltips in each of the fields for instructions and required format.
  5. For more information on completing the mapping fields, see Organization mapping and Team mapping.
  6. Click Save.

Verification

To verify that the authentication was configured correctly, logout of automation controller. The login screen displays the Google logo to indicate it as an alternate method of logging into automation controller.

image

22.3. Organization mapping

You must control which users are placed into which automation controller organizations based on their username and email address (distinguishing your organization administrators and users from social or enterprise-level authentication accounts).

Dictionary keys are organization names. Organizations are created, if not already present, and if the license permits 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, you can 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 administrators are not updated.
  • If True, all users using account authentication are automatically added as administrators of the organization.
  • If False, no account authentication users are automatically added as administrators of the organization.
  • If a string or list of strings, specifies the usernames and emails for users to be added to the organization, strings beginning and ending with / are compiled into regular expressions. The modifiers i (case-insensitive) and m (multi-line) can 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. The same rules apply as for admins.
  • remove_users: True/False. Defaults to True. The 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", "/^controller-[^@]+?@.*$/i"],
        "users": "/^[^@].*?@example\\.com$/"
    }
}
Copy to Clipboard

Organization mappings can be specified separately for each account authentication backend. If defined, these configurations take precedence over the global configuration above. 

SOCIAL_AUTH_GOOGLE_OAUTH2_ORGANIZATION_MAP = {}
SOCIAL_AUTH_GITHUB_ORGANIZATION_MAP = {}
SOCIAL_AUTH_GITHUB_ORG_ORGANIZATION_MAP = {}
SOCIAL_AUTH_GITHUB_TEAM_ORGANIZATION_MAP = {}
SOCIAL_AUTH_SAML_ORGANIZATION_MAP = {}
Copy to Clipboard

remove_auditors

Before Ansible Automation Platform 2.4, System Auditor rights were revoked when logging in using Single Sign-On (SSO). The user system auditor role was reset at login for SAML users when added in the Ansible Automation Platform user interface.

In Ansible Automation Platform 2.4, you can set a new special user flag to not remove system auditors when logging in, if you added the role in the user interface.

To enable this functionality:

  1. From the navigation panel, select Settings.
  2. Select SAML settings from the list of Authentication options.

  3. Click Edit and update the SAML Organization Attribute Mapping to {"remove_auditors": false}.

    Example

    { "remove": true, "remove_admins": false,
"remove_auditors": false, "saml_admin_attr":
"admin-of", "saml_attr": "organizations" }
    Copy to Clipboard

Verification

  1. Enable debugging in automation controller.

    • From the navigation panel, select Settings.
    • Select Logging settings from the list of System options.
    • Click Edit and select Debug in the Logging Aggregator Level Threshold drop-down menu.
  2. Use SSO to log in to an account with System Auditor privileges.

  3. Verify the results in /var/log/tower/tower.log. Or if you are running Ansible Automation Platform on OpenShift Container Platform, review the web pod logs and look for the following, which occurs when a system auditor logs in, whose role was removed when logging in: 

    2025-01-17 14:19:36,624 DEBUG
[7d3cf3b24d4e4d0e9edd5e2606d6ceba] awx.sso.common
SAML adapter removing user auditor1 permission of
auditor_role from organization Default
    Copy to Clipboard

22.4. Team mapping

Team mapping is the mapping of team members (users) from social authentication accounts. Keys are team names (which are 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 is created if the combination of organization and team name does not exist. The organization is created first if it does not exist. If the license does not permit multiple organizations, the team is always assigned to the single default organization.

  • users: None, True/False, string or list/tuple of strings.

    • If None, team members are not updated.
    • If True, all social authentication users are added as team members.
    • If False, all social authentication users are removed as team members.
  • If a string or list of strings, specifies expressions used to match users, the user is added as a team member if the username or email matches. Strings beginning and ending with / are compiled into regular expressions. The modifiers i (case-insensitive) and m (multi-line) can be specified after the ending /.

remove: True/False. Defaults to True. When True, a user who does not match the preceding rules 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
    }
}
Copy to Clipboard

Team mappings can be specified separately for each account authentication backend, based on which of these you set up. When defined, these configurations take precedence over the preceding global configuration. 

SOCIAL_AUTH_GOOGLE_OAUTH2_TEAM_MAP = {}
SOCIAL_AUTH_GITHUB_TEAM_MAP = {}
SOCIAL_AUTH_GITHUB_ORG_TEAM_MAP = {}
SOCIAL_AUTH_GITHUB_TEAM_TEAM_MAP = {}
SOCIAL_AUTH_SAML_TEAM_MAP = {}
Copy to Clipboard

Uncomment the following line, that is, set SOCIAL_AUTH_USER_FIELDS to an empty list, to prevent new user accounts from being created. 

SOCIAL_AUTH_USER_FIELDS = []
Copy to Clipboard

Only users who have previously logged in to automation controller using social or enterprise-level authentication, or have a user account with a matching email address can then login.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat