From bbe3b1ba82b270b634ee6363a6f3397eb8b7e992 Mon Sep 17 00:00:00 2001 From: Mark Drake <33191761+SharpRake@users.noreply.github.com> Date: Tue, 29 Oct 2024 08:58:41 -0700 Subject: [PATCH] adding login details to custom idp docs, centering/adjusting images (#1866) ## Type of change This PR adds information to each of the three IDP example docs about how to actually log in with the new identity provider. I also went ahead and resized and centered the images in each doc because: why not? ### What should this PR do? Resolves https://github.com/chainguard-dev/internal/issues/4329 ### Why are we making this change? This came from a customer request about the microsoft entra id doc specifically (see [this thread](https://chainguard-dev.slack.com/archives/C04PYHWPE1F/p1728673068946739) from @cartyc) ### What are the acceptance criteria? ### How should this PR be tested? Should read well, images should look ok. --------- Signed-off-by: Mark Drake --- .../custom-idps/ms-entra-id/index.md | 34 +++++++++++++----- .../administration/custom-idps/okta/index.md | 27 ++++++++++---- .../{okta_2_create_buttons.png => okta-2.png} | Bin ...{okta_3_new-web-app-int.png => okta-3.png} | Bin ...kta_6_open_id_connect-2.png => okta-6.png} | Bin .../custom-idps/ping-id/index.md | 30 ++++++++++++---- 6 files changed, 69 insertions(+), 22 deletions(-) rename content/chainguard/administration/custom-idps/okta/{okta_2_create_buttons.png => okta-2.png} (100%) rename content/chainguard/administration/custom-idps/okta/{okta_3_new-web-app-int.png => okta-3.png} (100%) rename content/chainguard/administration/custom-idps/okta/{okta_6_open_id_connect-2.png => okta-6.png} (100%) diff --git a/content/chainguard/administration/custom-idps/ms-entra-id/index.md b/content/chainguard/administration/custom-idps/ms-entra-id/index.md index b141e3f1f3..a0558ea577 100644 --- a/content/chainguard/administration/custom-idps/ms-entra-id/index.md +++ b/content/chainguard/administration/custom-idps/ms-entra-id/index.md @@ -7,7 +7,7 @@ lead: "" description: "Procedural tutorial on how to register a Microsoft Entra ID Application and integrate it with the Chainguard platform." type: "article" date: 2023-04-17T08:48:45+00:00 -lastmod: 2024-09-25T15:22:20+01:00 +lastmod: 2024-10-28T15:22:20+01:00 draft: false tags: ["CHAINGUARD IMAGES", "PROCEDURAL"] images: [] @@ -31,11 +31,13 @@ To complete this guide, you will need the following. To integrate Microsoft Entra ID with the Chainguard platform, log in to [Azure](https://azure.microsoft.com). In the left-hand navigation menu, select **Microsoft Entra ID**. -![Screenshot of Azure's left-hand navigation menu, with the "Microsoft Entra ID" option highglighted in a yellow box.](meid-0.png) +
Screenshot of Azure's left-hand navigation menu, with the 'Microsoft Entra ID' option highglighted in a yellow box.
+
From the Default Directory **Overview** page, click the **➕ Add** button and select **App Registration** from the dropdown menu. -![Screenshot of the Overview in the Azure console. The "Add" dropdown menu has been opened and the "App Registration" option is highlighted in a yellow box.](meid-1.png) +
Screenshot of the Overview in the Azure console. The
+
In the **Register an application** screen, configure the application as follows. @@ -43,7 +45,8 @@ In the **Register an application** screen, configure the application as follows. * **Supported account types**: Select the **Single tenant** option so that only your organization can use this application to authenticate to Chainguard. * **Redirect URI**: Set the platform to **Web** and the redirect URI to `https://issuer.enforce.dev/oauth/callback`. -![Screenshot of the Register an application screen with the following settings selected: the Name is set to "chainguard"; Supported account types is set to the "Accounts in this organizational directory only (default Directory only - Single tenant)" option; and the Redirect URI is set to "Web" with "https://issuer.enforce.dev/oauth/callback" set as the URI.](meid-2.png) +
Screenshot of the Register an application screen with the following settings selected: the Name is set to 'chainguard'; Supported account types is set to the 'Accounts in this organizational directory only (default Directory only - Single tenant)' option; and the Redirect URI is set to 'Web' with 'https://issuer.enforce.dev/oauth/callback' set as the URI.
+
Save your configuration by clicking the **Register** button. @@ -51,16 +54,18 @@ Next, you can optionally set additional branding for the application by selectin Here you can set additional metadata for the application, including a Chainguard logo icon here to help your users visually identify this integration. If you'd like, you can use the icon from the [Chainguard Console](https://console.chainguard.dev/logo512.png). The console homepage is [console.chainguard.dev](https://console.chainguard.dev), and our terms of service and private statements can be found at [chainguard.dev/terms-of-service](https://www.chainguard.dev/terms-of-service) and [chainguard.dev/privacy-notice](https://www.chainguard.dev/privacy-notice), respectively. -![Screenshot of the Branding & properties screen with the following settings: Name is set to "Chainguard"; Logo shows the sample Linky logo uploaded; Home page URL is set to "https://console.chainguard.dev"; Terms of service URL is set to "https://www.chainguard.dev/terms-of-service"; and the Privacy statement URL is set to "https://www.chainguard.dev/privacy-notice".](meid-3.png) +
Screenshot of the Branding & properties screen with the following settings: Name is set to 'Chainguard'; Logo shows the sample Linky logo uploaded; Home page URL is set to 'https://console.chainguard.dev'; Terms of service URL is set to 'https://www.chainguard.dev/terms-of-service'; and the Privacy statement URL is set to 'https://www.chainguard.dev/privacy-notice.
+
Finally, navigate to the **Certificates & secrets** tab in the **Manage** dropdown to create a client secret to authenticate the Chainguard platform to Microsoft Entra ID. Select **New client secret** to add a client secret. In the resulting modal window, add a description and set an expiration date. -![Screenshot showing the Certificates & secrets landing page with the Add a client secret screen opened. The "Certificates & secrets" tab is highlighted in yellow, as is the "New client secret" button.](meid-4.png) +
Screenshot showing the Certificates & secrets landing page with the Add a client secret screen opened. The 'Certificates & secrets' tab is highlighted in yellow, as is the 'New client secret' button.
+
Finally, take note of the client secret “Value” that is created. You'll need this to configure the Chainguard platform to use this Microsoft Entra ID application. -![Screenshot showing the "Client secrets" tab, with the Value highlighted in yellow.](meid-5.png) - +
Screenshot showing the 'Client secrets' tab, with the Value highlighted in yellow.
+
## Configuring Chainguard to use Microsoft Entra ID @@ -80,7 +85,8 @@ To configure Chainguard, make a note of the following details from your Microsof * **Client Secret**: You noted this down when you set up the client secret in the previous step. * **Directory (tenant) Id**: This can also be found on the **Overview** tab of the Chainguard application. -![Screenshot of a portion of the Overview page showing the "Essentials" information. The Application (client) ID and the Directory (tenant) ID are both highlighted in yellow boxes, though their values have been blurred.](meid-6.png) +
Screenshot of a portion of the Overview page showing the 'Essentials' information. The Application (client) ID and the Directory (tenant) ID are both highlighted in yellow boxes, though their values have been blurred.
+
You will also need the UIDP for the Chainguard organization under which you want to install the identity provider. Your selection won’t affect how your users authenticate but will have implications on who has permission to modify the SSO configuration. @@ -122,3 +128,13 @@ chainctl iam identity-provider create \ Note the `--default-role` option. This defines the default role granted to users registering with this identity provider. This example specifies the `viewer` role, but depending on your needs you might choose `editor` or `owner`. If you don't include this option, you'll be prompted to specify the role interactively. For more information, refer to the [IAM and Security section](/chainguard/administration/custom-idps/custom-idps/#iam-and-security) of our Introduction to Custom Identity Providers in Chainguard tutorial. You can refer to our [Generic Integration Guide](/chainguard/administration/custom-idps/custom-idps/#generic-integration-guide) in our Introduction to Custom Identity Providers doc for more information about the `chainctl iam identity-provider create` command and its required options. + +To log in to the Chainguard Console with the new identity provider you just created, navigate to [console.chainguard.dev](https://console.chainguard.dev) and click **Use Your Identity Provider**. Next, click **Use Your Organization Name** and enter the name of the organization associated with the new identity provider. Finally, click the **Login with Provider** button. This will open up a new window with the Microsoft Entra ID login flow, allowing you to complete the login process through there. + +You can also use the custom identity provider to log in through `chainctl`. To do this, run the `chainctl auth login` command and add the `--identity-provider` option followed by the identity provider's ID value: + +```sh +chainctl auth login --identity-provider +``` + +The ID value appears in the `ID` column of the table returned by the `chainctl iam identity-provider create` command you ran previously. You can also retrieve this table at any time by running `chainctl iam identity-provider ls -o table` when logged in. diff --git a/content/chainguard/administration/custom-idps/okta/index.md b/content/chainguard/administration/custom-idps/okta/index.md index d20da7580c..d9d48447a1 100644 --- a/content/chainguard/administration/custom-idps/okta/index.md +++ b/content/chainguard/administration/custom-idps/okta/index.md @@ -5,7 +5,7 @@ lead: "" description: "Procedural tutorial on how to create an Okta App Integration" type: "article" date: 2023-04-17T08:48:45+00:00 -lastmod: 2024-06-26T15:22:20+01:00 +lastmod: 2024-10-28T15:22:20+01:00 draft: false tags: ["Chainguard Images", "Procedural"] images: [] @@ -29,11 +29,13 @@ To complete this guide, you will need the following. To integrate your Okta identity provider with the Chainguard platform, [log in to Okta](https://www.okta.com/login/) and navigate to the **Applications** landing page in the Admin console. There, click the **Create App Integration** button. -![Screenshot of the Okta Admin console, showing the Applications landing page. "Applications" is circled in the left hand sidebar menu, as is the "Create App Integration" button.](okta-1.png) +
Screenshot of the Okta Admin console, showing the Applications landing page. 'Applications' is circled in the left hand sidebar menu, as is the 'Create App Integration' button.
+
Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type. -![Screenshot of the Okta Admin console, showing the "Create a new app integration" modal window. This image shows the "OIDC - Open ID Connect" option selected next to "Sign-in Method", and the "web Application" option selected next to "Application type."](okta_2_create_buttons.png) +
Screenshot of the Okta Admin console, showing the 'Create a new app integration' modal window. This image shows the 'OIDC - Open ID Connect' option selected next to 'Sign-in Method', and the 'web Application' option selected next to 'Application type'.
+
Next, in the **General Settings** window, configure the application as follows. @@ -46,15 +48,18 @@ Next, in the **General Settings** window, configure the application as follows. * **Sign-in redirect URIs**: Set the redirect URI to `https://issuer.enforce.dev/oauth/callback` * **Sign-out redirect URIs**: This will have a URI field set to `http://localhost:8080` by default. Click the **X** icon to remove the sign-out redirect entirely, leaving this field blank. -![Screenshot of the New Web App Integration process, showing the General Settings window. This window shows the following options: App integration name is set to "Chainguard"; Grant type is set to "Authorization Code"; Sign-in redirect URIs is set to "https://issuer.enforce.dev/oauth/callback"; and there are no URIs listed under Sign-out redirect URIs.](okta_3_new-web-app-int.png) +
Screenshot of the New Web App Integration process, showing the General Settings window. This window shows the following options: App integration name is set to 'Chainguard'; Grant type is set to 'Authorization Code'; Sign-in redirect URIs is set to 'https://issuer.enforce.dev/oauth/callback'; and there are no URIs listed under Sign-out redirect URIs.
+
Click the **Save** button. Then, select the **Sign On** tab. Find the **OpenID Connect ID Token** section and click the **Edit** button. -![Screenshots showing the OpenID Connect ID Token section of the Sign On tab. The Sign On tab and the relevant Edit button are circled in red.](okta-4-5.png) +
Screenshots showing the OpenID Connect ID Token section of the Sign On tab. The Sign On tab and the relevant Edit button are circled in red.
+
Set the **Issuer** option to **Okta URL**, then click the **Save** button. -![Screenshot showing the OpenID Connect ID Token section being edited. The Issuer field is set to the "Okta URL" option, while the rest of the options are set as their default options.](okta_6_open_id_connect-2.png) +
Screenshot showing the OpenID Connect ID Token section being edited. The Issuer field is set to the 'Okta URL' option, while the rest of the options are set as their default options.
+
That completes our configuration of the Okta Application. Next, we need to configure the Chainguard platform to use our Okta application. @@ -116,3 +121,13 @@ chainctl iam identity-provider create \ Note the `--default-role` option. This defines the default role granted to users registering with this identity provider. This example specifies the `viewer` role, but depending on your needs you might choose `editor` or `owner`. If you don't include this option, you'll be prompted to specify the role interactively. For more information, refer to the [IAM and Security section](/chainguard/administration/custom-idps/custom-idps/#iam-and-security) of our Introduction to Custom Identity Providers in Chainguard tutorial. You can refer to our [Generic Integration Guide](/chainguard/administration/custom-idps/custom-idps/#generic-integration-guide) in our Introduction to Custom Identity Providers article for more information about the `chainctl iam identity-provider create` command and its required options. + +To log in to the Chainguard Console with the new identity provider you just created, navigate to [console.chainguard.dev](https://console.chainguard.dev) and click **Use Your Identity Provider**. Next, click **Use Your Organization Name** and enter the name of the organization associated with the new identity provider. Finally, click the **Login with Provider** button. This will open up a new window with the Okta login flow, allowing you to complete the login process through there. + +You can also use the custom identity provider to log in through `chainctl`. To do this, run the `chainctl auth login` command and add the `--identity-provider` option followed by the identity provider's ID value: + +```sh +chainctl auth login --identity-provider +``` + +The ID value appears in the `ID` column of the table returned by the `chainctl iam identity-provider create` command you ran previously. You can also retrieve this table at any time by running `chainctl iam identity-provider ls -o table` when logged in. \ No newline at end of file diff --git a/content/chainguard/administration/custom-idps/okta/okta_2_create_buttons.png b/content/chainguard/administration/custom-idps/okta/okta-2.png similarity index 100% rename from content/chainguard/administration/custom-idps/okta/okta_2_create_buttons.png rename to content/chainguard/administration/custom-idps/okta/okta-2.png diff --git a/content/chainguard/administration/custom-idps/okta/okta_3_new-web-app-int.png b/content/chainguard/administration/custom-idps/okta/okta-3.png similarity index 100% rename from content/chainguard/administration/custom-idps/okta/okta_3_new-web-app-int.png rename to content/chainguard/administration/custom-idps/okta/okta-3.png diff --git a/content/chainguard/administration/custom-idps/okta/okta_6_open_id_connect-2.png b/content/chainguard/administration/custom-idps/okta/okta-6.png similarity index 100% rename from content/chainguard/administration/custom-idps/okta/okta_6_open_id_connect-2.png rename to content/chainguard/administration/custom-idps/okta/okta-6.png diff --git a/content/chainguard/administration/custom-idps/ping-id/index.md b/content/chainguard/administration/custom-idps/ping-id/index.md index 08b8d56ed2..3b8d04b357 100644 --- a/content/chainguard/administration/custom-idps/ping-id/index.md +++ b/content/chainguard/administration/custom-idps/ping-id/index.md @@ -5,7 +5,7 @@ lead: "" description: "Procedural tutorial on how to create a Ping Identity Application" type: "article" date: 2023-04-17T08:48:45+00:00 -lastmod: 2024-09-25T15:22:20+01:00 +lastmod: 2024-10-28T15:22:20+01:00 draft: false tags: ["Chainguard Images", "Procedural"] images: [] @@ -29,7 +29,8 @@ To complete this guide, you will need the following. To integrate the Ping identity provider with the Chainguard platform, [sign on to Ping Identity](https://www.pingidentity.com/en.html) and navigate to the Dashboard. Click on the **Applications** tab in the left-hand sidebar menu, and then click on **Applications** in the resulting dropdown menu. From the Applications landing page, click the plus sign (**➕**) to set up a new application. -![Screenshot of the Ping Identity Dashboard, showing the applications landing page. The Applications tab in the left hand sidebar and the "add application" plus sign icon are highlighted in yellow.](ping-1.png) +
Screenshot of the Ping Identity Dashboard, showing the applications landing page. The Applications tab in the left hand sidebar and the 'add application' plus sign icon are highlighted in yellow.
+
Configure the application as follows: @@ -37,17 +38,20 @@ Configure the application as follows: * **Icon**: You can optionally add a Chainguard logo icon here to help your users visually identify this integration. If you'd like, you can use the icon from the [Chainguard Console](https://console.chainguard.dev/logo512.png). * **Application Type**: Select **OIDC Web App**. -![Screenshot showing the Add Application modal window with the following settings in place: Application Name is set to "Chainguard"; Description reads "Safe Source for Open Source, https://console.chainguard.dev"; the example Linky icon has been uploaded to the Icon field; and the Application Type is set to "OIDC Web App."](ping-2.png) +
Screenshot showing the Add Application modal window with the following settings in place: Application Name is set to 'Chainguard'; Description reads 'Safe Source for Open Source, https://console.chainguard.dev'; the example Linky icon has been uploaded to the Icon field; and the Application Type is set to 'OIDC Web App'.
+
After setting these details, click the **Save** button. Next, configure scopes for the application. In the **Overview** tab, click the **Resource Access** scope button. -![Screenshot of the Overview tab, with the Resource Access scope button highlighted in a yellow box.](ping-3.png) +
Screenshot of the Overview tab, with the Resource Access scope button highlighted in a yellow box.
+
Add **email** and **profile** scopes, then save. -![Screenshot of the Edit Resources modal window, showing the email and profile scopes selected.](ping-4.png) +
Screenshot of the Edit Resources modal window, showing the email and profile scopes selected.
+
Next, configure the OIDC application. Navigate to the **Configuration** tab and click the pencil-shaped "edit" icon. @@ -60,13 +64,15 @@ To configure the application, add the following settings. * **Redirect URIs**: Set the Redirect URI to [`https://issuer.enforce.dev/oauth/callback`](https://issuer.enforce.dev/oauth/callback). -![Screenshot of the Edit Configuration modal window with the following settings: Resource type is set to "Code"; Grant type is set to "Authorization Code" (with PKCE enforcement set to "Optional"); Redirect URIs has one option set (https://issuer.enforce.dev/oauth/callback).](ping-5.png) +
Screenshot of the Edit Configuration modal window with the following settings: Resource type is set to 'Code'; Grant type is set to 'Authorization Code' (with PKCE enforcement set to 'Optional'); Redirect URIs has one option set (https://issuer.enforce.dev/oauth/callback).
+
Click the **Save** button to save your configuration. Finally, enable the Chainguard application by toggling the button in the top right corner. -![Screenshot of the Overview tab, with the toggle button turned on. The toggle button is highlighted with a yellow box.](ping-6.png) +
Screenshot of the Overview tab, with the toggle button turned on. The toggle button is highlighted with a yellow box.
+
This completes configuration of the Ping application. You're now ready to configure the Chainguard platform to use it. @@ -128,3 +134,13 @@ chainctl iam identity-provider create \ Note the `--default-role` option. This defines the default role granted to users registering with this identity provider. This example specifies the `viewer` role, but depending on your needs you might choose `editor` or `owner`. If you don't include this option, you'll be prompted to specify the role interactively. For more information, refer to the [IAM and Security section](/chainguard/administration/custom-idps/custom-idps/#iam-and-security) of our Introduction to Custom Identity Providers in Chainguard tutorial. You can refer to our [Generic Integration Guide](/chainguard/administration/custom-idps/custom-idps/#generic-integration-guide) in our Introduction to Custom Identity Providers guide for more information about the `chainctl iam identity-provider create` command and its required options. + +To log in to the Chainguard Console with the new identity provider you just created, navigate to [console.chainguard.dev](https://console.chainguard.dev) and click **Use Your Identity Provider**. Next, click **Use Your Organization Name** and enter the name of the organization associated with the new identity provider. Finally, click the **Login with Provider** button. This will open up a new window with the Ping Identity login flow, allowing you to complete the login process through there. + +You can also use the custom identity provider to log in through `chainctl`. To do this, run the `chainctl auth login` command and add the `--identity-provider` option followed by the identity provider's ID value: + +```sh +chainctl auth login --identity-provider +``` + +The ID value appears in the `ID` column of the table returned by the `chainctl iam identity-provider create` command you ran previously. You can also retrieve this table at any time by running `chainctl iam identity-provider ls -o table` when logged in.