Federated Auth

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:

   authentik_aws_sso/terragrunt.hcl

   include "panfactum" {
      path   = find_in_parent_folders("panfactum.hcl")
      expose = true
   }
   
   terraform {
      source = include.panfactum.locals.pf_stack_source
   }
   
   dependency "authentik_core" {
      config_path = "../authentik_core_resources"
   }
   
   dependency "kube_authentik" {
      config_path = "../kube_authentik"
   }
   
   inputs = {
      // Set to the "IAM Identity Center Assertion Consumer Service (ACS) URL" from the page you opened in the prior section.
      // Example: https://us-east-2.signin.aws.amazon.com/platform/saml/acs/95dd9da3-94ec-448b-9449-6564c5630e9b
      aws_acs_url      = "REPLACE_ME"
   
      // Set to the "AWS access portal sign-in URL" from the page you opened in the prior section.
      // Example: https://panfactum.awsapps.com/start
      aws_sign_in_url  = "REPLACE_ME"
   
      // Set to the "IAM Identity Center issuer URL" from the page you opened in the prior section.
      // Example: https://us-east-2.signin.aws.amazon.com/platform/saml/d-9a6709eac6
      aws_issuer       = "REPLACE_ME"
   
      aws_scim_enabled = false
   
      organization_name   = dependency.authentik_core.outputs.organization_name
      authentik_namespace = dependency.kube_authentik.outputs.namespace
      media_configmap     = dependency.kube_authentik.outputs.media_configmap
      authentik_domain    = dependency.kube_authentik.outputs.domain
   
      allowed_groups = [
         "superusers",
         "privileged_engineers",
         "engineers",
         "restricted_engineers",
         "billing_admins"
      ]
   }
   

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.

    authentik_aws_sso/terragrunt.hclauthentik_aws_sso/secrets.yaml

    include "panfactum" {
       path   = find_in_parent_folders("panfactum.hcl")
       expose = true
    }
    
    terraform {
       source = include.panfactum.locals.pf_stack_source
    }
    
    dependency "authentik_core" {
       config_path = "../authentik_core_resources"
    }
    
    dependency "kube_authentik" {
       config_path = "../kube_authentik"
    }
    
    locals {
       secrets = yamldecode(sops_decrypt_file("${get_terragrunt_dir()}/secrets.yaml"))
    }
    
    inputs = {
       // Set to the "IAM Identity Center Assertion Consumer Service (ACS) URL" from the page you opened in the prior section.
       // Example: https://us-east-2.signin.aws.amazon.com/platform/saml/acs/95dd9da3-94ec-448b-9449-6564c5630e9b
       aws_acs_url      = "REPLACE_ME"
    
       // Set to the "AWS access portal sign-in URL" from the page you opened in the prior section.
       // Example: https://panfactum.awsapps.com/start
       aws_sign_in_url  = "REPLACE_ME"
    
       // Set to the "IAM Identity Center issuer URL" from the page you opened in the prior section.
       // Example: https://us-east-2.signin.aws.amazon.com/platform/saml/d-9a6709eac6
       aws_issuer       = "REPLACE_ME"
    
       aws_scim_enabled = true
    
       // Set to the "SCIM endpoint" from the previous step.
       // Example: https://scim.us-east-2.amazonaws.com/Hw59fdecb43-083d-4307-b59f-ef4a9eb90ca6/scim/v2/
       aws_scim_url     = "REPLACE_ME"
    
       // Set to the secret "Access token" from the previous step. Ensure that you save it in an encrypted
       // sops file (secrets.yaml) and read it as shown above.
       aws_scim_token   = local.secrets.aws_scim_token
    
       organization_name   = dependency.authentik_core.outputs.organization_name
       authentik_namespace = dependency.kube_authentik.outputs.namespace
       media_configmap     = dependency.kube_authentik.outputs.media_configmap
       authentik_domain    = dependency.kube_authentik.outputs.domain
    
       allowed_groups = [
          "superusers",
          "privileged_engineers",
          "engineers",
          "restricted_engineers",
          "billing_admins"
       ]
    }
    

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.” ¹

    

    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:

   management/global/aws_iam_identity_center_permissions/terragrunt.hcl

   include "panfactum" {
      path   = find_in_parent_folders("panfactum.hcl")
      expose = true
   }
   
   terraform {
      source = include.panfactum.locals.pf_stack_source
   }
   
   inputs = {
      // IMPORTANT! Edit this configuration your organization's
      // unique needs. See below for instructions.
      account_access_configuration = {
         management = {
            account_id               = "REPLACE_ME"
            superuser_groups         = ["superusers"]
            restricted_reader_groups = ["privileged_engineers", "engineers"]
            billing_admin_groups     = ["billing_admins"]
         }
         production = {
            account_id               = "REPLACE_ME"
            superuser_groups         = ["superusers"]
            admin_groups             = ["privileged_engineers"]
            reader_groups            = ["engineers"]
            restricted_reader_groups = ["restricted_engineers", "demo_users"]
            billing_admin_groups     = ["billing_admins"]
         }
         development = {
            account_id              = "REPLACE_ME"
            superuser_groups        = [
               "superusers",
               "privileged_engineers",
               "engineers"
            ]
            admin_groups            = ["restricted_engineers"]
            billing_admin_groups    = ["billing_admins"]
         }
      }
   }
   

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 a module.yaml file for aws_iam_identity_center_permissions.

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

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. Here is an example file:

   .aws/config.yaml

   sso_start_url: REPLACE_ME # Found in your AWS IAM Identity Center dashboard page.
   sso_region: REPLACE_ME # MUST be the AWS IAM Identity Center region. Found in your AWS IAM Identity Center dashboard page.
   default_aws_region: REPLACE_ME # Can be any AWS region
   module: management/global/aws_iam_identity_center_permissions
   

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:

   .kube/config.user.yaml

   clusters:
   - name: "production-primary"
      aws_profile: "production-superuser"
   

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 terragrunt.hcl and module.yaml files that looks like this:

   authentik_vault_sso_production/terragrunt.hclauthentik_vault_sso_production/module.yaml

      include "panfactum" {
         path   = find_in_parent_folders("panfactum.hcl")
         expose = true
      }
   
      terraform {
         source = include.panfactum.locals.pf_stack_source
      }
   
      dependency "kube_authentik" {
         config_path = "../kube_authentik"
      }
   
      dependency "authentik_core" {
         config_path = "../authentik_core_resources"
      }
   
      inputs = {
         authentik_namespace = dependency.kube_authentik.outputs.namespace
         media_configmap     = dependency.kube_authentik.outputs.media_configmap
         organization_name   = dependency.authentik_core.outputs.organization_name
         authentik_domain    = dependency.kube_authentik.outputs.domain
   
         # Every one of your Vault clusters must have a unique name
         vault_name   = "REPLACE_ME"
   
         # Must be a subdomain of your environment's domain
         # Example: vault.prod.panfactum.com
         vault_domain = "REPLACE_ME"
   
         # Provide *all* the groups that you want to allow to access the particular Vault cluster (we will assign roles later). 
         allowed_groups = [
            "superusers",
            "privileged_engineers",
            "engineers",
            "restricted_engineers"
         ]
      }
   

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

4. 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 new terragrunt.hcl and sops-encrypted secrets.yaml files that looks like this:

   vault_auth_oidc/terragrunt.hclvault_auth_oidc/secrets.yaml

   include "panfactum" {
      path   = find_in_parent_folders("panfactum.hcl")
      expose = true
   }
   
   terraform {
      source = include.panfactum.locals.pf_stack_source
   }
   
   dependency "vault" {
      config_path  = "../kube_vault"
      skip_outputs = true
   }
   
   locals {
      secrets = yamldecode(sops_decrypt_file("${get_terragrunt_dir()}/secrets.yaml"))
   }
   
   inputs = {
   
      // Note: 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.
   
      // The `client_id` output from `authentik_vault_sso`
      // Example: 06fcaxxxeaee0113
      client_id          = "REPLACE_MET"
   
      // The `client_secret` output from `authentik_vault_sso`
      // Example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx
      client_secret      = local.secrets.client_secret
   
      // The `oidc_discovery_url` output from `authentik_vault_sso`
      // Example: https://authentik.panfactum.com/application/o/vault-primary/
      oidc_discovery_url = "REPLACE_ME"
   
      // The `oidc_discovery_url` output from `authentik_vault_sso`
      // Example: [
      //  "https://vault.prod.panfactum.com/ui/vault/auth/oidc/oidc/callback",
      //  "https://vault.prod.panfactum.com/oidc/callback",
      //  "http://localhost:8250/oidc/callback" 
      // ]
      oidc_redirect_uris = [REPLACE_ME]
   
      // The `oidc_issuer` output from `authentik_vault_sso`
      // Example: https://authentik.panfactum.com/application/o/vault-primary/
      oidc_issuer = "REPLACE_ME"
   
      // See below instructions
      superuser_groups         = [REPLACE_ME]
      admin_groups             = [REPLACE_ME]
      reader_groups            = [REPLACE_ME]
      restricted_reader_groups = [REPLACE_ME]
   }
   

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.

   .env

   VAULT_ADDR=vault.example.com
   VAULT_TOKEN=hvs.XXXXXXXXXXXXXXXXXX
   

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

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.