Federated Auth
Objective
Connect AWS, Kubernetes, and Vault to Authentik to enable single sign-on (SSO) and unified role-based access control (RBAC).
Background
Every federated authentication configuration comes in two parts:
-
a module for setting up the authentication provider in Authentik
-
a module for setting up the authentication receiver in the service provider
These are split in two because the modules will often be deployed in different environments. The Authentik half will always be deployed in the same environment as your Authentik instance while the service provider half will be deployed in the same environment where the service provider is deployed.
Let's get started.
AWS
Enable AWS IAM Identity Center
AWS IAM Identity Center is the AWS mechanism to log into your AWS organization from an external identity provider. Unfortunately, it does not have a robust configuration API, so we will have to configure several settings manually before we can begin deploying infrastructure-as-code.
Let's do this now:
-
Log into the AWS web console of your management account. Switch to the AWS region you have set in your
global
Terragrunt region (i.e., theaws_region
value in yourmanagement/global/region.yaml
file). -
Navigate to the IAM Identity Center service:
-
Follow these instructions to change your access portal url. This is the URL that your organization will use to access AWS. You cannot change this later.
-
Select "Settings" from the side panel.
-
Under the "Identity Source" tab, select "Change Identity Source" from the "Actions" dropdown.
-
Select "External Identity Provider."
-
Keep this page open as you will need to reference the values and upload an IdP SAML metadata file provided by Authentik in the following section.
Deploy AWS Provider in Authentik
We have a module for configuring Authentik to work with Identity Center: authentik_aws_sso.
Let's deploy it now:
-
Add a new
authentik_aws_sso
folder adjacent to yourauthentik_core_resources
folder. -
Add a new
terragrunt.hcl
file that looks like this.-
Set the
aws_acs_url
as the "IAM Identity Center Assertion Consumer Service (ACS) URL" from the page you opened in the prior section. -
Set the
aws_sign_in_url
as the "AWS access portal sign-in URL" from the page you opened in the prior section. -
Set the
aws_issuer
as the "IAM Identity Center issuer URL" from the page you opened in the prior section. -
Set
aws_scim_enabled
tofalse
and omitaws_scim_url
andaws_scim_token
for now. Additionally, you may omit reading in the secrets file viasops_decrypt_file
. -
For
allowed_groups
, provide all the groups that you want to allow to access AWS (we will assign roles later).
-
-
Run
pf-tf-init
to enable the required providers. -
Run
terragrunt apply
. -
Log into the Authentik admin dashboard. Navigate to Applications > Providers and select the
aws
provider: -
Under "Related objects," click the "Download" button for the Metadata object.
-
Return to the AWS IAM Center page opened in the prior section. Under "IdP SAML metadata," there is a "Choose file" button. Use that button to upload the metadata you just downloaded from Authentik. After that uploads, click "Next."
-
Type "ACCEPT" and click "Change identity source."
-
On the settings page, you should now see a pop-up titled "Automatic provisioning". Select the "Enable" button.
-
This will provide you configuration options for setting up SCIM, a method for synchronizing users and groups across services.
-
Enable SCIM in the
authentik_aws_sso
module.-
Set
aws_scim_enabled
totrue
. -
Set
aws_scim_url
to the "SCIM endpoint" from the previous step. -
Set
aws_scim_token
to the secret "Access token" from the previous step. Ensure that you save it in an encrypted sops file and read it into yourterragrunt.hcl
viasops_decrypt_file
.
-
-
Re-apply the module via
terragrunt apply
. -
In the Authentik dashboard, you should see a new provider called
aws-scim
(under Applications > Providers). Select it. -
You will see "Sync status" as not yet synced. Click "Run sync again." 1
-
After a few moments, you should see the users and groups populated in AWS Identity Center:
-
To verify that SSO works, return to the Authentik page and select "User interface" to return to the normal user dashboard. You should see an app for AWS:
-
Click the app, and you should successfully log in to the AWS access portal. However, you will not yet have access to any accounts just yet.
Configure AWS Identity Center Permissions
We will now configure permissions in AWS Identity Center to allow your users access to accounts in your AWS organizations. Fortunately, AWS does expose APIs for this, so we can provide an infrastructure module to automatically set this up: aws_iam_identity_center_permissions.
Let's deploy it now:
-
Add a new
aws_iam_identity_center_permissions
folder to management environment in the global region. -
Add a new
terragrunt.hcl
file that looks like this. -
For the
acccount_access_configuration
, we recommend setting this up according to our RBAC recommendations, but you have the flexibility to choose what works best for your organization.-
Each top-level object is an AWS account that you have created. You will likely have different accounts than what we use in our reference
terragrunt.hcl
. -
The top-level key (e.g.,
production
) is for reference only. Theaccount_id
value determines the account. -
The remaining values determine which Authentik groups get assigned which roles in the specified account. For descriptions of the roles, see this reference document. You must have already allowed these groups access to AWS in the
authentik_aws_sso
module above.
-
-
Run
pf-tf-init
to enable the required providers. -
Run
terragrunt apply
. -
Refresh the AWS access portal, and you will now see you have SSO access to your AWS accounts:
Configure Developer Environment for AWS SSO
We will now configure your organization's local development environment to take advantage of dynamically provisioned SSO credentials and roles and stop using your static root access keys.
-
For every Kubernetes cluster that you have already deployed, re-apply the
aws_eks
module. This will automatically pick up the new AWS roles and give them equivalent access to resources in the Kubernetes cluster. Failure to complete this step will cause you to lose access to your clusters. 2 -
As AWS KMS keys are special resources that require explicit permission grants, you must re-apply every module that make use of KMS keys in order to pick up the new SSO roles. In this guide, that would be the following modules:
- sops keys deployed with the aws_kms_encrypt_key module
- Vault clusters deployed with kube_vaults
-
Run
pf-update-aws
to scaffold files in youraws_dir
directory. -
Copy the generated
config.example.yaml
file toconfig.yaml
. -
Set up
config.yaml
according to these reference docs.-
We provide an example file here.
-
The
sso_region
can be found in your AWS IAM Identity Center dashboard page. -
If you are using a pre-existing AWS SSO setup, you can omit
module
and instead manually list the roles via theextra_roles
field. You can also useextra_roles
in tandem withmodule
.
-
-
Run
pf-update-aws --build
. This will automatically generate your<aws_dir>/config
file to support all SSO roles (file format).Profiles names are of the format
environment-role
and can be used likeaws --profile production-superuser ...
. You will first need to runaws --profile <profile-name> sso login
and complete the login flow before running commands under a given SSO profile.The
config
file is safe to commit to version control. It does not contain any secret information. -
Let's test the new SSO configuration with
aws --profile management-superuser sso login
. This login should complete successfully. -
Ensure that you adjust your
<kube_dir>/config.user.yaml
and terragrunt variables to reflect the generated profile names.In general, your terragrunt variables for AWS profiles should use the
<environment>-superuser
roles as some modules will require superuser privileges to run. Your organization's users can override this profile in their personalenvironment.user.yaml
files if they need to run terragrunt but do not havesuperuser
access. See this guide for more information. -
Verify that you still have Kubernetes connectivity by running
kubectl cluster-info
for every cluster (after runningpf-update-kube
to reflect any changes to your<kube_dir>/config.user.yaml
). -
Let's finally de-provision your static root user credentials.
-
Delete
<aws_dir>/credentials
which contains your static credentials. -
Using each AWS account's root user, login to the AWS web console, select the rop-right dropdown, select "Security credentials," and delete the AWS access key provisioned at the start of this guide series.
-
In the event of a disaster, you can still re-provision these credentials via the web console. However, since they can easily become a security vulnerability, it is best delete them when not needed.
-
Vault
Deploy Vault Provider in Authentik
We have a module for configuring Authentik to serve as the IdP for Vault clusters: authentik_vault_sso.
Let's deploy it now:
-
For every Vault cluster, add a
authentik_vault_sso_<cluster_name>
folder adjacent to yourauthentik_core_resources
folder. -
Add a new
terragrunt.hcl
file that looks like this.-
Every Vault cluster must have a unique
vault_name
. -
Set
vault_domain
to the name that you host the Vault cluster on. -
For
allowed_groups
, provide all the groups that you want to allow to access the particular Vault cluster (we will assign roles later).
-
-
Run
pf-tf-init
to enable the required providers. -
In your
module.yaml
, set themodule
toauthentik_vault_sso
. -
Run
terragrunt apply
.
Deploy Vault OIDC Login Configuration
We also provide a module to configure Vault to work with the above Authentik configuration: vault_auth_oidc.
Let's deploy it now:
-
For every Vault cluster, add a
vault_auth_oidc
folder adjacent to itskube_vault
folder. -
Add a new
terragrunt.hcl
file that looks like this.Note that while this example module is connected to
authentik_vault_sso
viadependency
blocks, this is only possible because they are in the same environment. If the modules are not in the same environment, you will need to copy the relevant outputs fromauthentik_vault_sso
(viaterragrunt output -json
to get the secrets) into theterragrunt.hcl
and make sure you encrypt theclient_secret
with sops. -
Set the
superuser_groups
,admin_groups
, andreader_groups
as appropriate.Note that these permissions will grant access to all databases created by Panfactum modules.
admin_groups
will get read and write access.reader_groups
will only receive read access.Additionally, note that we do not have
restricted_reader_groups
orbilling_admin_groups
as Vault contains only sensitive information. -
Run
pf-tf-init
to enable the required providers. -
Run
terragrunt apply
. -
To verify that SSO works, visit the Vault web UI. Select the OIDC method and then click "Sign in with OIDC Provider." This should open a pop-up that enables you to authenticate with Authenticate. After signing in, you should be redirected to the Vault web dashboard.
Configure Developer Environment for OIDC Auth to Vault
-
Remove your hardcoded
VAULT_ADDR
andVAULT_TOKEN
token from your.env
file. Make sure that you added thevault_addr
in youregion.yaml
as covered in the inbound networking section. -
Terragrunt will automatically work with the new SSO login flow. Test this by re-applying the
vault_auth_oidc
module. -
To use the
vault
CLI directly, you will need to set theVAULT_ADDR
environment variable and runpf-get-vault-token
to retrieve a dynamically generated credential. From there, you can run vault commands directly (you do not need to specify the token as it is saved on disk). Test this now by runningvault operator members
. -
Now you will need to revoke the root token generated when you initialized Vault. It is not safe to keep this static credential live. Run
vault token revoke <your_root_token>
to complete the revocation. 3
Additional Systems
The purpose of an identity provider like Authentik is to be the single source of truth for identity and access management in your organization. While we only provide Authentik modules for components of the Panfactum stack, Authentik provides robust documentation for 100+ common service provider integrations such as with Google, Azure, GitHub, etc. Additionally, Authentik provides support for all the standard federated authentication protocols so its nearly guaranteed that it will be able to integrate with any system.
Check out their integration documentation here.
You should take some time to configure this for your other service providers.
Next Steps
Congratulations! You have successfully configured federated authentication, unified your RBAC, and removed most of the static credentials from your ecosystem. In the next section we will do a final review of the Panfactum bootstrapping process and recommend some next steps.
Footnotes
-
After the initial sync, SCIM will sync automatically after user and group updates. ↩
-
If you do make a mistake, this is recoverable, but you will need to revert to using your static root credentials to fix. ↩
-
You can always generate a new root token with your unseal keys by following these instructions. ↩