Identity Provider

Deploy an Identity Provider (IdP) to centralize authentication and authorization for your organization.

Background

A core security tenant is providing a single root directory for managing your organization’s users and permissions. This greatly simplifies identity and access management (IAM), improves the user experience, and reduces the probability of access control mistakes.

Identity and access management is a broad topic which we will not cover in-depth in this guide. However, it is critical to understand a few key terms:

  • Authentication (Authn): The process of identifying a user (i.e., “logging in”)

  • Authorization (Authz): The process of controlling what a user has access to

  • Identity Provider (IdP): A system that serves as the source of truth for information about users and group assignments; can provide this information to other systems in a secure manner

  • Service Provider (SP): Any system that your users utilize directly (e.g., AWS, Kubernetes, Vault); will often connect to an IdP for information about the users

  • Federated Auth: The use of protocols such as SAML, OAuth2 / OIDC, or LDAP to connect many SPs to a single IdP.

  • Single Sign-on: Using a federated auth protocol to facilitate a single means of authentication for your users; does not necessarily facilitate authorization

  • Role-based Access Control (RBAC): An authorization paradigm that assigns permissions to users based on which groups they are in

For more information, we recommend reviewing our more detailed concept documentation:

  • Federated Authentication (TODO)

  • Role-based Access Control in the Panfactum Stack (TODO)

Deploy an Identity Provider

There are many managed IdPs available and you have likely heard of a few such as Okta or Microsoft Entra ID. However, we strongly recommend self-hosting. Your IdP will control all access to your systems, and leaving this control in the hands of a third-party leaves you vulnerable to outages and security incidents (not to mention egregious pricing).

Fortunately, there are also many production-ready self-hosted IdPs that contain all the same functionality. In our analysis, the most robust and well-integrated tool is Authentik.

We provide both a module to deploy Authentik (kube_authentik) and many modules to connect Authentik to the various systems in the Panfactum stack (e.g., authentik_aws_sso).

Configure AWS SES

Before we deploy Authentik, we need to provide some means for it to send emails to users in your organization to accomplish tasks like password resets or administrator notifications.

AWS provides a service called Simple Email Service (SES) that facilitates email sending via SMTP (the standard protocol for sending email).

Before using it, you must first configure SES to use the domain you want to use send email from (e.g., panfactum.com). We provide a module to do this: aws_ses_domain.

Let’s deploy the module now:

  1. Choose the domain that you want to use for automated email sending. This can be the same domain that you use to send email normally.

  2. Add a new aws_ses_domain folder to your production environment in the region where you plan to deploy Authentik.

  3. Add a new terragrunt.hcl file that looks like this:

    include "panfactum" {
   path   = find_in_parent_folders("panfactum.hcl")
   expose = true
}

terraform {
   source = include.panfactum.locals.pf_stack_source
}

dependency "aws_vpc" {
   config_path = "../aws_vpc"
}

inputs = {
   smtp_allowed_cidrs = concat(
      [dependency.aws_vpc.outputs.vpc_cidr],
      dependency.aws_vpc.outputs.nat_ips
   )

   // Replace with your sending domain. 
   //MUST be a domain that has its Route53 zone in the environment.
   domain = "REPLACE_ME" 
}

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

  5. Run terragrunt apply.

  6. Log into the AWS web console and navigate to the SES service. Under “Get set up,” notice that your SES configuration may be in Sandbox mode:

    SES Sandbox mode

    Depending on your needs, you may need to request production access to authorize your account for more permissive email sending. AWS adds this extra gate-keeping step to guard against spam senders.

  7. (Optional) This module does not configure your DMARC record as you would typically only have one DMARC record that covers all of your email sending systems. We recommend following this guide to set this up. You can use the aws_dns_records module to deploy the record.

Deploy Authentik

We are now ready to deploy Authentik:

  1. Add a new kube_authentik folder adjacent to your aws_ses_domain folder.

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

    include "panfactum" {
   path   = find_in_parent_folders("panfactum.hcl")
   expose = true
}

terraform {
   source = include.panfactum.locals.pf_stack_source
}

dependency "cnpg" {
   config_path  = "../kube_cloudnative_pg"
   skip_outputs = true
}

dependency "kyverno" {
   config_path  = "../kube_kyverno"
   skip_outputs = true
}

dependency "ses_domain" {
   config_path = "../aws_ses_domain"
}

inputs = {
   smtp_host          = dependency.ses_domain.outputs.smtp_host
   smtp_user          = dependency.ses_domain.outputs.smtp_user
   smtp_password      = dependency.ses_domain.outputs.smtp_password
   email_from_address = "no-reply@${dependency.ses_domain.outputs.domain}" // The user (e.g., `no-reply`) is arbitrary.

   // Should be a subdomain of one of the domains available in this environment.
   // Example: authentik.panfactum.com
   domain = "REPLACE_ME"

   // Should be a real email address that will be used for the initial root authentik user.
   // Example: it@panfactum.com
   akadmin_email = "REPLACE_ME"
}

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

  4. Run terragrunt apply.

  5. This may take about 5-10 minutes to fully deploy as Authentik completes its initialization.

  6. Once this completes, run terragrunt output -json to retrieve the sensitive outputs.

  7. Save the akadmin_bootstrap_token value in your .env as AUTHENTIK_TOKEN. Save the authentik_url as the authentik_url field in your global.yaml. This will be used by the Authentik OpenTofu (Terraform) provider in subsequent steps to configure Authentik.

    AUTHENTIK_TOKEN=REPLACE_ME

  8. Navigate to the domain you configured in step 2 in a web browser. You should receive a login prompt like this (may have different branding):

    Initial Authentik login page

  9. Sign-in with the username akadmin and the akadmin_bootstrap_password from your module outputs.

  10. After successful sign-in, click the “Admin Interface” button in the top-right (if not already in the admin dashboard):

    Authentik admin interface button

  11. You should reach a dashboard that looks like this:

    Authentik admin interface

  12. Navigate to System > Brands. Edit the authentik brand. Disable the Default setting. This will conflict with the automated setup in the next guide section.

Configure Authentik - Automated Set Up

Out-of-the box, Authentik provides a nearly blank slate with only enough to facilitate the initial admin login. We provide a module that augments this initial setup with more secure authentication flows, recovery flows, and branding: authentik_core_resources.

This module also allows you to define user groups. Groups in Authentik will be assigned to roles in service providers as the foundational mechanism for implementing RBAC across your ecosystem. See the Panfactum RBAC reference for more information.

Of particular note is the superusers group which will receive root access to every system deployed by a Panfactum module.

Let’s deploy this configuration now:

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

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

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

inputs = {
   authentik_namespace       = dependency.kube_authentik.outputs.namespace
   email_templates_configmap = dependency.kube_authentik.outputs.email_templates_configmap
   media_configmap           = dependency.kube_authentik.outputs.media_configmap

   // How you want your organization to be referenced on the Authentik web UI.
   organization_name   = "REPLACE_ME"

   // Should be the root domain on which the Authentik subdomain is hosted.
   // Example: "panfactum.com" if Authentik is hosted at "authentik.panfactum.com"
   organization_domain = "REPLACE_ME"

   // Optional: logo_svg_b64 = filebase64("${get_terragrunt_dir()}/logo.svg")


   // Controls whether members of the `superusers` group require hardware tokens such as Yubikeys (https://www.yubico.com/)
   // to authenticate. We *strongly* recommend setting this to `true`.
   superusers_require_webauthn = true
}

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

  4. Run terragrunt apply.

  5. After a few minutes, when you reload the site, you should see updated branding.

Provision your User

Now that Authentik is bootstrapped, we will stop using the insecure bootstrapped user and switch to a personal user account.

  1. Create your user

    1. Navigate to Directory > Users.

    2. Select “Create”.

    3. Set your email as the Username.

    4. Set your name as the Name.

    5. Set internal as the User type.

    6. Set your email as the Email.

    7. Use the default for the other settings.

  2. Assign the user to the superusers group to ensure it will have root access to all systems.

    1. Select your newly created user from Directory > Users.

    2. Select the Groups tab.

    3. Select “Add to existing group.”

    4. Select the superusers group.

  3. Reset the new user’s password.

    1. Select the user.

    2. On the Overview tab, click the “Email recovery link” button in the sidebar:

      Email recovery link button

    3. Select the panfactum-recovery-email stage.

    4. In a minute or two, you should receive a recovery email at your user’s email address: 1

      Password recovery email

    5. Clicking on the link, you will be greeted with a prompt to set up a new password. Enter one. 2

    6. Next, you will need to set up your preferred MFA method. Since you are in superusers, you may need to use WebAuthn for which we recommend Yubikeys.

    7. After configuring MFA, you should be successfully logged in.

  4. Provision a new API token.

    1. Navigate to Directory > Tokens and App passwords.

    2. Select “Create.”

    3. Use a meaningful name for Identifier.

    4. Assign this to your new User.

    5. Set API Token as the Intent.

    6. Adding a meaningful Description.

    7. We recommend using a short-lived, expiring token as the credential will have root access to Authentik and thus every system in your ecosystem. Generally, you will only need this for initially setting up the Authentik infrastructure modules which will not change frequently.

    8. Once the token has been created, copy it to your clipboard via the copy button on the far right of the token’s row in the Tokens table.

    9. Set it as the AUTHENTIK_TOKEN in your .env, replacing the bootstrap token.

      AUTHENTIK_TOKEN=REPLACE_ME

    10. Run terragrunt apply on the authentik_core_resources module to ensure that it is working correctly.

  5. Disable the bootstrap user. This user is no longer necessary and is not as secure as your new superuser.

    1. Delete the authentik-bootstrap-token from the Tokens table.

    2. Navigate to Users > Directory.

    3. Edit the akadmin user.

    4. Set Is active to false.

    5. Click “Update.”

  6. (Recommended) Add a secondary MFA device in case you lose or damage your primary. If you skip this step, you increase your risk of becoming locked out of your entire ecosystem permanently.

    1. Select “User interface” in the Admin dashboard sidebar.

    2. Click “Settings” (top-right).

    3. Select “MFA Devices.”

    4. Enroll an additional WebAuthn device (or TOTP if you are using TOTP). 3

Next Steps

Your IdP is now fully configured and ready to be connected to the other systems set up in this guide such as AWS, Kubernetes, and Vault.

Panfactum Bootstrapping Guide:
Step 19 of 21

Footnotes

  1. If you do not receive an email or if clicking on the link results in a “Request has been denied” error from Authentik, it is possible your email client is scanning the URLs which can either consume the one-time password reset token or even result in the email never being delivered at all. This is particularly prevalent with Microsoft Outlook SafeLinks. Ensure that you have whitelisted the Authentik domain as trustworthy. ↩

  2. If you are not greeted with a prompt, first log out of Authentik. ↩

  3. Static tokens will not work. ↩