Skip to content

Commit

Permalink
[docs] - Update Dagster+ OKTA SAML guide to reflect Okta UI changes (…
Browse files Browse the repository at this point in the history
…DOC-307) (#23066)

## Summary & Motivation

This PR updates the Dagster+ Okta SAML guide to reflect some new Okta UI
changes:

- The **Subdomain** field, which was in **General settings**, is now in
**Sign on**. It has been renamed **Organization**.
- The steps to download IdP metadata have changed, [as outlined
here](https://support.okta.com/help/s/article/Location-to-download-Okta-IDP-XML-metadata-for-a-SAML-app-in-the-new-Admin-User-Interface?language=en_US).
Users now have to open the metadata in a new page as XML and then
manually save it.

I've also removed a handful of screenshots that are no longer needed.

## How I Tested These Changes

eyes, testing in Okta
  • Loading branch information
erinkcochran87 authored Aug 5, 2024
1 parent 6aea1a1 commit 9cd950a
Show file tree
Hide file tree
Showing 12 changed files with 43 additions and 39 deletions.
73 changes: 42 additions & 31 deletions docs/content/dagster-plus/account/authentication/okta/saml-sso.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,63 +35,65 @@ To complete the steps in this guide, you'll need:

3. On the **Applications** page, click **Browse App Catalog**.

<Image
alt="Okta Browse App Catalog"
src="/images/dagster-cloud/sso/okta/browse_app_catalog.jpg"
width={1262}
height={296}
/>

4. On the **Browse App Integration Catalog** page, search for `Dagster+`:

<Image
alt="Okta App Integration Catalog"
src="/images/dagster-cloud/sso/okta/app_integration_catalog.png"
width={2531}
height={1395}
/>
4. On the **Browse App Integration Catalog** page, search for `Dagster Cloud`.

5. Add and save the application.

---

## Step 2: Configure SSO in Okta

1. In Okta, open the application and navigate to its **General Settings**.
1. In Okta, open the Dagster Cloud application and navigate to its **Sign On Settings**.

2. Scroll down to the **Advanced Sign-on settings** section.

2. In the **Subdomain** field, enter your Dagster+ organization name. This is used to route the SAML response to the correct Dagster+ subdomain.
3. In the **Organization** field, enter your Dagster+ organization name. This is used to route the SAML response to the correct Dagster+ subdomain.

In the following example, the organization name is `hooli` and our Dagster+ domain is `https://hooli.dagster.cloud`. To configure this correctly, we'd enter `hooli` into the **Subdomain** field:
In the following example, the organization name is `hooli` and our Dagster+ domain is `https://hooli.dagster.cloud`. To configure this correctly, we'd enter `hooli` into the **Organization** field:

<!-- ![Okta Subdomain Configuration](/images/dagster-cloud/sso/okta/subdomain_configuration.png) -->

<Image
alt="Okta Subdomain Configuration"
src="/images/dagster-cloud/sso/okta/subdomain_configuration.jpg"
width={2560}
height={1437}
src="/images/dagster-cloud/sso/okta/subdomain_configuration.png"
width={709}
height={215}
/>

3. When finished, click **Done**.
4. When finished, click **Done**.

---

## Step 3: Upload the SAML metadata to Dagster+

Next, you'll save and upload the application's SAML metadata to Dagster+. This will enable single sign-on.

1. In Okta, navigate to the Dagster+ application.
1. In the **Sign On Settings**, navigate to the **SAML Signing Certificates** section.

2. Navigate to **Sign On**.
2. Click the **Actions** button of the **Active** certificate.

3. Click **Identity Provider metadata** to initiate a download. This will save the SAML metadata file to your computer.
3. Click **View IdP metadata**:

<Image
alt="Okta Save Identity Provider Metadata"
src="/images/dagster-cloud/sso/okta/save_identity_provider_metadata.jpg"
width={1431}
height={687}
alt="The View IdP metadata options in the Okta UI"
src="/images/dagster-cloud/sso/okta/save_identity_provider_metadata.png"
width={1920}
height={970}
/>

4. After you've downloaded the SAML metadata file, upload it to Dagster+ using the `dagster-cloud` CLI:
This will open a new page in your browser with the IdP metadata in XML format.

4. Right-click on the page and use **Save As** or **Save Page As**:

<Image
src="/images/dagster-cloud/sso/okta/save-xml-as-page.png"
width={1920}
height={743}
/>

In Chrome and Edge, the file will be downloaded as an XML file. In Firefox, choose **Save Page As > Save as type**, then select **All files**. **Note**: Copying and pasting the metadata can cause formatting issues that will prevent successful setup. Saving the page directly from the browser will avoid this.

5. After you've downloaded the metadata file, upload it to Dagster+ using the `dagster-cloud` CLI:

```shell
dagster-cloud organization settings saml upload-identity-provider-metadata <path/to/metadata> \
Expand All @@ -116,7 +118,10 @@ Next, you'll assign users to the Dagster+ application in Okta. This will allow t
Lastly, you'll test your SSO configuration:

- [Service provider (SP)-initiated login](#testing-a-service-provider-initiated-login)
- [Identity provider (idP)-initiated login](#testing-an-identity-provider-initiated-login)
- [Identity provider (IdP)-initiated login](#testing-an-identity-provider-initiated-login)

<TabGroup>
<TabItem name="Service provider-initiated">

### Testing a service provider-initiated login

Expand All @@ -126,6 +131,9 @@ Lastly, you'll test your SSO configuration:

3. Initiate the login flow and address issues that arise, if any.

</TabItem>
<TabItem name="Identity provider-initiated">

### Testing an identity provider-initiated login

In the Okta **Applications** page, click the **Dagster+** icon:
Expand All @@ -137,4 +145,7 @@ width={1150}
height={780}
/>

</TabItem>
</TabGroup>

If successful, you'll be automatically signed into your Dagster+ organization.
Original file line number Diff line number Diff line change
Expand Up @@ -57,14 +57,7 @@ To complete the steps in this guide, you'll need:

2. In the **Dagster+ organisation name** field, enter your Dagster+ organization name. This is used to route the SAML response to the correct Dagster+ subdomain.

In the following example, the organization name is `hooli` and our Dagster+ domain is `https://hooli.dagster.cloud`. To configure this correctly, we'd enter `hooli` into the **Subdomain** field:

<Image
alt="Okta Subdomain Configuration"
src="/images/dagster-cloud/sso/okta/subdomain_configuration.jpg"
width={2560}
height={1437}
/>
For example, our organization name is `hooli` and our Dagster+ domain is `https://hooli.dagster.cloud`. To configure this correctly, we'd enter `hooli` into the **Subdomain** field.

3. When finished, click **Done**.

Expand Down
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

1 comment on commit 9cd950a

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deploy preview for dagster-docs ready!

✅ Preview
https://dagster-docs-r9a4mn423-elementl.vercel.app
https://master.dagster.dagster-docs.io

Built with commit 9cd950a.
This pull request is being automatically deployed with vercel-action

Please sign in to comment.