Terraform and Auth0: RBAC via SAML
As part of a recent project, I wanted to demonstrate how using infrastructure as code to setup HashiCorp Terraform, with the appropriate teams, can seamlessly integrate with your existing SSO implementation. After all, I think we would all agree that having to manage user accounts in multiple locations individually is more painful than finding out Darth Vader is your father (spoiler alert).
As I progressed through the project, I compiled some notes on how I configured a free account on Auth0 to demonstrate SSO. Some of this is covered in an incredible article by my brilliant colleague Yulei Liu discussing setting up Auth0 for Single Sign-On with Terraform Cloud for Business. I’m not going to duplicate his efforts, but I did want to include areas where there is a deviation (standard or not).
Start your process with Yulei’s blog to setup Auth0 and create the web application. After the “SAML2 WEB APP Add-On” has been enabled, use the following mapping which includes one very special alteration to Yulei’s example. This is where we will start our own journey.
Line 10, specifically “roles”: “MemberOf”, performs the necessary mapping to take the Auth0 Role configured for the particular user, and map that role to the MemberOf Attribute that is configured within the Terraform SAML settings for Team Membership Management.
After replacing the JSON within the settings area of the Web App, be sure to scroll to the bottom and save your settings. I’ve learned that failing to save these configurations can hamper progress.
At the top of that Web App configuration page, you’ll see a link for ‘Usage.’ Hit that link and you’ll see the URLs and information related to the SAML Web App you just configured. At this point, the procedure for continuing the setup on Terraform differs slightly between Terraform Cloud for Business and Terraform Enterprise. To continue with Terraform Cloud for Business, you can return to Yulei’s blog post and copy the link address for Identity Provider Metadata, however, further below we do address the details of mapping roles with Auth0 within the ‘Almost Done’ section.
Terraform Enterprise
The SAML configuration within Terraform Enterprise is a part of the Site Admin settings. Here we can find the ACS Consumer (Recipient) URL to use as the Application Callback URL within the Auth0 Web App settings.
Our focus, however, shall be at the bottom of the configuration page. This is where we find the Sign-On URL, the Log-Out URL, and the IDP Certificate. These parameters require some of the values and information available in the ‘Usage’ tab of the Web App Configuration page. For our purposes, I used the Web App Identity Provider Login URL as both the Sign-On and Log-Out URL for Terraform.
Don’t forget to also download the Auth0 Certificate, and open that PEM file in your favorite text editor (friends don’t let friends use WordPad). Copy the contents of that file into the IDP Certificate section within the Terraform SAML Identity Provider configuration.
On the Terraform UI, make sure “Use SAML to manage team memberships is configured,” and save the Terraform configuration.
With those details saved, let’s return to the Web Settings tab, and bring that ACS Consumer (Recipient) URL over to the Application Callback URL within the Auth0 Web App settings.
At this point you may think you are done here (I know I did), but wait, there’s more! Skip down to the ‘Almost Done’ section as we want to address Terraform Cloud configuration next.
Terraform Cloud for Business
Much of this was covered in Yulei’s blog, however, I wanted to include the information here just for a consistent flow. Additionally, the Terraform Cloud for Business setup is a bit more straightforward, so why not!
For Terraform Cloud for Business, the SSO Provider is configured for each Organization within the Organization Settings
Click the ‘Setup SSO’ button, and the wizard will start walking you through. Choose ‘SAML’ and the settings for the Auth0 SAML provider are configured at the next page.
The SSO Settings for Terraform Cloud for Business is pretty straightforward, requiring only the Metadata URL to be copied (just copy the link) and paste that into the SAML configuration section of the Terraform Cloud for Business SSO Configuration.
One more thing to configure and we can be on our way! Let’s return to the Web App Settings tab, and bring that Assertion Consumer URL over to the Application Callback URL within the Auth0 Web App settings. Be sure to save the Web App Settings, and test the SAML configuration!
Hopefully your test was successful, and with that, enable SSO for Terraform Cloud for Business by clicking ‘Enable’! At this point you may think you are done here, but wait, there’s more!
Almost Done — Enable Auth0 RBAC
In order to map the User Role within Auth0 to the Terraform Team, you need to enable Auth0 RBAC. Auth0 offers two tools for this purpose, Authorization Extension which is Application focused and has been around for a little while, and Authorization Core which seems to be where Auth0 development is headed. For this purpose, I wasn’t sure if Authorization Core would work, so I chose Authorization Extension. Follow the Auth0 Instructions for installing and configuring the Authorization extension. Within the configuration, all that is required is to enable the ‘Roles’ for the user object.
Any users that you’ve already configured in Auth0 should show up in this extension interface as well, however, any Roles you’ve configured in the main Auth0 Dashboard do not carry over. Within the same Authorization Extension page, go to Roles and create a new role. Be sure to associate that Role with the application you’ve configured for this integration.
Now, if you go back to the Auth0 Application you’ve configured, and the SAML WEB APP settings, you should see a big orange ‘DEBUG’ button. Hit that button and a new tab will open up with all of the SAML data being presented. Within that glorious output, you should be able to find your ‘MemberOf’ assertion that maps to the role you just created in the Extension.
OK…NOW we are done with Auth0! Any Users that are assigned to a Role will have that Role name mapped to a Team name within Terraform(assuming of course that Team Name exists), and will be able to login in using their Auth0 SSO Credentials!
