Import identity provider groups into Astro Private Cloud

You can import existing identity provider (IdP) groups into Astro Private Cloud as Teams, which are groups of Astro users that have the same set of permissions for a specific Workspace or Deployment. Configuring Teams lets you quickly onboard staff to APC and provides better control of user permissions. Astro Private Cloud supports importing groups from OpenID Connect (OIDC) identity providers. Starting in Astro Private Cloud 2.1, you can also import groups from LDAP directories (OpenLDAP or Active Directory). This document covers both. For the initial LDAP authentication setup that provisions the LDAP connection itself, see Configure LDAP authentication. APC Teams function similar to users. You can:

Assign Teams to both Workspaces and Deployments.
Assign Viewer, Editor, or Admin roles to a Team.
View information about users and permissions from the UI.

After you configure SCIM, you can use templates to add or remove Teams on Astro Private Cloud and manage groups of users directly from your IdP. However, if SCIM isn’t available, you can pre-populate groups through the UI or API following the procedure for Create local teams. With either process, when you create new user groups in the future, you can automatically apply a batch of permissions that they need to access Astro Private Cloud.

Implementation considerations

Before you implement Teams, consider the following:

By default, the first user to sign in to your Astronomer platform is automatically granted SYSTEM ADMIN permissions. If you configure Teams for a new Astronomer installation, Astronomer recommends signing in first as the user responsible for importing your IdP groups using the default Astronomer sign-in flow.
Teams are based solely on the IdP group they are configured from, which means that you can’t configure Team membership from Astronomer.
To remove a Team from your installation, you have to delete it from the Astro Private Cloud UI or the APC API. Deleting an IdP group from your IdP UI doesn’t automatically delete the associated Team.
If a user is added or removed from your original IdP group, that change applies to the related Astronomer Team only after the user logs back in to Astronomer.

Most Permissive Role PriorityAstronomer user roles function on a most permissive policy: If a user has roles defined at both the Workspace and the Team level, then that user will continue to have the most permissive role between the two contexts. This policy has a few implications for implementing Team:

If a user’s most permissive role comes from a Workspace configuration, there is no way to override/ remove this permission from a Team configuration.
If a user’s most permissive role comes from a Team configuration, then there is no way to override/ remove this permission from a Workspace configuration.
Importing a Team from an IdP has no effect on existing Astronomer user roles. Users continue to have permissions from both contexts, with the most permissive role defining how they interact with a given Workspace or Deployment.

For example, consider a user with Workspace Editor permission in a Production Workspace through Astronomer’s default authentication for the last year. Your organization begins using Okta as your authentication system for Astronomer and adds this user to a Team with Workspace Viewer permissions in Production Workspace. Because the user still has Workspace Editor permissions from their original account, they continue to have Workspace Editor permissions in Production Workspace. The only way to remove their Editor permissions is to have a Workspace Admin remove them through Workspace settings.

Prerequisites

To complete this setup, you need:

A configured identity provider — an OIDC provider integrated through Integrate an auth system, or an LDAP directory integrated through Configure LDAP authentication.
System Admin permissions for configuring the feature.
Workspace or Deployment Admin permissions for managing Teams.
For OIDC providers only: an OAuth authorization code flow. See Configure a custom OAuth flow. LDAP doesn’t use OAuth; groups are resolved through LDAP queries at each sign-in.
An IdP group (OIDC) or a directory group (LDAP).

Astronomer also recommends setting up SCIM so that you can manage user groups as Teams directly from your IdP.

Step 1: Enable APC Teams

Add the following values to your values.yaml file. The exact shape depends on whether you provision Teams from an OIDC provider or from an LDAP directory. Save the configuration and push it to your platform as described in Apply a Platform Config Change.

OIDC
LDAP (OpenLDAP)
LDAP (Active Directory)

# Auth configuration.
auth:
  openidConnect:
    idpGroupsImport:
      enabled: true
    # Optional. Set to assign system-level permissions from IdP groups.
    manageSystemPermissionsViaIdpGroups:
      enabled: true
      systemAdmin: ["<your-system-admin-groups>"]     # Only these groups get SYSTEM_ADMIN
      systemEditor: ["<your-system-editor-groups>"]
      systemViewer: ["<your-system-viewer-groups>"]
    # Optional. Restrict which IdP groups become Teams.
    teamFilterRegex: "^astro-"

Astro Private Cloud 2.1This feature was introduced in Astro Private Cloud 2.1. To access this feature, upgrade your Astro Private Cloud installation to 2.1 or later.

# Auth configuration.
auth:
  ldap:
    enabled: true
    # The rest of the LDAP connection (host, bindDn, searchBase, etc.) is set up
    # in Configure LDAP authentication. This block only adds the group-import
    # settings on top of a working LDAP configuration.
    groups:
      enabled: true
      reconcileTeams: true                             # Turn resolved LDAP groups into Teams
      searchBase: "ou=groups,dc=corp,dc=example,dc=com"
      searchFilter: "(member={{dn}})"
      # Optional. Restrict which LDAP groups become Teams. LDAP-scoped —
      # separate from auth.openidConnect.teamFilterRegex.
      teamFilterRegex: "^astro-"
      # Optional. Assign system-level permissions from LDAP groups.
      manageSystemPermissions:
        enabled: true
        systemAdmin: ["astro-platform-admins"]
        systemEditor: ["astro-workspace-editors"]
        systemViewer: ["astro-observers"]

Astro Private Cloud 2.1This feature was introduced in Astro Private Cloud 2.1. To access this feature, upgrade your Astro Private Cloud installation to 2.1 or later.

# Auth configuration.
auth:
  ldap:
    enabled: true
    # The rest of the LDAP connection (host, bindDn, searchBase, etc.) is set up
    # in Configure LDAP authentication. This block only adds the group-import
    # settings on top of a working LDAP configuration.
    groups:
      enabled: true
      reconcileTeams: true                             # Turn resolved AD groups into Teams
      nestedGroups: "ad"                               # Use LDAP_MATCHING_RULE_IN_CHAIN for transitive membership
      searchBase: "CN=Users,DC=corp,DC=example,DC=com"
      # Optional. Restrict which AD groups become Teams. LDAP-scoped —
      # separate from auth.openidConnect.teamFilterRegex.
      teamFilterRegex: "^Astro-"
      # Optional. Assign system-level permissions from AD groups.
      manageSystemPermissions:
        enabled: true
        systemAdmin: ["Astro Platform Admins"]
        systemEditor: ["Astro Workspace Editors"]
        systemViewer: ["Astro Observers"]

The auth.ldap.groups.teamFilterRegex field is applied only to LDAP-resolved groups. It has no effect on OIDC-provisioned Teams, which use auth.openidConnect.teamFilterRegex — the two filters are independent. For the full LDAP-specific behavior see Configure LDAP authentication.

Disabling manageSystemPermissionsViaIdpGroups.enabled (OIDC) or groups.manageSystemPermissions.enabled (LDAP) stops future synchronization from directory groups but doesn’t revoke roles that were previously auto-assigned. Existing system role assignments remain in place until you remove them manually in the Astro Private Cloud UI, in Settings > Teams.

Step 2: Add a group claim to your IdP group (OIDC only)

This step applies only when you provision Teams from an OIDC identity provider. LDAP directories don’t use token-based group claims — Houston resolves LDAP groups through a direct LDAP query on every sign-in based on the auth.ldap.groups.* configuration you set in Step 1. Skip to Step 3 if you provision Teams from LDAP.

To add your IdP group to Astronomer as a Team, Astronomer needs to be able to recognize the IdP group through a group claim and assign members from the group through tokens. If you haven’t already, add group claims to the IdP groups that you’re importing to Astronomer through your configured third party identity provider. Refer to your IdP’s documentation for information on how to complete this step. For example, for Okta you can refer to Customize tokens returned from Okta with a Groups claim.

By default, Astronomer assumes that the name of your group claim is groups. If you named your group claim something other than groups, complete the following setup:

In your values.yaml file, set houston.config.auth.openidConnect.<idp-provider>.claimsMapping to the custom name of your group claim.
Save this configuration and push it to your platform. See Apply a Platform Config Change.

Step 3: Add Teams to Workspaces and Deployments

After you complete Step 1, Astro Private Cloud provisions Teams automatically the first time an eligible user signs in:

OIDC: Houston reads the group claim from the user’s OIDC token and creates one Team per matching group, tagged with the OIDC provider name (for example, google, microsoft, okta).
LDAP: Houston resolves the user’s directory groups according to the auth.ldap.groups.nestedGroups mode you set in Step 1 and creates one Team per resolved group, tagged with provider='ldap'. See Configure LDAP authentication for the resolution modes.

You don’t need to pre-create Teams — the sign-in flow provisions them. After a Team appears on the System Admin > Teams page, Workspace Admins and Deployment Admins can assign it to Workspaces and Deployments through the UI in the same way they assign individual users.

You can use the System Admin > Teams > Create Team dialog to pre-create Teams before any group member signs in, but the Provider dropdown in that dialog lists only local (when local Teams are enabled) and OIDC providers. LDAP doesn’t appear in the dropdown. For LDAP-provisioned Teams, wait for the first sign-in from a member of the directory group — the Team appears automatically after Houston reconciles it.

Create local teams

If you want to create a Team of Astronomer users, and the team doesn’t map to a group in the IdP, you can enable local team creation. This means that if SCIM sync isn’t available, you don’t have to wait for a user to sign in to Astro Private Cloud for their IdP user groups to sync. You can instead create teams using a locally available source of users. To enable the feature, add the following configuration to your values.yaml file and apply the change to your installation.

astronomer:
  houston:
    config:
      # Auth configuration.
      auth:
      # Local database (user/pass) configuration.
        local:
          enabled: true
          teams:
            enabled: true

Then, to create a local Team:

In the UI, open the System Admin menu, then click Teams.
Click Create Team.
Give the team a name and a description, then select all the users that you want in the Team.
(Optional) Grant the Team a System Level Role if the Team needs system-level permissions.

You can now add the local Team to a Workspace or Deployment as you would with an IdP Team or an individual user.

Disable individual user management

To use Teams as the only user management system on Astro Private Cloud, add the following entry to your values.yaml file:

astronomer:
  houston:
    config:
      userManagement:
        enabled: false

Save this configuration and push it to your platform. See Apply a Platform Config Change. After you apply the configuration, individual users can’t be invited or assigned Workspace or Deployment-level roles in Astro Private Cloud. Users must be invited through a Team by a System Admin, and only Teams can be assigned roles for Workspaces and Deployments. You can still create individual service accounts with Workspace and Deployment permissions.

Overview

Architecture

Upgrade to Astro Private Cloud 2.0

Install Astro Private Cloud

Develop Dags

Airflow administration

Airflow 3

Deploy Dags

Manage Deployments

Platform administration

Manage Platform resources

Security and compliance

APC API

Platform Observability

Release notes

Reference

Import identity provider groups into Astro Private Cloud

Implementation considerations

Prerequisites

Step 1: Enable APC Teams

Step 2: Add a group claim to your IdP group (OIDC only)

Step 3: Add Teams to Workspaces and Deployments

Create local teams

Disable individual user management

​Implementation considerations

​Prerequisites

​Step 1: Enable APC Teams

​Step 2: Add a group claim to your IdP group (OIDC only)

​Step 3: Add Teams to Workspaces and Deployments

​Create local teams

​Disable individual user management

Implementation considerations

Prerequisites

Step 1: Enable APC Teams

Step 2: Add a group claim to your IdP group (OIDC only)

Step 3: Add Teams to Workspaces and Deployments

Create local teams

Disable individual user management