How authentik signs HCP Terraform users in over SAML
authentik signs HCP Terraform users in by acting as the SAML identity provider, so engineers authenticate with the company's authentik account instead of a separate HCP Terraform password. The authentik integrations catalog publishes a Terraform Cloud guide that configures SAML single sign-on between the two systems, and that guide is the starting point for the SAML provider, the application entry and the attribute and group handling. Before the platform team commits to it, it should confirm the team mapping and organization settings against that guide and against HashiCorp's current SAML documentation for HCP Terraform, because those settings change how group membership turns into team membership and should not be copied from memory or from an older tutorial.
The integration changes where sign-in is decided. Passwords, password rules and MFA for engineers are enforced in authentik, so the authentik flows and factors the organization already uses apply when someone opens HCP Terraform. It does not change what happens inside HCP Terraform after sign-in: workspace permissions, variable sets, run approvals and API tokens remain configured in HCP Terraform, and an API token issued to a person or pipeline keeps working independently of the browser session. Teams should check how their SAML settings behave for users who are removed from authentik, because access that depends on a live SAML session ends when that session does, while tokens and any local accounts may outlive it.
Keep at least one local owner account in HCP Terraform, held by a named set of people and tested before it is needed, so the organization can still administer the organization if authentik, the network path to it or the SAML configuration fails. Document who holds that account, where its credentials are stored, and how the break-glass path is exercised. Confirm with HashiCorp which account types and organization settings it expects for this, since the local path is what keeps a misconfigured SAML setting from locking every administrator out.
What you need before configuring SAML
Most of the SAML work is quick once the prerequisites are in place. The items below run in parallel, so start the DNS, certificate and group design early, because the HCP Terraform team mapping depends on how authentik groups are named.
A supported authentik version
Confirm that your running authentik release is one the project still patches. The security policy lists 2026.5.x and 2026.8.x as the supported lines receiving security fixes, and the latest release on the GitHub releases page is 2026.8.4. Plan any upgrade before the SAML build, since the sequential upgrade rule applies. Check the release notes for your target version before you change anything in production.
HCP Terraform organization with owner access
You need an HCP Terraform organization where you hold owner rights, because the SAML provider, SSO settings and team mapping are organization-level changes. Confirm which plan the organization is on. HashiCorp's blog states that SSO is included in the enhanced Free tier, and team management is included in every paid tier, so the plan does not block the SAML work itself. Confirm the exact feature list with HashiCorp before you commit to a tier.
DNS name and TLS certificate
Give authentik a stable DNS name that HCP Terraform and your users' browsers can both reach, and a TLS certificate that clients trust. SAML metadata, assertion consumer URLs and signing material all depend on this hostname, so changing it later means reconfiguring both sides. Confirm that the certificate chain is complete and that it is issued by a authority your identity team already monitors for renewal.
Groups that match planned teams
Design the authentik group structure before you map anything. Each HCP Terraform team you plan to use should correspond to one authentik group, with a clear owner and a naming convention. Decide which groups grant organization owner rights and keep that list short. Unmapped users will sign in without team membership, so confirm the default behavior for a user with no matching group before go-live.
Named break-glass owner
Name one person who keeps a local HCP Terraform owner path and knows how to use it if the SAML provider fails, a certificate expires or a group mapping locks out administrators. Store the recovery credentials outside the SSO path. Test the break-glass login before enabling SSO enforcement, and record who can approve its use. This owner should not depend on the authentik instance being available.
Configuration sequence from authentik to HCP Terraform
This sequence connects authentik to an HCP Terraform organization over SAML, maps authentik groups to HCP Terraform teams, and confirms that a non-owner test user lands in the right team while an owner keeps a working recovery sign-in. The sequence follows the authentik Terraform Cloud integration guide, and each step ends with a check you can verify before moving on.
Confirm the authentik and HCP Terraform prerequisites
Before changing anything, a platform administrator in authentik and an owner of the HCP Terraform organization should agree on who holds each role, which authentik groups will map to HCP Terraform teams, and which owner account will serve as the recovery path if SAML fails. Open the authentik Terraform Cloud guide on the integrations catalog and note every value it asks for, including the ACS URL, entity ID and certificate handling it specifies. Confirm your authentik version is one that receives security fixes, using the security policy, and that your HCP Terraform plan includes SSO, since that is a feature listed for the enhanced Free tier and paid tiers. Done means a written list of groups, owners and the guide version you are following, approved by both sides.
Create the SAML provider and application in authentik
In authentik, create a SAML provider and an application that uses it, entering the values the integrations guide specifies for Terraform Cloud. Set the signing certificate, the name ID and the attribute mappings that the guide describes, and bind the application to a policy or group so only intended users can start a login. Keep the provider in a test state and do not yet assign it to your production users. Done means the provider and application exist in authentik with the exact values from the guide, and you can see the provider's metadata and endpoint URLs on its detail page.
Export the metadata and endpoints from authentik
Copy or download the SAML metadata and the individual endpoints the authentik provider exposes, including the SSO and logout URLs and the signing certificate. Store them in your change record and label which values go into which HCP Terraform field, since HCP Terraform asks for a certificate, a sign-in URL and an identifier. Verify that the entity ID in the metadata matches the value the guide tells you to use in HCP Terraform. Done means you have a single record of the endpoints and certificate fingerprint, and a second administrator has compared them against the guide.
Configure SAML in the HCP Terraform organization
An HCP Terraform organization owner opens the organization's SSO settings and enters the authentik values from the previous step, then selects the SAML option as the guide directs. Keep the owner's existing password and any recovery method active, and do not enforce SSO for the whole organization yet. Save the configuration and use the SSO test option if one is offered for your plan. Done means HCP Terraform accepts the SAML configuration without error and the organization still shows a working owner sign-in path.
Map authentik groups to HCP Terraform teams
Configure the attribute and group mapping so the SAML assertion carries the group membership that HCP Terraform uses to place users in teams. Use the attribute name the guide specifies, and map each authentik group to exactly one HCP Terraform team, leaving no group that grants owner rights by default. Create matching teams in HCP Terraform first so the mapping has a target. Done means the mapping table lists every group and its team, reviewed by an owner who confirms no unintended group grants organization-level permissions.
Check the assertion in an authentik test login
Sign in to authentik as a test user who belongs to one mapped group and open the SAML test or assertion view that authentik provides for the provider. Confirm the assertion contains the expected name ID, the email attribute and the group attribute with the correct group names, and that no unexpected groups are present. Compare the output to the attribute names in the guide. Done means the assertion contents match the mapping table exactly for that user, and you have saved a copy with personal data removed for the change record.
Test with a non-owner account and confirm recovery
Sign in to HCP Terraform through SSO with the non-owner test account and confirm it lands in the team mapped to its authentik group, with only the permissions that team should hold. Repeat with one account from a second group to confirm separation. Then, as an owner, confirm the recovery method still works by signing in with the owner's non-SSO credentials before enforcing SSO for the organization. Done means each test account reaches the expected team, the recovery owner sign-in succeeds, and your team has recorded the result before enabling SSO enforcement.
How authentik groups map to HCP Terraform teams
This table compares each piece of identity data that moves from authentik into HCP Terraform during SAML sign-in, the team it should land in, and the access that team needs on projects and workspaces. Read each row as a decision to confirm before you build the mapping, and treat the attribute names as placeholders until you copy them from the authentik Terraform Cloud guide and HashiCorp's current SAML team documentation.
| Data element | What it carries | Where it lands in HCP Terraform | Access to plan with |
|---|---|---|---|
| User email | Login identifier and notification address from the authentik user record | Matched to the HCP Terraform user during SAML sign-in | Confirm the exact SAML attribute name in the authentik Terraform Cloud guide |
| User name | Display name for audit trails and run history | User profile, shown in run and workspace activity | Confirm whether HCP Terraform reads a separate first and last name attribute |
| authentik groups | Group membership sent in the SAML assertion for each login | Input for team assignment, not a team itself | Send only groups that map to Terraform teams to keep assertions small |
| Platform team group | Engineers who administer the organization | Owners team, with organization-wide settings access | Limit membership to a few named administrators and review it on a schedule |
| Application team group | Developers who deploy to their own environments | Team with write access to the projects and workspaces they own | Grant write on named workspaces, not the whole organization |
| Read-only auditor group | Reviewers who need visibility without changing infrastructure | Team with read access to projects and workspaces | Confirm the read-only permission set in HashiCorp's current team documentation |
| Owner role | Ability to manage the organization, billing and all teams | Owners team only, which should stay small | Keep at least one owner outside SAML so you can recover if SSO fails |
Designing teams before you turn on SSO
Settle the team design before the SAML group mapping goes live. In this integration, group membership in authentik is the access model: when an administrator removes a user from an authentik group, that user's HCP Terraform team membership changes at their next sign-in. Group names therefore stop being labels and become part of the authorization contract, and renaming a group later can silently move people between teams. Decide which HCP Terraform teams exist, which authentik group maps to each one, and who is allowed to change membership in each group before you configure the attribute mapping on the SAML provider.
The simplest model is one authentik group per HCP Terraform team, named with a stable convention that does not depend on a project or a person. Engineers who belong to several teams, such as a platform engineer who also reviews a networking team's plans, need a deliberate rule. Either they are placed in several groups, which gives broad access but is easy to audit, or you create a narrower combined team for them. Write down the rule and the owner of each group. Confirm with HashiCorp how multiple team memberships are reflected in a SAML sign-in before you rely on it, and test it with a non-production user.
Your team design also interacts with cost and features. The HashiCorp pricing page lists HCP Terraform Essentials, Standard and Premium with resource-based pricing, and it lists team notifications and change requests as features that Standard and Premium include and Essentials does not. A team layout that depends on notifications or change requests therefore depends on the tier you buy. Count the managed resources each team will own, then confirm current tier features and prices on HashiCorp's pricing page before you commit, because both change over time and the pricing page is the authoritative source.
Hardening the SAML trust between the two systems
A SAML sign-in to HCP Terraform makes authentik the gatekeeper for every run, state read and variable change in the organization. The controls below decide who can reach the workspace, which signing material the trust depends on, and how you recover when the identity provider is unavailable. Confirm the signing and encryption options in the authentik Terraform Cloud guide and against your own security standards before you go live.
Signing key and certificate handling
The SAML provider in authentik signs assertions with a certificate and key that HCP Terraform trusts through its SAML settings. Store the private key in authentik's certificate store, restrict who can export or replace it, and record the certificate fingerprint in your change log. Confirm which signing algorithm and whether assertion encryption are supported in the authentik guide, and check that the values in HCP Terraform match the certificate you deployed.
Certificate rotation planning
A rotated signing certificate that does not reach HCP Terraform before the old one expires will lock out every federated user at once. Plan the rotation as a dated change with both parties: publish the new certificate, update the HCP Terraform SAML settings, test a sign-in with a non-admin account, then retire the old certificate. Keep a named owner for the calendar entry, and confirm with your authentik and HashiCorp contacts how overlap between old and new certificates is handled.
Restricting the application to HCP Terraform groups
Bind the authentik application to a policy that allows only the groups that need HCP Terraform, rather than every authentik user. Map those groups to HCP Terraform teams so that access to workspaces follows team membership. Review the binding whenever a team changes, since an account outside the bound groups should fail at authentik before any assertion reaches HashiCorp.
MFA enforced before the assertion
Attach an authentication flow in authentik that requires a second factor before it issues a SAML assertion for this application. HCP Terraform can only enforce what it receives, so an assertion issued after a password-only login would carry the same trust as one issued after MFA. Test the flow with an account that has no second factor enrolled to confirm it is blocked, and document which factor types your policy accepts.
Non-SSO owner recovery path
Keep at least one HCP Terraform organization owner who signs in with a local account protected by a password manager and a hardware second factor, stored outside the SSO path. Without it, an authentik outage or a misconfigured SAML setting can leave no one able to change the SSO settings back. Test this account on a schedule, and confirm with HashiCorp how the organization's login options interact with SSO enforcement before you turn enforcement on.
Audit log review in both systems
Review authentik's event logs for failed assertions, policy denials and changes to the SAML provider or certificates, and review HCP Terraform's audit and team membership records for changes made through SSO. Compare the two sets of records on a fixed cadence so that a certificate change in authentik has a matching entry on the HashiCorp side. Confirm which log retention and export options each product provides for your environment.
Why SAML sign-in to HCP Terraform fails and how to fix it
This table lists the failures teams most often hit when wiring authentik SAML into HCP Terraform, with the likely cause and the procedural fix for each. Read it when a sign-in fails or a user lands in the wrong team, and check the matching row before changing both systems. Exact field names belong in the authentik guide and HashiCorp's documentation, so confirm them there before editing.
| Symptom | Likely cause | Fix |
|---|---|---|
| SAML response rejected with an audience or issuer error | Entity ID in the authentik SAML provider does not match the entity ID configured in the HCP Terraform SAML settings | Copy the entity ID exactly from one system into the other, including trailing slashes and case, then retest from a private browser session |
| Redirect fails or returns to an error page after the IdP login | ACS (assertion consumer service) URL in authentik differs from the URL HCP Terraform expects for the organization | Compare the ACS URL in both systems, correct the authentik provider, and confirm the organization name in the HCP Terraform URL |
| Sign-in breaks after a certificate or signing key rotation | HCP Terraform still holds the previous signing certificate, so assertions signed with the new key fail validation | Export the current signing certificate from authentik, upload it to HCP Terraform, and remove the retired certificate once logins succeed |
| Login succeeds but the user has no team membership | The assertion does not include the group attribute, or the attribute name differs from the one HCP Terraform reads | Inspect a sample SAML response, confirm the group attribute name and that the user belongs to a bound authentik group, then adjust the attribute mapping |
| User lands in a team they should not have | Group names in authentik do not match team names in HCP Terraform, or a broad group is mapped to a high-privilege team | Align group and team names, remove overly broad group mappings, and review team permissions after each mapping change |
| Intermittent assertion expired or not yet valid errors | Clock skew between authentik, the browser and HCP Terraform, which shifts the assertion validity window | Confirm time synchronization (NTP) on the authentik hosts and check the validity window settings in the SAML provider |
| Organization owner locked out after SSO is enforced | Enforcing SSO removed the local password path before a working SAML login was verified | Keep a tested owner account with a recovery path before enforcing SSO, and confirm the recovery steps in HashiCorp's organization documentation |
Questions teams ask before configuring SAML for HCP Terraform
How much effort does an HCP Terraform SAML integration take?
The supplied sources do not give a duration, so the effort depends on your environment. Four drivers matter most: group design, meaning how many authentik groups map to HCP Terraform teams and where those groups come from; the number of organizations and teams; how far your existing SSO already runs on authentik; and the testing scope, from a single admin login to every team's access path. The authentik Terraform Cloud guide covers the SAML setup and is the starting point for a scoped estimate. Ask any partner to break effort down by these drivers so you can compare the work you keep in-house with the work you buy.
Can our team set up SAML for HCP Terraform without a partner?
Yes, if your team has the skills and access to do it. The authentik guide walks through the SAML provider and the Terraform Cloud side, so a team that already runs authentik, understands SAML attributes and controls the HCP Terraform organization settings can handle the core setup. The parts that are easy to underestimate are deciding which groups map to which teams, testing each role before users depend on it, and documenting the result so the next administrator can maintain it. Teams without a clear owner for authentik or without a written test plan usually find that the group and testing work takes longer than the configuration itself. DeployOpen can take this on as a fixed-scope engagement when a team prefers to hand it over.
What access and decisions do we need to provide?
Before work starts, plan to provide these four things:
- authentik admin access to create the SAML provider, the application and its bindings
- HCP Terraform owner access to change the organization's SSO and team settings
- a written test plan listing the test users, the teams they should join and the permissions each should have
- a named owner who can approve group decisions and mappings, so changes do not stall while people wait for a decision
Also confirm how an owner can still sign in to HCP Terraform if SSO fails. Settle this before go-live, not during an outage.
How much does HCP Terraform cost per resource?
HashiCorp's pricing page lists Essentials at $0.10 per resource per month ($0.00013 per hour), Standard at $0.47 per resource per month and Premium at $0.99 per resource per month. Terraform Enterprise, the self-managed edition, and HCP Terraform Europe are custom priced. The recurring cost therefore scales with the managed resources you count. HashiCorp counts a managed resource as one in a state file with mode set to managed, from its first plan or apply, and excludes null resources. All tiers include team management, but the supplied information does not say which tier SAML requires, so confirm that with HashiCorp before you choose a tier. Essentials also limits test-integrated module publishing to 10 modules, while Standard and Premium add unlimited module publishing.
What does authentik cost for this integration?
The open-source edition of authentik is free to use. Its repository is under the MIT license, while code in the enterprise directory falls under a separate enterprise license. The pricing page lists Enterprise at $5 per user per month billed annually plus $0.02 per external user per month, and Enterprise Plus starting at $20k annually. The enterprise-only features listed include Google Workspace and Entra ID integrations, mTLS, privileged access management, password history and enhanced audit logging. SAML is not on that list, but confirm on the pricing page that your edition covers the SAML provider you plan to use. Recurring costs also include hosting, PostgreSQL, upgrades and the time to keep certificates and group mappings current. Ask every quote to name the authentik edition it assumes.
Does HCP Terraform SSO work on the free tier?
According to HashiCorp's blog on the enhanced Free tier, the enhanced Free tier includes unlimited users, SSO, Sentinel and OPA policy as code, run tasks, HCP Terraform agents and cost estimation. It also includes 500 managed resources at no charge. The legacy Free plan reached end of life on March 31, 2026, and remaining organizations were moved automatically to the enhanced tier. Because the free allowance is measured in managed resources, count yours against the 500 limit before you rely on the tier. Confirm the current terms with HashiCorp before you depend on it for production access.
How do we ask a partner for a fixed-scope quote?
Ask for a written scope before you discuss price. DeployOpen agrees scope, deliverables and timelines in writing before work starts, and a quote follows from that written scope. DeployOpen does not publish a price list. Bring the inputs that drive scope: the authentik version and edition you run, the number of HCP Terraform organizations and teams, the groups that map to them, your managed resource count, the test cases you need and the person who approves group decisions. Ask the partner to separate one-time work, such as setup, testing and documentation, from recurring work, such as support or a retainer for upkeep after upgrades. Also ask what is excluded so that the boundary is clear before signing.
How DeployOpen scopes and delivers this integration
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including the authentik SAML provider that signs your team into HCP Terraform. Engagements are fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts.
How we scope
- We confirm which HCP Terraform edition and organization settings your team uses before any configuration begins.
- The written scope lists the authentik SAML provider, application, group mapping and HCP Terraform team assignments.
- We record which groups map to which HCP Terraform teams and who approves each mapping.
How we build
- We configure the authentik SAML provider and application, then verify metadata and certificate exchange with HCP Terraform.
- Group claims are mapped to HCP Terraform teams and tested with accounts from each group.
- We test a break-glass local owner path so administrators keep access if SSO fails.
How we hand over
- You receive a written record of provider settings, group mappings and organization configuration.
- Test results show which groups sign in, which teams they join and which access is denied.
- Operators get a runbook covering certificate renewal, group changes and onboarding new team members.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- We can review authentik release notes and HCP Terraform changes before your team applies an update.
- Support scope and response expectations are set in the retainer agreement, not assumed.
