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):
- Microsoft Entra ID
- Okta
- IdPs managed through Auth0
- Amazon Cognito
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.
- Microsoft Entra ID
- Okta
- Auth0
- AWS Cognito
- Local auth
- General OIDC
Step 1: Register an application using App Registrations
on Azure
-
In Microsoft Entra ID, click App registrations > New registration.
-
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/
.
- Web /
Replace
BASEDOMAIN
with your own. For example, if your base domain isexample.com
, your redirect URIs should behttps://houston.example.com/v1/oauth/redirect/
andhttps://houston.example.com/v1/oauth/callback/
. -
Click Register.
-
Click Authentication in the left menu.
-
In the Web area, confirm the redirect URI is correct.
-
In the Implicit grant and hybrid flows area, select Access tokens and ID tokens.
-
Click Save.
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.
-
In your Microsoft Entra ID application management left menu, click Certificates & secrets.
-
Click New client secret.
-
Enter a description in the Description field and then select an expiry period in the Expires list.
-
Click Add.
-
Copy the values in the Value and Secret ID columns.
-
Click API permissions in the left menu.
-
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:
-
Click Token configuration in the left menu.
-
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.
-
Click Add.
-
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:
astronomer:
houston:
config:
auth:
openidConnect:
flow: "code"
google:
enabled: false
microsoft:
enabled: true
clientId: <your-client-id>
discoveryUrl: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
# Configure a secret only if you're importing Microsoft Entra ID user groups as Teams
clientSecret: <your-client-secret>
baseDomain: login.microsoftonline.com
authUrlParams:
audience: <your-client-id>
github:
enabled: false
Then, push the configuration change to your platform. See Apply a config change.
Step 1: Configure Okta
-
If you haven't already, create an Okta account.
-
In your Okta account, create a new web app for Astronomer.
-
In Okta, under General Settings > Application, set
Login redirect URIs
tohttps://houston.BASEDOMAIN/v1/oauth/redirect/
, whereBASEDOMAIN
is the domain where you're hosting your Software installation. -
Under Allowed grant types, select
Implicit (Hybrid)
. -
Save the
Client ID
generated for this Okta app for use in the next steps. -
Optional. To ensure that an Okta tile appears for Astronomer, set
Initiate Login URI
tohttps://houston.BASEDOMAIN/v1/oauth/start?provider=okta
.
Step 2: Integrate Okta with Astronomer Software
Add the following to your values.yaml
file in your astronomer
directory:
astronomer:
houston:
config:
auth:
openidConnect:
okta:
enabled: true
clientId: "<okta-client-id>"
discoveryUrl: "https://<okta-base-domain>/.well-known/openid-configuration"
Then, push the configuration change to your platform. See Apply a config change.
okta-base-domain
is different from the base domain of your Software installation. See Okta documentation for finding your domain if you are unsure what this value should be.
If you manage your identity provider through Auth0, follow these steps to configure the identity provider for Astro.
Step 1: Create an Auth0 tenant domain
Follow the Auth0 documentation to create a tenant. You can use the default domain name or your own unique tenant-name
. Your full tenant domain looks something like astronomer.auth0.com
.
Your full tenant domain may differ if you've created it outside of the United States.
Step 2: Create a connection between Auth0 and your identity management provider
Follow steps in the the Auth0 connection guide for your identity provider to create an integration between your tenant and identity provider.
Step 3: Configure Auth0 application settings
- Go to
https://manage.auth0.com/dashboard/us/<tenant-name>/applications
. - Under Applications, select Default App.
- Open the Connections tab. You should see your new connection here. Enable your new connection, and disable any connections that you won't be using.
- Open the Settings tab.
- Under Allowed Callback URLs, add
https://houston.<your-astronomer-base-domain>/v1/oauth/redirect/
. - Under Allowed Logout URLs, add
https://app.<your-astronomer-base-domain>/logout
. - Under Allowed Origins (CORS), add
https://*.<your-astronomer-base-domain>
. - Go to
https://manage.auth0.com/dashboard/us/<tenant-name>/apis
. - Click
+ Create API
. - Under Name, enter
astronomer-ee
. - Under Identifier, enter
astronomer-ee
. - Leave the value under Signing Algorithm as
RS256
.
Step 4: Enable Auth0 in your values.yaml file
Add the following to your values.yaml
file in your astronomer
directory:
astronomer:
houston:
config:
auth:
openidConnect:
auth0:
enabled: true
clientId: "<default-app-client-id>"
discoveryUrl: https://<tenant-name>.auth0.com
Then, push the configuration change to your platform as described in Apply a config change.
You can find your clientID
value at https://manage.auth0.com/dashboard/us/<tenant-name>/applications
listed next to 'Default App'.
Step 1: Create a user pool in Cognito
Start by creating a user pool in Cognito. You can either review the default settings or step through them to customize.
Make sure that you create an App client
, which is the OpenID client configuration that Astronomer uses to authenticate against. You do not need to generate a client secret, as Astronomer is a public client that uses implicit flow.
After Auth0 creates the pool and app client, open App integration
>App client settings
and configure the following settings:
- Select an identity provider to use (either the built-in cognito user pool or a federated identity provider).
- Set the callback URL parameter to
https://houston.BASEDOMAIN/v1/oauth/redirect/
. - Enable
Implicit grant
inAllowed OAuth Flows
. Leave the other settings disabled. - Enable
email
,openid
, andprofile
inAllowed OAuth Scopes
.
Then, switch to the Domain name tab and select a unique domain name to use for your hosted Cognito components.
Step 2: Edit your Astronomer configuration
Add the following values to your values.yaml
file in the astronomer/
directory:
astronomer:
houston:
config:
auth:
openidConnect:
cognito:
enabled: true
clientId: <client_id>
discoveryUrl: https://cognito-idp.<AWS-REGION>.amazonaws.com/<COGNITO-POOL-ID>/.well-known/openid-configuration
authUrlParams:
response_type: token
Your Cognito pool ID can be found in the General settings
tab of the Cognito portal. Your client ID is found in the App clients
tab.
After you save your values.yaml
file with these values, push it to your platform. See Apply a config change.
To let users authenticate to Astronomer with a local username and password, follow the steps below.
-
Enable
local auth
in yourvalues.yaml
file:astronomer:
houston:
config:
auth:
local:
enabled: true -
Push the configuration change to your platform. See Apply a config change.
Astronomer supports a generic OIDC configuration to accommodate all OIDC-compliant providers. If there are no specific setup instructions for your OIDC provider in this document, you can add the following configuration to your values.yaml
file.
For example:
astronomer:
houston:
config:
auth:
openidConnect:
clockTolerance: 0 # A field that can optionally be set to adjust for clock skew on the server.
<provider-name>:
enabled: true
discoveryUrl: <provider-discovery-url> # Note this must be a URL that with an https:// prefix
clientId: <provider-client-id>
authUrlParams: # Additional required params set on case-by-case basis
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:
astronomer:
houston:
config:
auth:
openidConnect:
<provider>:
enabled: true
clientId: ...
discoveryUrl: ...
env:
- name: GLOBAL_AGENT_HTTPS_PROXY
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.