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.

info

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:

• Microsoft Entra ID
• Okta

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)

1. Create an Organization API token with Organization Owner permissions. See Organization API tokens. Copy the token to use later in this setup.

2. In the Astro UI, click Organization Settings.

3. On the General page, copy your Organization ID to use later in this setup.

4. Go to Settings > Authentication. In the Advanced Settings menu, click Edit Settings, then click the SCIM integration toggle to on.

5. In the Okta admin dashboard, open your Astro app integration and click Provisioning.

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

7. Test your API credentials, then click Save.

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

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

Okta - Manual

Complete the manual setup if you configured your existing Astro app without using the Okta app catalogue.

1. Create an Organization API token with Organization Owner permissions. See Organization API tokens. Copy the token to use later in this setup.

2. In the Astro UI, click Organization Settings, then click Authentication.

3. In the Advanced Settings menu, click Edit Settings, then click the SCIM integration toggle to on.

4. Copy the SCIM Integration URL that appears.

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

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

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

Microsoft Entra ID

1. Create an Organization API token with Organization Owner permissions. See Organization API tokens. Copy the token to use later in this setup.

2. In the Astro UI, click Organization Settings, then click Authentication.

3. In the Advanced Settings menu, click Edit Settings, then click the SCIM integration toggle to on.

4. Copy the SCIM Integration URL that appears.

5. Append the Microsoft Entra ID feature flag parameter ?aadOptscim062020 to your SCIM Integration URL and recopy it. For example, if your SCIM Integration URL is https://api.astronomer.io/scim/v2/cknaqyipv05731evsry6cj4n0, your final URL would be https://api.astronomer.io/scim/v2/cknaqyipv05731evsry6cj4n0?aadOptscim062020. The feature flag is required for fully compliant SCIM behavior in Microsoft Entra ID.

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

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

Only provision users

If you prefer to only provision users with SCIM, and you don't want to provision Teams, skip Steps 8-10.

8. In Mappings, open the Groups mapping configuration.

9. In Target Object Actions, tick the checkboxes for Create, Update, and Delete.

10. 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:

    

11. Go back to the Mappings menu and open the User mapping configuration.

12. In Target Object Actions, tick the checkboxes for Create, Update, and Delete.

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

warning

This setup assumes that mail contains your users' email. If you use a field other than mail to define your user email, replace mail with the attribute you use.

Whether you choose to use mail or a different attribute like userPrincipleName, 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:

1. 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?

1. In the Okta dashboard, open the Astro application and click Push Groups.
2. 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.