Ansible Tower and Okta
Ansible Tower (Otherwise known as AWX, or Ansible Controller) is a platform that provides a user interface for Ansible, allowing you to more easily use Ansible in a large organization, or as part of a pipeline.
Okta is an enterprise oauth platform that allows you to use SAML authentication to pass credentials to your applications. It integrates with Active Directory, and is generally easy to get working.
This article will walk you through the setup of SAML authentication between Okta and Ansible Tower running on an EC2 in AWS behind an AWS Application Load Balancer. You should already have your Okta configured, as well as Ansible Tower running and licensed.
When configuring Ansible Tower with Okta, we need to start with the Okta configuration, because we will need some of the values from this process in order to get through our Ansible Tower SAML setup.
Okta Configuration
If you have a Red Hat license, this article does a good job of describing how to set up general SAML access within Ansible Tower. However, this configuration isn’t specific to Okta, and there are a few changes that we need to make in order to successfully get our Okta configuration up and running.
Within the Okta Portal, go to Applications > Add Application > Create New App.
Set your new application to use Platform: Web and Single Sign On Method: SAML 2.0
Set your Application Name to something descriptive, like Company-Ansible-Tower
Configure the SAML Settings. You will need to remember these! The first thing you need to fill out is yourSingle sign on URL . This is the base URL of your Ansible Tower instance, plus /sso/complete/saml/ . The trailing slash here is pretty imporant, as I can tell you that without it, Ansible Tower will just silently redirect you back to the login page.
The Audience URI or SP Entity ID is just the base URL of your service
For example, if your base tower URL is https://ansibletower.company.com , then your Single Sign On Configuration will be:
Platform: Web
Single Sign On Method: SAML 2.0
Application Name: Company-Ansible-Tower
Single sign on URL: https://ansibletower.company.com/sso/complete/saml/
Audience URI (SP Entity ID): https://ansibletower.company.comThe next step is to create our Attribute Statements. While this isn’t always necessary for Okta configuration, without this section, Ansible Tower will silently redirect you back to the Login page, with one line in the log file letting you know that
Authentication failed: SAML login failed: ['invalid_response']
(There is no AttributeStatement on the Response).In the below configuration, keep in mind that both the Attribute and Group Attribute statement sections need to be configured, and will need to be referenced when you are configuring Ansible Tower. Jot down what you set in the Name section below for use later.
Some Notes: Okta Attribute Statements need to be based on what your Okta Values are configured to be, so you may need to change your Attribute Statements to match your existing Okta Configuration.
Now that you have your basic Okta Configuration finished, you can assign your application by going to the Applications > Assign Applications > and add users to your application.
Your final Okta configuration should look something like the one below. If so, we can go ahead and move on to configuring our Load Balancer!
AWS Application Load Balancer Configuration
Before we set up Ansible Tower’s SAML configuration, it’s important to make sure that the AWS Application Load Balancer and it’s listeners are correctly configured to allow SAML traffic to our Ansible Tower instance. If you don’t have an Application Load balancer in front of your Ansible Tower instance, feel free to move on to the next section, Ansible Tower Configuration.
This article will assume you already have an Application Load Balancer (ALB) configured and running, but if you need to set one up, take a look at AWS’s great documentation on how to get started.
Head into your load balancer, and go to the Listeners tab.
The first thing we want to verify, is that group-level stickiness is turned on. If this isn’t turned on, you’ll start getting weird errors where SAML data could be sent to one Ansible Tower instance, and the actual login redirect could take you to the other instance.
If you see something like group-level stickiness: off head into your listener, and edit the sickiness.
Once that’s done, head over to the Attributes tab, and verify that your settings look like the ones below.
The most important settings to keep an eye on here are to make sure that Client Port Preservation is on, as well as Preserve Host Headers is on and X-Forward-For header is set to Preserve
Ansible Tower Configuration
At this point, we are finally ready to set up our Ansible Tower SAML settings. Ansible provides us some documentation for setting up SAML, which you can however there are some things that are specific to Okta.
The first step to getting Ansible Tower set up is to go into Settings > SAML settings > Edit
The first thing we need to fill in is the SAML Service Provider Entity ID. While Ansible gives a number of options for what this could be, the Service Provider Entity ID should be filled in directly from the Audience Restriction section of the Okta Configuration.
If these don’t match, you’ll see an error in the Ansible Tower logs that looks like this:
ERROR social Authentication failed: SAML login failed: ['invalid_response']
(https://non-matching-url is not a valid audience for this Response).The next step is to get our Ansible Tower Certificate. If you haven’t set up Ansible Tower yet, the documentation has great tutorial on creating a new certificate.
However, the certificate that is required in the SAML Service Provider Public Certificate and the SAML Service Provider Private Key needs to be the server certificate itself.
This certificate and private key can be found at /etc/tower/tower.cert on your Ansible Tower server.
The next three sections are listed as optional in the Ansible Tower configuration guide, but Ansible Tower will not be able to utilize SAML without them set.
These sections are SAML Service Provider Organization Info , SAML Service Provider Technical Contact, and SAML Service Provider Support Contact .
As you can see above, we should match our Service Provider Organization Info section to the name we’ve assigned our application in Okta. Technical Contact and Support Contact do not need to be set to an already created user, but do need to be set for Ansible Tower to recognize SAML as configured.
The next section, the SAML Enabled Identity Providers section is the most detailed section, and requires a significant amount of data from Okta.
You can see in this example that we’ve set the attributes that will be pulled from our Attribute Statements in order to create the accounts that we will need. These fields are attr_first_name , attr_username , attr_last_name , attr_email , and attr_user_permenent_id . You can set the actual values of these to be any attribute statement sent over by Okta, in order to create the types of accounts that you need to create.
The field x509cert is a different certificate than entered above. This certificate is the certificate provided in Okta. It needs to be pasted in as a single string without line breaks, or Ansible Tower will fail to save.
The URL is the entire Okta url that you use to access the application, and the entity ID is the url that you find in the Okta metadata that defines which company you are using to create the Okta application.
Finally, you need to set up the SAML Organization Mapsection to define users. If you don’t, Ansible Tower will fail to assign your new user to an organization, and redirect back to the login page with no error message in the logs whatsoever.
You can also use this section to define organization administrators.
Make sure that SAML Security Config is set as below, and you should be ready to save and test out your configuration!
Testing
If everything has gone well, you will be able to sign out of Ansible Tower, and see the new grey SAML login icon at the bottom of the login window.
If you can hit this button to log in, congratuations! You’ve successfully set up Ansible Tower.
While this is where this tutorial would usually end, based on my experience setting up Ansible Tower, I’m going to add a few debugging steps just in case.
Debugging
If you do run into any issues with Okta and Ansible Tower, there are a few tools you can use to track down what’s happening.
One of the tools I found extremely useful throughout the troubleshooting process was this chrome extension, which allowed me to see the full SAML response being sent back by Okta.
I also had a lot of luck with both the Nginx logs on the Ansible Tower Server at /var/log/nginx/error.log and the Ansible Tower logs at /var/log/tower/tower.log .
Finally, you can check your Ansible Tower configuration by going to your Ansible Tower url + /api/v2/settings/system . So in our example, it would be https://ansibletower.company/api/v2/settings/system
Hopefully you won’t ever need this section, though!
