AdministrationUser access and management

Configure authentication and configure an identity provider on Astronomer Software

An auth system determines how users can log in to Astronomer Software. By default, Astronomer Software allows users to create an account and authenticate using one of the following methods:

  • Google OAuth
  • GitHub OAuth
  • Local username/password

Integrating an external identity provider (IdP) greatly increases the security of your platform. When you integrate your IdP into Astronomer Software:

  • Users no longer need to repeatedly login and remember credentials for their account.
  • You have complete ownership over credential configuration and management on Astro.
  • You can enforce multi-factor authentication (MFA) for users.

In addition to the default methods, Astronomer provides the option to integrate any IdP that follows the Open Id Connect (OIDC) protocol. This includes (but is not limited to):

After you integrate your IdP, you can invite users that already have an account on your IdP to Astronomer Software. For a more advanced integration, you can configure SCIM so that you can manage users directly from your IdP and import batches of users into Astronomer Software as Teams.

The following setups assume that you are using the default Astronomer implicit flow as your authorization flow. To implement a custom authorization flow, see Configure a Custom OAuth Flow.

Step 1: Register an application using App Registrations on Azure

  1. In Microsoft Entra ID, click App registrations > New registration.

  2. Complete the following sections:

    • Name: Any
    • Supported account types: Accounts in this organizational directory only (Astronomer only - single tenant)
    • Redirect URIs:
      • Web / https://houston.BASEDOMAIN/v1/oauth/redirect/.
      • Web / https://houston.BASEDOMAIN/v1/oauth/callback/.

    Replace BASEDOMAIN with your own. For example, if your base domain is example.com, your redirect URIs should be https://houston.example.com/v1/oauth/redirect/ and https://houston.example.com/v1/oauth/callback/.

  3. Click Register.

  4. Click Authentication in the left menu.

  5. In the Web area, confirm the redirect URI is correct.

  6. In the Implicit grant and hybrid flows area, select Access tokens and ID tokens.

  7. Click Save.

authentication.png

Step 2: (Optional) Create a client secret

Complete this setup only if you want to import Microsoft Entra ID groups to Astronomer Software as Teams.

  1. In your Microsoft Entra ID application management left menu, click Certificates & secrets.

  2. Click New client secret.

  3. Enter a description in the Description field and then select an expiry period in the Expires list.

  4. Click Add.

  5. Copy the values in the Value and Secret ID columns.

  6. Click API permissions in the left menu.

  7. Click Microsoft Graph and add the following minimum permissions for Microsoft Graph:

    • email
    • Group.Read.All
    • openid
    • profile
    • User.Read

    For each of these permissions, select Grant Admin Consent for Astronomer Data. Your Microsoft Graph permissions should look similar to the following image:

    Completed permissions page in Azure

  8. Click Token configuration in the left menu.

  9. Click Add groups claim and select the following options:

    • In the Select group types to include in Access, ID, and SAML tokens area, select every option.
    • In Customize token properties by type area, expand ID, Access, and SAML and then select Group ID for each type.

  10. Click Add.

  11. Encrypt the secret value you copied as a Kubernetes Secret on your Astronomer installation. See Store and encrypt identity provider secrets.

Step 3: Enable Microsoft Entra ID in your values.yaml file

Add the following values to your values.yaml file:

1astronomer:
2  houston:
3    config:
4      auth:
5        openidConnect:
6          flow: "code"
7          google:
8            enabled: false
9          microsoft:
10            enabled: true
11            clientId: <your-client-id>
12            discoveryUrl: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
13            # Configure a secret only if you're importing Microsoft Entra ID user groups as Teams
14            clientSecret: <your-client-secret>
15            baseDomain: login.microsoftonline.com
16            authUrlParams:
17              audience: <your-client-id>
18        github:
19          enabled: false

Then, push the configuration change to your platform. See Apply a config change.

Running behind an HTTPS proxy

Integrating an external identity provider with Astronomer requires that the platform’s Houston API component is able to make outbound HTTPS requests to those identity providers in order to fetch discovery documents, sign keys, and ask for user profile information upon login/signup.

If your install is configured without a direct connection to the internet you will need to configure an HTTPS proxy server for Houston.

Configure an HTTPS proxy server for Houston

To configure the proxy server used we need to set the GLOBAL_AGENT_HTTPS_PROXY Environment Variable for the Houston deployment.

To do so, add the following to the Houston section of the values.yaml file in your astronomer directory:

1astronomer:
2  houston:
3    config:
4      auth:
5        openidConnect:
6          <provider>:
7            enabled: true
8            clientId: ...
9            discoveryUrl: ...
10    env:
11      - name: GLOBAL_AGENT_HTTPS_PROXY
12        value: http://my-proxy:3129

Then, push the configuration change to your platform as described in Apply a config change.

Configure a custom OAuth flow

Starting with Astronomer v0.27, you can set up a custom OAuth authorization flow as an alternative to Astronomer’s default implicit flow. You can customize Astronomer’s existing Okta, Google, and GitHub OAuth flows or import an entirely custom OAuth flow.

This setup must be completed only during a scheduled maintenance window. There should be no active users on your installation until the setup has been finalized.

Step 1: Configure your authorization flow on Astronomer

To use a custom Oauth authorization code flow:

  1. In your values.yaml file, set the astronomer.houston.config.auth.openidConnect.flow value to "code":

    1astronomer:
    2  houston:
    3    config:
    4      auth:
    5      # Local database (user/pass) configuration.
    6        local:
    7          enabled: true
    8
    9      openidConnect:
    10      # Valid values are "code" and "implicit"
    11      flow: "code"

  2. Configure the section of your values.yaml file specific to your identity provider with each of the following values:

    • enabled: Set this value to true under the section for your own identity provider.
    • clientId and clientSecret: Your Client ID and Client secret
    • discoveryURL: Your base Discovery URL
    • authUrlParams: Additional parameters to append to your discovery URL. At a minimum, you must configure audience. Refer to your identity provider’s documentation for information on how to find this value (Auth0 maintains this information in their glossary, for example).

    For example, a custom configuration of Okta might look like the following.

    1astronomer:
    2  houston:
    3    config:
    4      auth:
    5        okta:
    6          enabled: true
    7          clientId: ffhsdf78f734h2fsd
    8          clientSecret: FSDFSLDFJELLGJLSDFGJL42353425
    9          discoveryUrl: "https://<your-idp-url>.okta.com/oauth2/default/.well-known/openid-configuration"
    10          authUrlParams:
    11            audience: "GYHWEYHTHR443fFEW"
    1. Push your configuration changes to your platform as described in Apply a config change.

You can also pass your auth configurations as environment variables in the Houston section of your values.yaml file. If you choose to configure your installation this way, set the following variables in the astronomer.houston.env list instead of setting values in astronomer.auth:

1# Replace <idp-provider> with OKTA, AUTH0, or CUSTOM
2AUTH__OPENID_CONNECT__<idp-provider>__ENABLED="true"
3AUTH__OPENID_CONNECT__<idp-provider>__CLIENT_ID="<client-id>"
4AUTH__OPENID_CONNECT__<idp-provider>__CLIENT_SECRET="<client-secret>"
5AUTH__OPENID_CONNECT__<idp-provider>__DISCOVERY_URL="<discovery-url>
6AUTH__OPENID_CONNECT__<idp-provider>__AUTH_URL_PARAMS__AUDIENCE="<audience>"
7AUTH__OPENID_CONNECT__FLOW="implicit" # or "code"
8AUTH__OPENID_CONNECT__<idp-provider>__BASE_DOMAIN="<base-domain>"
9AUTH__OPENID_CONNECT__CUSTOM__DISPLAY_NAME="Custom OAuth" # Only used for custom flows

For further security, you can specify the values of these environment variables as Kubernetes secrets in the astronomer.houston.secret list. See Store and encrypt identity provider secrets.

Step 2: Configure your identity provider

To finalize your configuration, configure the following key values in your identity provider’s settings:

  • Grant Code: Set to “Code” or “Auth Code” depending on your identity provider.
  • Sign-in Redirect URI: Set to https://houston.<BASE_DOMAIN>/v1/oauth/callback/. Be sure to include the trailing /.

Step 3: Confirm your installation

When you complete this setup, you should be able to see the differences in login flow when logging in at <BASE_DOMAIN>.astronomer.io.

If you configured a fully custom OAuth flow, you should see a new Log in with Custom Oauth button on the Astronomer login screen:

Custom login button on the Astronomer login screen

You can see the name you configured in AUTH__OPENID_CONNECT__CUSTOM__DISPLAY_NAME when authenticating using the Astro CLI.

Manage users and Teams with SCIM

Astronomer Software supports integration with the open standard System for Cross-Domain Identity Management (SCIM). Using the SCIM protocol with Astronomer Software allows you to automatically provision and deprovision users and Teams based on templates that define permission and accesses. It also centralizes user management so that you can configure Astronomer user permissions directly from your identity provider (IdP).

SCIM works because the IdP pushes updates about users and teams to Astronomer Software. This means your Astronomer Software platform must be connected to the internet to receive those updates. If you are running Astronomer Software without exposing it to the internet, there might be solutions for routing SCIM traffic depending on your combination of cloud provider and IdP. Contact Astronomer support for more information.

  1. In Okta Admin dashboard, go to Applications > Applications.

  2. Click Browse App catalog

  3. Search for SCIM 2.0, then select the option that includes Basic Auth. The configuration page for the SCIM integration appears.

  4. Complete the General Settings page, then click Next.

  5. Complete the Sign-On Options page and click Done.

  6. Return to the Applications menu and search for the integration you just created. Click the integration to open its settings.

  7. Click Provisioning, then click Configure API integration.

  8. Tick the Enable API integration checkbox, then configure the following values:

    • SCIM connector base URL: https://astro-software-host/v1/scim/v2/okta
    • Authentication mode: Basic Auth
      • Username: <your-provisioning-account-username>
      • Password: <your-provisioning-account-password>

  9. Click General, then click Edit. Give your application a name and configure any other required general settings.

  10. Go to Push Groups page and create a rule for Group Push. See Group Push.

  11. On the Assignments tab, ensure that the right users and groups in your org are assigned to the app integration. See Use the Assign Users to App action.

  12. Follow the steps in Store and encrypt identity provider secrets to store your provisioning account credentials as a Kubernetes secret. Your secret configuration should look similar to the following:

    1# Required configuration for all secrets
    2kind: Secret
    3apiVersion: v1
    4metadata:
    5     name: okta-provisioning-secret
    6     labels:
    7        release: {{ .Release.Name }}
    8        chart: {{ .Chart.Name }}
    9        heritage: {{ .Release.Service }}
    10        component: {{ template "houston.backendSecret" . }}
    11type: Opaque
    12# Specify a key and value for the data you want to encrypt
    13data:
    14    okta_provisioning_account_secret: {{ "<your-provisioning-account-username>:<your-provisioning-account-password>" | b64enc | quote }}

  13. Add the following lines to your values.yaml file:

    1astronomer:
    2  houston:
    3    secret:
    4      - envName: "SCIM_AUTH_CODE_OKTA"
    5        secretName: "okta-provisioning-secret"
    6        secretKey: "okta_provisioning_account_secret"

  14. Push the configuration change. See Apply a config change.

See Add SCIM provisioning to app integrations for more information about configuring SCIM within Okta.

Store and encrypt identity provider secrets

You can prevent your identity provider passwords, authorization tokens, and security keys from being exposed as plain text by encrypting them in Kubernetes secrets.

This setup is primarily used for encrypting the required secrets for configuring a custom OAuth flow, but can also be used to encrypt any secrets used in your Helm configuration.

  1. Create a file named secret.yaml that contains the value you want to encrypt as a Kubernetes secret. For example, the following configuration encrypts the required client secret for configuring a custom OAuth flow for Okta.

    1# Required configuration for all secrets
    2kind: Secret
    3apiVersion: v1
    4metadata:
    5     name: okta-secret
    6     labels:
    7        release: {{ .Release.Name }}
    8        chart: {{ .Chart.Name }}
    9        heritage: {{ .Release.Service }}
    10        component: {{ template "houston.backendSecret" . }}
    11type: Opaque
    12# Specify a key and value for the data you want to encrypt
    13data:
    14    okta_client_secret: {{ "<okta-secret-value>" | b64enc | quote }}

  2. Run the following command to apply your secret to your Astronomer cluster:

    1kubectl apply -f ./secret.yaml

  3. Reference your secret name, key, and the environment variable you want the key to apply towards in your values.yaml file. To configure the example secret from Step 1 as an Okta client secret, you would add the following:

    1astronomer:
    2  houston:
    3    secret:
    4      - envName: "AUTH__OPENID_CONNECT__OKTA__CLIENT_SECRET"
    5        secretName: "okta-secret"
    6        secretKey: "okta_client_secret"

  4. Save and push your changes. See Apply a config change.