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:

1. 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., the aws_region value in your management/global/region.yaml file).

2. Navigate to the IAM Identity Center service:

   

3. 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.

4. Select "Settings" from the side panel.

5. Under the "Identity Source" tab, select "Change Identity Source" from the "Actions" dropdown.

6. Select "External Identity Provider."

7. 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:

1. Add a new authentik_aws_sso folder adjacent to your authentik_core_resources folder.

2. Add a new terragrunt.hcl file that looks like this.

   1. Set the aws_acs_url as the "IAM Identity Center Assertion Consumer Service (ACS) URL" from the page you opened in the prior section.

   2. Set the aws_sign_in_url as the "AWS access portal sign-in URL" from the page you opened in the prior section.

   3. Set the aws_issuer as the "IAM Identity Center issuer URL" from the page you opened in the prior section.

   4. Set aws_scim_enabled to false and omit aws_scim_url and aws_scim_token for now. Additionally, you may omit reading in the secrets file via sops_decrypt_file.

   5. For allowed_groups, provide all the groups that you want to allow to access AWS (we will assign roles later).

3. Run pf-tf-init to enable the required providers.

4. Run terragrunt apply.

5. Log into the Authentik admin dashboard. Navigate to Applications > Providers and select the aws provider:

   

6. Under "Related objects," click the "Download" button for the Metadata object.

7. 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."

8. Type "ACCEPT" and click "Change identity source."

9. On the settings page, you should now see a pop-up titled "Automatic provisioning". Select the "Enable" button.

   

10. This will provide you configuration options for setting up SCIM, a method for synchronizing users and groups across services.

11. Enable SCIM in the authentik_aws_sso module.

    1. Set aws_scim_enabled to true.

    2. Set aws_scim_url to the "SCIM endpoint" from the previous step.

    3. 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 your terragrunt.hcl via sops_decrypt_file.

12. Re-apply the module via terragrunt apply.

13. In the Authentik dashboard, you should see a new provider called aws-scim (under Applications > Providers). Select it.

14. You will see "Sync status" as not yet synced. Click "Run sync again." 1

    
    SCIM will fail if any of your users have the same email as the root user for any of your AWS accounts. Ensure that the root users have globally unique email addresses.

15. After a few moments, you should see the users and groups populated in AWS Identity Center:

    

16. 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:

    

17. 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:

1. Add a new aws_iam_identity_center_permissions folder to management environment in the global region.

2. Add a new terragrunt.hcl file that looks like this.

3. 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.

   1. 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.

   2. The top-level key (e.g., production) is for reference only. The account_id value determines the account.

   3. 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.

4. Run pf-tf-init to enable the required providers.

5. Run terragrunt apply.

   When you set up the AWS IAM Identity Center at the beginning of this guide section, it becomes bound to a single AWS region. If this region is different than the AWS region used in your global region, you will run into the following error:

   Error: Invalid index
   │
   │   on main.tf line 12, in locals:
   │   12:   sso_instance_arn  = tolist(data.aws_ssoadmin_instances.main.arns)[0]
   │     ├────────────────
   │     │ data.aws_ssoadmin_instances.main.arns is empty list of string
   │
   │ The given key does not identify an element in this collection value: the
   │ collection has no elements.
   

   You can fix this by setting the aws_region value to the AWS IAM Identity Center region in your module.yaml.

6. 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.

1. For every Kubernetes cluster that you have already deployed, re-apply the kube_rbac 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

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
   • EKS clusters deployed with aws_eks
   • Vault clusters deployed with kube_vaults

3. Run pf-update-aws to scaffold files in your aws_dir directory.

4. Copy the generated config.example.yaml file to config.yaml.

5. Set up config.yaml according to these reference docs.

   1. We provide an example file here.

   2. The sso_region can be found in your AWS IAM Identity Center dashboard page.

   3. If you are using a pre-existing AWS SSO setup, you can omit module and instead manually list the roles via the extra_roles field. You can also use extra_roles in tandem with module.

6. 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 like aws --profile production-superuser .... You will first need to run aws --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.

7. Let's test the new SSO configuration with aws --profile management-superuser sso login. This login should complete successfully.

8. 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 personal environment.user.yaml files if they need to run terragrunt but do not have superuser access. See this guide for more information.

9. Verify that you still have Kubernetes connectivity by running kubectl cluster-info for every cluster (after running pf-update-kube to reflect any changes to your <kube_dir>/config.user.yaml).

10. Let's finally de-provision your static root user credentials.

    1. Delete <aws_dir>/credentials which contains your static credentials.

    2. 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.

    3. 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:

1. For every Vault cluster, add a authentik_vault_sso_<cluster_name> folder adjacent to your authentik_core_resources folder.

2. Add a new terragrunt.hcl file that looks like this.

   1. Every Vault cluster must have a unique vault_name.

   2. Set vault_domain to the name that you host the Vault cluster on.

   3. For allowed_groups, provide all the groups that you want to allow to access the particular Vault cluster (we will assign roles later).

3. Run pf-tf-init to enable the required providers.

4. In your module.yaml, set the module to authentik_vault_sso.

5. 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:

1. For every Vault cluster, add a vault_auth_oidc folder adjacent to its kube_vault folder.

2. Add a new terragrunt.hcl file that looks like this.

   Note that while this example module is connected to authentik_vault_sso via dependency 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 from authentik_vault_sso (via terragrunt output -json to get the secrets) into the terragrunt.hcl and make sure you encrypt the client_secret with sops.

3. Set the superuser_groups, admin_groups, and reader_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 or billing_admin_groups as Vault contains only sensitive information.

4. Run pf-tf-init to enable the required providers.

5. Run terragrunt apply.

6. 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

1. Remove your hardcoded VAULT_ADDR and VAULT_TOKEN token from your .env file. Make sure that you added the vault_addr in you region.yaml as covered in the inbound networking section.

2. Terragrunt will automatically work with the new SSO login flow. Test this by re-applying the vault_auth_oidc module.

3. To use the vault CLI directly, you will need to set the VAULT_ADDR environment variable and run pf-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 running vault operator members.

4. 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.