Installing and Configuring Central Authentication for the Ansible Automation Platform
Enable central authentication functions for your Ansible Automation Platform
Abstract
Preface
Ansible Automation Platform Central Authentication is a third-party identity provider (idP) solution, allowing for a simplified single sign-on solution that can be used across the Ansible Automation Platform. Platform administrators can utilize central authentication to test connectivity and authentication, as well as onboard new users and manage user permissions by configuring and assigning them to groups. Along with OpenID Connect-based and LDAP support, central authentication also provides a supported REST API which can be used to bootstrap customer usage.
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Providing feedback on Red Hat documentation
If you have a suggestion to improve this documentation, or find an error, please contact technical support at https://access.redhat.com to create an issue on the Ansible Automation Platform Jira project using the docs-product component.
Chapter 1. Ansible Automation Platform Central Authentication for automation hub
To enable Ansible Automation Platform Central Authentication for your automation hub, start by downloading the Red Hat Ansible Automation Platform installer then proceed with the necessary set up procedures as detailed in this guide.
The installer in this guide will install central authentication for a basic standalone deployment. Standalone mode only runs one central authentication server instance, and thus will not be usable for clustered deployments. Standalone mode can be useful to test drive and play with the features of central authentication, but it is not recommended that you use standalone mode in production as you will only have a single point of failure.
To install central authentication in a different deployment mode, please see this guide for more deployment options.
1.1. System Requirements
There are several minimum requirements to install and run Ansible Automation Platform Central Authentication:
- Any operating system that runs Java
- Java 8 JDK
- zip or gzip and tar
- At least 512mb of RAM
- At least 1gb of disk space
- A shared external database like PostgreSQL, MySQL, Oracle, etc. if you want to run central authentication in a cluster. See the Database Configuration section of the Red Hat Single Sign-On Server Installation and Configuration guide for more information.
- Network multicast support on your machine if you want to run in a cluster. central authentication can be clustered without multicast, but this requires some configuration changes. See the Clustering section of the Red Hat Single Sign-On Server Installation and Configuration guide for more information.
-
On Linux, it is recommended to use
/dev/urandom
as a source of random data to prevent central authentication hanging due to lack of available entropy, unless/dev/random
usage is mandated by your security policy. To achieve that on Oracle JDK 8 and OpenJDK 8, set thejava.security.egd
system property on startup tofile:/dev/urandom
.
1.2. Installing Ansible Automation Platform Central Authentication for use with automation hub
The Ansible Automation Platform Central Authentication installation will be included with your Red Hat Ansible Automation Platform installer. Install the Ansible Automation Platform using the following procedures, then configure the necessary parameters in your inventory file to successfully install both the Ansible Automation Platform and central authentication.
1.2.1. Choosing and obtaining a Red Hat Ansible Automation Platform installer
Choose the Red Hat Ansible Automation Platform installer you need based on your Red Hat Enterprise Linux environment internet connectivity. Review the following scenarios and decide on which Red Hat Ansible Automation Platform installer meets your needs.
A valid Red Hat customer account is required to access Red Hat Ansible Automation Platform installer downloads on the Red Hat Customer Portal.
Installing with internet access
Choose the Red Hat Ansible Automation Platform installer if your Red Hat Enterprise Linux environment is connected to the internet. Installing with internet access retrieves the latest required repositories, packages, and dependencies. Choose one of the following ways to set up your Ansible Automation Platform installer.
Tarball install
- Navigate to the Red Hat Ansible Automation Platform download page.
- Click Download Now for the Ansible Automation Platform <latest-version> Setup.
Extract the files:
$ tar xvzf ansible-automation-platform-setup-<latest-version>.tar.gz
RPM install
Install Ansible Automation Platform Installer Package
v.2.4 for RHEL 8 for x86_64
$ sudo dnf install --enablerepo=ansible-automation-platform-2.4-for-rhel-8-x86_64-rpms ansible-automation-platform-installer
v.2.4 for RHEL 9 for x86-64
$ sudo dnf install --enablerepo=ansible-automation-platform-2.4-for-rhel-9-x86_64-rpms ansible-automation-platform-installer
dnf install
enables the repo as the repo is disabled by default.
When you use the RPM installer, the files are placed under the /opt/ansible-automation-platform/installer
directory.
Installing without internet access
Use the Red Hat Ansible Automation Platform Bundle installer if you are unable to access the internet, or would prefer not to install separate components and dependencies from online repositories. Access to Red Hat Enterprise Linux repositories is still needed. All other dependencies are included in the tar archive.
- Navigate to the Red Hat Ansible Automation Platform download page.
- Click Download Now for the Ansible Automation Platform <latest-version> Setup Bundle.
Extract the files:
$ tar xvzf ansible-automation-platform-setup-bundle-<latest-version>.tar.gz
1.2.2. Configuring the Red Hat Ansible Automation Platform installer
Before running the installer, edit the inventory file found in the installer package to configure the installation of automation hub and Ansible Automation Platform Central Authentication.
Provide a reachable IP address for the [automationhub] host to ensure users can sync content from Private Automation Hub from a different node and push new images to the container registry.
Navigate to the installer directory:
Online installer:
$ cd ansible-automation-platform-setup-<latest-version>
Bundled installer:
$ cd ansible-automation-platform-setup-bundle-<latest-version>
- Open the inventory file using a text editor.
Edit the inventory file parameters under
[automationhub]
to specify an installation of automation hub host:-
Add group host information under
[automationhub]
using an IP address or FQDN for the automation hub location. -
Enter passwords for
automationhub_admin_password
,automationhub_pg_password
, and any additional parameters based on your installation specifications.
-
Add group host information under
-
Enter a password in the
sso_keystore_password
field. Edit the inventory file parameters under
[SSO]
to specify a host on which to install central authentication:-
Enter a password in the
sso_console_admin_password
field, and any additional parameters based on your installation specifications.
-
Enter a password in the
1.2.3. Running the Red Hat Ansible Automation Platform installer
With the inventory file updated, run the installer using the setup.sh
playbook found in the installer package.
Run the
setup.sh
playbook:$ ./setup.sh
1.2.4. Log in as a central authentication admin user
With Red Hat Ansible Automation Platform installed, log in as an admin user to the central authentication server using the admin credentials that you specified in your inventory file.
- Navigate to your Ansible Automation Platform Central Authentication instance.
-
Login using the admin credentials you specified in your inventory file, in the
sso_console_admin_username
andsso_console_admin_password fields
.
With Ansible Automation Platform Central Authentication successfully installed, and the admin user logged in, you can proceed by adding a user storage provider (such as LDAP) using the following procedures.
Chapter 2. Adding a User Storage Provider (LDAP/Kerberos) to Ansible Automation Platform Central Authentication
Ansible Automation Platform Central Authentication comes with a built-in LDAP/AD provider. You can add your LDAP provider to central authentication to be able to import user attributes from your LDAP database.
Prerequisites
- You are logged in as an SSO admin user.
Procedure
- Log in to Ansible Automation Platform Central Authentication as an SSO admin user.
- From the navigation panel, select Configure section → User Federation.
When using an LDAP User Federation in RH-SSO, a group mapper must be added to the client configuration, ansible-automation-platform, to expose the identity provider (IDP) groups to the SAML authentication. Refer to OIDC Token and SAML Assertion Mappings for more information on SAML assertion mappers.
- From the Add provider list, select your LDAP provider to proceed to the LDAP configuration page.
The following table lists the available options for your LDAP configuration:
Configuration Option | Description |
Storage mode | Set to On if you want to import users into the central authentication user database. See Storage Mode for more information. |
Edit mode | Determines the types of modifications that admins can make on user metadata. See Edit Mode for more information. |
Console Display Name | Name used when this provider is referenced in the admin console |
Priority | The priority of this provider when looking up users or adding a user |
Sync Registrations | Enable if you want new users created by Ansible Automation Platform Central Authentication in the admin console or the registration page to be added to LDAP |
Allow Kerberos authentication | Enable Kerberos/SPNEGO authentication in the realm with users data provisioned from LDAP. See Kerberos for more information. |
Chapter 3. Assigning automation hub administrator permissions
Hub administrative users will need to be assigned the role of hubadmin in order to manage user permissions and groups. You can assign the role of hubadmin to a user through the Ansible Automation Platform Central Authentication client.
Prerequisites
- A user storage provider (e.g., LDAP) has been added to your central authentication
Procedure
-
Navigate to the
ansible-automation-platform
realm on your SSO client. - From the navigation panel, select User Access → Users.
- Select a user from the list by clicking their ID.
- Click the Role Mappings tab.
- From the Client Roles list, select automation-hub.
- Click hubadmin from the Available Roles field, then click Add selected >.
The user is now a hubadmin. Repeat steps 3-6 to assign any additional users the hubadmin role.
Chapter 4. Adding an identity broker to Ansible Automation Platform Central Authentication
Ansible Automation Platform Central Authentication supports both social and protocol-based providers. You can add an identity broker to central authentication to enable social authentication for your realm, allowing users to log in using an existing social network account, such as Google, Facebook, GitHub etc.
For a list of supported social networks and for more information to enable them, please see this section.
Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users. They allow you to connect to any identity provider compliant with a specific protocol. Ansible Automation Platform Central Authentication provides support for SAML v2.0 and OpenID Connect v1.0 protocols.
Procedure
- Log in to Ansible Automation Platform Central Authenticationas an admin user.
- Under the Configure section on the side navigation bar, click Identity Providers.
- From the Add provider list, select your identity provider to proceed to the identity provider configuration page.
The following table lists the available options for your identity provider configuration:
Table 4.1. Identity Broker Configuration Options
Configuration Option | Description |
Alias |
The alias is a unique identifier for an identity provider. It is used to reference an identity provider internally. Some protocols such as |
Enabled | Turns the provider on/off. |
Hide on Login Page |
If enabled, this provider will not be shown as a login option on the login page. Clients can still request to use this provider by using the |
Account Linking Only | If enabled, this provider cannot be used to login users and will not be shown as an option on the login page. Existing accounts can still be linked with this provider. |
Store Tokens | Whether or not to store the token received from the identity provider. |
Stored Tokens Readable | Whether or not users are allowed to retrieve the stored identity provider token. This also applies to the broker client-level role read token. |
Trust Email | Whether an email address provided by the identity provider will be trusted. If the realm requires email validation, users that log in from this IDP will not have to go through the email verification process. |
GUI Order | The order number that sorts how the available IDPs are listed on the login page. |
First Login Flow | Select an authentication flow that will be triggered for users that log in to central authentication through this IDP for the first time. |
Post Login Flow | Select an authentication flow that is triggered after the user finishes logging in with the external identity provider. |
4.1. Managing group permissions with Ansible Automation Platform Central Authentication
You can manage user access on the Ansible Automation Platform by grouping specific permissions into roles, and then assigning those roles to groups. As you log in to the Ansible Automation Platform for the first time, Users, Groups, and Roles appear in the user access page in automation hub, then you can assign user access and roles to each group.
Automation hub includes a set of managed roles that are compatible with use cases you may encounter. You can create your own set of managed roles or use the predefined roles located in the Roles section of the User Access page.
4.1.1. Grouping permissions into Roles
You can group permissions into roles with specific user access to features in the system.
Prerequisites
-
You are signed in as a
hubadmin
user.
Procedure
- Log in to your private automation hub.
- Navigate to the User Access drop-down menu.
- Click Roles.
- Click Add roles.
- Enter role name in the Name field.
- Enter role description in the Description field.
- Click the drop-down menu next to each Permissions type and select the appropriate permissions for the role.
- Click Save.
You have created a new role with specific permissions. You can now assign this role to groups.
4.1.1.1. Assigning roles to groups
You can assign roles to groups, giving users access to specific features in the system, from both the Groups menu and the Namespaces menu. Roles assigned to a group from the Groups menu have a global scope. For example, if a user is assigned a namespace owner role, that permission applies to all namespaces. However, roles assigned to a group from the Namespaces menu will only give a user access to a specific instance of an object.
Prerequisites
-
You are signed in as a
hubadmin
user.
Procedure
Assigning roles from the Groups menu.
- Log in to your private automation hub.
- From the navigation panel, select User Access → Groups.
- Select a group from the list of groups displayed.
- Click Add roles.
- Click the checkbox next to the role that you want to add.
- Click Next to preview the role that will be applied to the group.
- Click Add to apply the selected role to the group.
Click Back to return to the roles menu, or click Cancel to return to the previous page.
Procedure
Assigning roles from the Namespaces menu.
- Log in to your private automation hub.
- From the navigation panel, select Collections → Namespaces.
- Click the My Namespaces tab, and select a namespace.
- Click the Access tab to edit.
Users can now access features in automation hub associated with their assigned permissions.
4.1.2. Automation hub permissions
Permissions provide a defined set of actions each group can perform on a given object. Determine the required level of access for your groups based on the permissions described in this table.
Table 4.2. Permissions Reference Table
Object | Permission | Description |
---|---|---|
collection namespaces | Add namespace Upload to namespace Change namespace Delete namespace | Groups with these permissions can create, upload collections, and delete a namespace. |
collections | Modify Ansible repo content Delete collections | Groups with this permission can perform these actions: Move content between repositories by using the Approval feature. Certify or reject features to move content from the staging to published or rejected repositories. Delete collections. |
users | View user Delete user Add user Change user | Groups with these permissions can manage user configuration and access in private automation hub. |
groups | View group Delete group Add group Change group | Groups with these permissions can manage group configuration and access in private automation hub. |
collection remotes | Change collection remote View collection remote | Groups with these permissions can configure a remote repository by navigating to Collection → Repositories. |
containers | Change container namespace permissions Change containers Change image tags Create new containers Push to existing containers Delete container repository | Groups with these permissions can manage container repositories in private automation hub. |
remote registries | Add remote registry Change remote registry Delete remote registry | Groups with these permissions can add, change, or delete remote registries added to private automation hub. |
task management | Change task Delete task View all tasks | Groups with these permissions can manage tasks added to Task Management in private automation hub. |
Chapter 5. Configuring Ansible Automation Platform Central Authentication Generic OIDC settings and Red Hat SSO/keycloak for Red Hat SSO and Ansible Automation Platform
Ansible Automation Platform Central Authentication allows for the setting of generic OIDC settings and Red Hat SSO/keycloak for Red Hat SSO and Ansible Automation Platform.
5.1. Prerequisites
- You are able to log in as an admin user.
5.2. Configuring Central Authentication Generic OIDC settings
Procedure
Log in to RH-SSO as admin.
NoteIf you have an existing realm you may go to step 6.
- Add Realm.
- Enter Name and click Create.
- Click the Clients tab.
- Enter name and click Create.
- From the navigation panel, select Client Protocol → openid-connect.
- From the navigation panel, select Access Type → confidential.
- In the Root URL field, enter your Ansible Automation Platform server IP or hostname.
- In the Valid Redirect field, enter your Ansible Automation Platform server IP or hostname. If not in production, set to *.
- In the Web origins field, enter your Ansible Automation Platform server IP or hostname. If not in production, set to *.
Click the Credentials tab.
NoteKeep track of the Secret to be used later.
- Log in to Ansible Automation Platform Controller as admin.
- From the navigation panel, select Settings.
- Select Generic OIDC settings from the list of Authentication options.
- Click Edit.
- In the OIDC Key field, enter the name of your client from step 5.
- In the OIDC Secret field, enter the secret saved from step 8.
- In the OIDC Provider URL field, enter your keycloak server URL and port.
- Click Save.
OIDC should appear as an option for login. Click Sign in with OIDC and it will redirect you to the SSO server for login and redirection back to Ansible Automation Platform.