Set up SCIM provisioning on Astro
Astro supports integration with the open standard System for Cross-Domain Identity Management (SCIM). Using the SCIM protocol with Astro allows you to automatically provision and deprovision users and Teams based on templates for access and permissions. It also provides better observability through your identity provider for when users and Teams are created or modified across your organization. Specifically, you can utilize SCIM provisioning to complete the following Astro actions from your identity provider platform:
- Create and remove users in your Organization.
- Update user profile information.
- Create and remove Astro Teams.
- Add and remove Team members.
- Retrieve user and Team information.
Some user management features on Astro behave differently after you set up SCIM provisioning. See Manage Teams for more information. Astro does not support group nesting for SCIM provisioning. Access levels assigned to parent groups do not automatically propagate to child groups, so each group must be individually assigned the required access levels.
Supported SSO identity providers
Astro supports SCIM provisioning with the following IdPs:
Supported Okta features
Okta's Astro integration supports the following SCIM actions:
- Create users
- Update user attributes
- Deactivate users
- Group push
Prerequisites
- A configured identity provider. See Set up SSO.
Setup
- Okta - Astro integration (Recommended)
- Okta - Manual
- Microsoft Entra ID
-
Create an Organization API token with Organization Owner permissions. See Organization API tokens. Copy the token to use later in this setup.
-
In the Astro UI, click Organization Settings.
-
On the General page, copy your Organization ID to use later in this setup.
-
Go to Settings > Authentication. In the Advanced Settings menu, click Edit Settings, then click the SCIM integration toggle to on.
-
In the Okta admin dashboard, open your Astro app integration and click Provisioning.
-
Click Configure API integration, check Enable API integration, then configure the following values:
- Organization ID: Enter your Organization ID.
- API token: Enter your Organization API token.
-
Test your API credentials, then click Save.
-
In the Provisioning menu, click To App and configure the following:
- Provisioning to App: Select only Create Users, Update User Attributes, and Deactivate Users.
See Okta documentation for more information on configuring these values.
-
Create user groups and push them to Astro. User groups pushed to Astro appear as Teams in the Astro UI. See Okta documentation for setup steps.
Complete the manual setup if you configured your existing Astro app without using the Okta app catalogue.
-
Create an Organization API token with Organization Owner permissions. See Organization API tokens. Copy the token to use later in this setup.
-
In the Astro UI, click Organization Settings, then click Authentication.
-
In the Advanced Settings menu, click Edit Settings, then click the SCIM integration toggle to on.
-
Copy the SCIM Integration URL that appears.
-
In the Okta admin dashboard, add SCIM provisioning to your existing Astro app integration. Then, open your app in Okta and go to Provisioning > Integration to configure the following values:
- Supported provisioning actions: Select Push New Users, Push Profile Updates, and Push Groups.
- SCIM connector base URL: Enter the SCIM integration URL you copied from the Astro UI.
- Unique identifier field for users:
email. - Authentication Mode: Choose HTTP Header and paste your Organization API token in the Bearer field.
See Okta documentation for more information about setting up SCIM provisioning.
-
In the Provisioning menu, click To App and configure the following:
- Provisioning to App: Select Create Users, Update User Attributes, and Deactivate Users.
- Astro Attribute Mappings: Configure the following mappings:
Attribute Attribute Type Value Apply On Username ( userName)Personal Configured in sign-on settings Given name ( givenName)Personal user.firstName Create and update Family name ( familyName)Personal user.lastName Create and update Email ( email)Personal user.email Create and update Display name ( displayName)Personal user.displayName Create and update Profile Url ( profileUrl)Personal user.profileUrl Create and update See Okta documentation for more information on configuring these values.
-
Create user groups and push them to Astro. User groups pushed to Astro appear as Teams in the Astro UI. See Okta documentation for setup steps.
-
Create an Organization API token with Organization Owner permissions. See Organization API tokens. Copy the token to use later in this setup.
-
In the Astro UI, click Organization Settings, then click Authentication.
-
In the Advanced Settings menu, click Edit Settings, then click the SCIM integration toggle to on.
-
Copy the SCIM Integration URL that appears.
-
Append the Microsoft Entra ID feature flag parameter
?aadOptscim062020to your SCIM Integration URL and recopy it. For example, if your SCIM Integration URL ishttps://api.astronomer.io/scim/v2/cknaqyipv05731evsry6cj4n0, your final URL would behttps://api.astronomer.io/scim/v2/cknaqyipv05731evsry6cj4n0?aadOptscim062020. The feature flag is required for fully compliant SCIM behavior in Microsoft Entra ID. -
In the Microsoft Entra ID management dashboard, create a new enterprise application with the third option, Integrate any other application you don't find in the gallery.
-
In the menu for your new application, click Provisioning and configure the following values:
- Provisioning mode: Set to Automatic.
- Admin Credentials > Tenant URL: Enter the SCIM integration URL including the Microsoft Entra ID feature flag parameter.
- Secret Token: Enter your Organization API token.
If you prefer to only provision users with SCIM, and you don't want to provision Teams, skip Steps 8-10.
-
In Mappings, open the Groups mapping configuration.
-
In Target Object Actions, tick the checkboxes for Create, Update, and Delete.
-
In the Attribute Mappings table, add the following mappings:
Microsoft Entra ID Attribute Astro Attribute displayName displayName members members Delete any other group attributes not listed in the previous table. You should have exactly two attributes as shown in the following screenshot:
-
Go back to the Mappings menu and open the User mapping configuration.
-
In Target Object Actions, tick the checkboxes for Create, Update, and Delete.
-
In the Attribute Mappings table, add the following mappings:
Microsoft Entra ID Attribute Astro Attribute mail userName Switch([IsSoftDeleted], , "False", "True", "True", "False") active displayName displayName To successfully configure the
activemapping in the table, you must first complete these steps:If not already present, create the
activeAttribute:- Click Show advanced options.
- Select Edit attribute list.
- Add a new attribute:
- Name:
active - Type: Boolean
- Name:
- Click Save.
Add the Attribute Mapping using an Expression:
- Go back to Attribute Mappings.
- Click Add New Mapping.
- Change the Type to Expression.
- In the Entra ID Attribute field, enter:
Switch([IsSoftDeleted], , "False", "True", "True", "False") - In the Attribute field, select
active. - Click Save.
warningThis setup assumes that
mailcontains your users' email. If you use a field other thanmailto define your user email, replacemailwith the attribute you use.Whether you choose to use
mailor a different attribute likeuserPrincipleName, you must use the same Microsoft Entra ID Attribute for both your SSO and SCIM configurations.Delete any other user attributes not listed in the previous table. You should have exactly three attributes as shown in the following screenshot:
-
Click Test connection in the Microsoft Entra ID application management menu to confirm your connection to the SCIM endpoint.
Frequently asked questions
What if an Okta group is out of sync with an Astro Team?
- In the Okta dashboard, open the Astro application and click Push Groups.
- Click the value in Push Status for the group that's out of sync, then click Push now.
What if an Okta user is out of sync with their Astro user account?
If you removed an Okta user but their Astro account remains, delete the account from Astro.
If an Astro user is not appearing for an Okta user as expected, remove and re-assign the user in Okta.