feat(console): add google workspace integration guide (#4997)

* feat(console): add google workspace integration guide

add google workspace integration guide

* fix(console): fix lint error

fix lint error

packages/console/src/assets/docs/single-sign-on/AzureAD/README.mdx

@@ -1,37 +1,40 @@
 import SsoSamlSpMetadata from '@/mdx-components/SsoSamlSpMetadata';
-import createApplication from './create_application.webp';
-import setupSso from './set_up_single_sign_on.webp';
-import spConfig from './sp_config.webp';
-import metadataUrl from './metadata_url.webp';
-import defaultAttributesMapping from './default_attribute_mapping.webp';
-import logtoAttributes from './logto_attribute_mapping.webp';
-import assignUsers from './assign_users.webp';
+import Step from '@/mdx-components/Step';
 
-# Azure AD single sign-on integration guide
-
-This guide will help you to integration Azure AD single sign-on (SSO) to your application using Logto.
-
-## Step 1: Create an Azure AD SSO application
+import createApplication from './assets/create_application.webp';
+import setupSso from './assets/set_up_single_sign_on.webp';
+import spConfig from './assets/sp_config.webp';
+import metadataUrl from './assets/metadata_url.webp';
+import defaultAttributesMapping from './assets/default_attribute_mapping.webp';
+import logtoAttributes from './assets/logto_attribute_mapping.webp';
+import assignUsers from './assets/assign_users.webp';
 
+<Step index={0} title="Create an Azure AD SSO application">
 Initiate the Azure AD SSO integration by creating an SSO application on the Azure AD side.
 
 1. Go to the [Azure portal](https://portal.azure.com/) and sign in as an administrator.
 
 2. Navigate to `Microsoft Entra ID` > `Enterprise applications` > `New application`, and select `Create your own application`.
 
-   <img src={createApplication} alt="Create Application" width="100%" />
+<center>
+  <img src={createApplication} alt="Create Application" />
+</center>
 
 3. Enter the application name and select `Integrate any other application you don't find in the gallery (Non-gallery)`.
 
 4. Select `Setup single sign-on` > `SAML`.
 
-   <img src={setupSso} alt="Setup single sign on" width="100%" />
+<center>
+  <img src={setupSso} alt="Setup single sign on" />
+</center>
 
 5. Follow the instructions, as the first step, you will need to fill in the basic SAML configuration using the following information provided by Logto.
 
-   <SsoSamlSpMetadata />
+<center>
+  <img src={spConfig} alt="SP Configuration" />
+</center>
 
-   <img src={spConfig} alt="SP Configuration" width="100%" />
+<SsoSamlSpMetadata />
 
 - **Audience URI(SP Entity ID)**: It represents as a globally unique identifier for your Logto service, functioning as the EntityId for SP during authentication requests to the IdP. This identifier is pivotal for the secure exchange of SAML assertions and other authentication-related data between the IdP and Logto.
 
@@ -39,23 +42,24 @@ Initiate the Azure AD SSO integration by creating an SSO application on the Azur
 
 Click `Save` to continue.
 
-<br />
-
-## Step 2: Configure SAML SSO at Logto
+</Step>
 
+<Step index={1} title="Configure SAML SSO at Logto">
 To make the SAML SSO integration work, you will need to provide the IdP metadata back to Logto. Let's switch back to the Logto side, navigate to the `Connection` tab of your Azure AD SSO connector.
 
 Logto provides three different ways to configure the IdP metadata. The easiest way is to provide the `metadata URL` of the Azure AD SSO application.
 
 - Copy the `App Federation Metadata Url` from your Azure AD SSO application and paste it into the `Metadata URL` field in Logto.
 
-  <img src={metadataUrl} alt="Metadata URL" width="100%" />
+<center>
+  <img src={metadataUrl} alt="Metadata URL" />
+</center>
 
 - Logto will fetch the metadata from the URL and configure the SAML SSO integration automatically.
 
-<br />
+</Step>
 
-## Step 3: Configure user attributes mapping
+<Step index={2} title="Configure user attributes mapping">
 
 Logto provides a flexible way to map the user attributes returned from IdP to the user attributes in Logto. Logto will sync the following user attributes from IdP by default:
 
@@ -67,41 +71,50 @@ You may manage the user attributes mapping logic either on the Azure AD side or
 
 1. Map the AzureAD user attributes to Logto user attributes at Logto side.
 
-   Visit the `Attributes & Claims` tab of your Azure AD SSO application.
+<center>
+  <img src={defaultAttributesMapping} alt="Default Attributes Mapping" />
+</center>
 
-   <img src={defaultAttributesMapping} alt="Default Attributes Mapping" width="100%" />
+Visit the `Attributes & Claims` tab of your Azure AD SSO application.
 
-   Copy the following attribute names (with namespace prefix) from the `Attributes & Claims` section of your Azure AD SSO application and paste them into the corresponding fields in Logto.
+Copy the following attribute names (with namespace prefix) from the `Attributes & Claims` section of your Azure AD SSO application and paste them into the corresponding fields in Logto.
 
-   - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email`
-   - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` (Recommend: update the attribute value map to `user.displayname` for better user experience)
+- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email`
+
+- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` (Recommend: update the attribute value map to `user.displayname` for better user experience)
 
 2. Map the AzureAD user attributes to Logto user attributes at AzureAD side.
 
-   Visit the `Attributes & Claims` section of your Azure AD SSO application. Click on `Edit`. Update the `Additional claims` fields based on the Logto user attributes settings:
+Visit the `Attributes & Claims` section of your Azure AD SSO application. Click on `Edit`. Update the `Additional claims` fields based on the Logto user attributes settings:
 
-   - update the claim name value based on the Logto user attributes settings.
-   - remove the namespace prefix.
-   - click `Save` to continue.
+- update the claim name value based on the Logto user attributes settings.
+- remove the namespace prefix.
+- click `Save` to continue.
 
-   You should end up with the following settings:
+Should end up with the following settings:
 
-   <img src={logtoAttributes} alt="Logto Attributes" width="100%" />
+<center>
+  <img src={logtoAttributes} alt="Logto Attributes" />
+</center>
 
-> You may also specify additional user attributes on the Azure AD side. Logto will keep a record of the original user attributes returned from IdP under the user's `sso_identity` field.
+You may also specify additional user attributes on the Azure AD side. Logto will keep a record of the original user attributes returned from IdP under the user's `sso_identity` field.
 
-<br />
+</Step>
 
-## Step 4: Assign users to the Azure AD SSO application
+<Step index={3} title="Assign users to the Azure AD SSO application">
 
 Visit the `Users and groups` section of your Azure AD SSO application. Click on `Add user/group` to assign users to the Azure AD SSO application. Only users assigned to your Azure AD SSO application will be able to authenticate through the Azure AD SSO connector.
 
-<img src={assignUsers} alt="Assign Users" width="100%" />
+<center>
+  <img src={assignUsers} alt="Assign Users" />
+</center>
 
-<br />
+</Step>
 
-## Step 5: Set email domains and enable the SSO connector
+<Step index={4} title="Set email domains and enable the SSO connector">
 
 Provide the email domains of your organization at the Logto's SAML SSO connector experience tab. This will enable the SSO connector as an authentication method for those users.
 
 Users with email addresses in the specified domains will be restricted to use SAML SSO connector as their only authentication method.
+
+</Step>

packages/console/src/assets/docs/single-sign-on/GoogleWorkspace/README.mdx

@@ -0,0 +1,103 @@
+import OidcCallbackUri from '@/mdx-components/OidcCallbackUri';
+import Step from '@/mdx-components/Step';
+
+import clientCredentials from './assets/client_credentials.webp';
+import consentScreenScopes from './assets/consent_screen_scopes.webp';
+import consentScreenSettings from './assets/consent_screen_settings.webp';
+import consentScreenUserType from './assets/consent_screen_user_type.webp';
+import createCredentials from './assets/create_credentials.webp';
+import credentialsConfig from './assets/credentials_config.webp';
+import credentials from './assets/credentials.webp';
+
+<Step index={0} title="Create an new project on Google Cloud Platform" >
+
+Before you can use Google Workspace as an authentication provider, you must set up a project in the [Google API Console](https://console.developers.google.com/) to obtain OAuth 2.0 credentials, If you already have a project, you can skip this step. Otherwise, create a new project under your Google organization.
+
+</Step>
+
+<Step index={1} title="Config the consent screen for your application" >
+
+In order to create a new OIDC credential, you need to configure the consent screen for your application. Otherwise, you will receive an error prompt when creating the credential like the following:
+
+<center>
+  <img src={credentials} alt="create credentials" />
+</center>
+
+1. Navigate to the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) page and select the `Internal` user type. This will make the OAuth application only available to users within your organization.
+
+<center>
+  <img src={consentScreenUserType} alt="consent screen user type" />
+</center>
+
+2. Fill in the `Consent Screen` settings following the instructions on the page. You need to provide the following minimum information:
+
+- **Application name**: The name of your application. It will be displayed on the consent screen.
+- **Support email**: The support email of your application. It will be displayed on the consent screen.
+
+<center>
+  <img src={consentScreenSettings} alt="consent screen settings" />
+</center>
+
+3. Set the `Scopes` for your application. In order to retrieve the user's identity information and email address properly from the IdP, Logto SSO connector need to grant the following scopes from the IdP:
+
+<center>
+  <img src={consentScreenScopes} alt="consent screen scopes" />
+</center>
+
+- **openid**: This scope is required for OIDC authentication. It is used to retrieve ID token and get access to the userInfo endpoint of the IdP.
+- **profile**: This scope is required for accessing the user's basic profile information.
+- **email**: This scope is required for accessing the user's email address.
+
+Click the `Save` button to save the consent screen settings.
+
+</Step>
+
+<Step index={2} title="Create a new OAuth credential">
+
+Navigate to the [Credentials](https://console.cloud.google.com/apis/credentials) page and click the `Create Credentials` button. Select the `OAuth client ID` option from the dropdown menu to create a new OAuth credential for your application.
+
+<center>
+  <img src={createCredentials} alt="create credentials" />
+</center>
+
+Continue set up the OAuth credential by filling up the following information:
+
+<center>
+  <img src={credentialsConfig} alt="credentials config" />
+</center>
+
+1. Select the `Web application` as the application type.
+
+2. Fill in the `Name` of your client application, `Logto SSO Connector` for example. This will help you to identify the credential in the future.
+
+3. Fill in the `Authorized redirect URIs` with the Logto callback URI. This is the URI that the Google will redirect the user's browser after successful authentication. After a user successfully authenticates with the IdP, the IdP redirects the user's browser back to this designated URI along with an authorization code. Logto will complete the authentication process based on authorization code received from this URI.
+
+<OidcCallbackUri />
+
+4. Fill in the `Authorized JavaScript origins` with the Logto callback URI's origin. This ensures only your Logto application can send requests to the Google OAuth server.
+
+5. Click the `Create` button to create the OAuth credential.
+
+</Step>
+
+<Step index={3} title="Copy the client ID and client secret">
+
+After successfully creating the OAuth credential, you will receive a prompt modal with the client ID and client secret.
+
+<center>
+  <img src={clientCredentials} alt="client credentials" />
+</center>
+
+Copy the client ID and client secret and fill in the corresponding fields on the Logto SSO connector connection page.
+
+Now you have successfully configured a Google Workspace SSO connector on Logto.
+
+</Step>
+
+<Step index={4} title="Set email domains and enable the SSO connector">
+
+Provide the email domains of your organization on the connector experience tab. This will enabled the SSO connector as an authentication method for those users.
+
+Users with email addresses in the specified domains will be restricted to use your SSO connector as their only authentication method.
+
+</Step>

packages/console/src/assets/docs/single-sign-on/OIDC/README.mdx

@@ -1,10 +1,7 @@
 import OidcCallbackUri from '@/mdx-components/OidcCallbackUri';
+import Step from '@/mdx-components/Step';
 
-# OIDC single sign-on integration guide
-
-This standard OIDC Single Sign-On (SSO) connector will help you to enable single sign-on (SSO) in your application using Logto. With minimal configuration efforts, this connector allows integration with OIDC-based Identity Provider (IdP).
-
-## Step 1: Create an OIDC application on your IdP
+<Step index={0} title="Create an OIDC application on your IdP">
 
 Initiate the OIDC SSO integration by creating an application on the IdP side. You will need to provide the following configurations from the Logto server.
 
@@ -12,11 +9,10 @@ Initiate the OIDC SSO integration by creating an application on the IdP side. Yo
 
 <OidcCallbackUri />
 
-Fill in the Logto Callback URI in your IdP OIDC application and continue to create the application.(Most of the OIDC IdPs provides a wide range of application types to choose from. To create a web based SSO connector on Logto, please choose the `Web Application` type.)
+Fill in the Logto Callback URI in your IdP OIDC application settings form and continue to create the application.(Most of the OIDC IdPs provides a wide range of application types to choose from. To create a web based SSO connector on Logto, please choose the `Web Application` type.)
 
-<br />
-
-## Step 2: Configure OIDC SSO on Logto
+</Step>
+<Step index={1} title="Configure OIDC SSO on Logto">
 
 After successfully creating an OIDC application on the IdP side, you will need to provide the IdP configurations back to Logto. Navigate to the `Connection` tab, and fill in the following configurations:
 
@@ -36,10 +32,11 @@ After successfully creating an OIDC application on the IdP side, you will need t
 
   This is to ensure that Logto can retrieve the user's identity information and email address properly from the IdP. You may add additional scopes to the scope parameter to request for more information from the IdP.
 
-<br />
-
-## Step 3: Set email domains and enable the SSO connector
+</Step>
+<Step index={2} title="Set email domains and enable the SSO connector">
 
 Provide the email domains of your organization on the connector experience tab. This will enabled the SSO connector as an authentication method for those users.
 
 Users with email addresses in the specified domains will be restricted to use your SSO connector as their only authentication method.
+
+</Step>

packages/console/src/assets/docs/single-sign-on/SAML/README.mdx

@@ -1,10 +1,7 @@
 import SsoSamlSpMetadata from '@/mdx-components/SsoSamlSpMetadata';
+import Step from '@/mdx-components/Step';
 
-# SAML single sign-on integration guide
-
-This standard SAML Single Sign-On (SSO) connector will help you to enable single sign-on (SSO) in your application using Logto. With minimal configuration efforts, this connector allows integration with any SAML-based Identity Provider (IdP).
-
-## Step 1: Create an SAML SSO application on your IdP
+<Step index={0} title="Create an SAML SSO application on your IdP" >
 
 Initiate the SAML SSO integration by creating an application on the IdP side. Obtain the following configurations from Logto, representing your Service Provider (SP):
 
@@ -16,9 +13,9 @@ Initiate the SAML SSO integration by creating an application on the IdP side. Ob
 
 Fill in the above configurations in your IdP SAML application and continue to retrieve the following configurations from your IdP.
 
-<br />
+</Step>
 
-## Step 2: Configure SAML SSO on Logto
+<Step index={1} Configure SAML SSO on Logto>
 
 To make the SAML SSO integration work, you will need to provide the IdP metadata to Logto. The IdP metadata is an XML document that contains all the information required for Logto to establish the trust with the IdP.
 
@@ -36,9 +33,9 @@ Navigate to the `Connection` tab. Logto provides three different ways to configu
 
 With either of the above configurations, Logto will parse the IdP metadata and configure the SAML SSO integration accordingly.
 
-<br />
+</Step>
 
-## Step 3: Configure user attributes mapping
+<Step index={2} title="Configure user attributes mapping">
 
 The user attributes returned from IdP may vary depending on the IdP configuration. Logto provides a flexible way to map the user attributes returned from IdP to the user attributes in Logto. You can configure the user attributes mapping in the SAML SSO integration experience tab.
 
@@ -48,10 +45,12 @@ For minimum configuration, please make sure the following attributes are well ma
 
 - email: The email address of the user.
 
-<br />
+</Step>
 
-## Step 4: Set email domains and enable the SSO connector
+<Step index={3} title="Set email domains and enable the SSO connector">
 
 Provide the email domains of your organization in the SAML SSO integration experience tab. This will enable the SSO connector as an authentication method for those users.
 
 Users with email addresses in the specified domains will be restricted to use SAML SSO connector as their only authentication method.
+
+</Step>

packages/console/src/assets/docs/single-sign-on/index.ts

@@ -2,12 +2,13 @@ import { SsoProviderName } from '@logto/schemas';
 import { type MDXProps } from 'mdx/types';
 import { lazy, type LazyExoticComponent, type FunctionComponent } from 'react';
 
-export type GuideComponentType = LazyExoticComponent<FunctionComponent<MDXProps>>;
+type GuideComponentType = LazyExoticComponent<FunctionComponent<MDXProps>>;
 
 const ssoConnectorGuides: Readonly<{ [key in SsoProviderName]?: GuideComponentType }> = {
   [SsoProviderName.SAML]: lazy(async () => import('./SAML/README.mdx')),
   [SsoProviderName.OIDC]: lazy(async () => import('./OIDC/README.mdx')),
   [SsoProviderName.AZURE_AD]: lazy(async () => import('./AzureAD/README.mdx')),
+  [SsoProviderName.GOOGLE_WORKSPACE]: lazy(async () => import('./GoogleWorkspace/README.mdx')),
 };
 
 export default ssoConnectorGuides;

packages/console/src/pages/EnterpriseSsoDetails/SsoGuide/index.module.scss

@@ -1,10 +1,23 @@
 @use '@/scss/underscore' as _;
 @use '@/scss/dimensions' as dim;
 
+
 .content {
   flex: 1;
   position: relative;
 
+  section {
+    margin: _.unit(6) 0;
+
+    &:first-child {
+      margin-top: 0;
+    }
+
+    &:last-child {
+      margin-bottom: 0;
+    }
+  }
+
   h3 {
     font: var(--font-title-2);
     color: var(--color-text-secondary);
@@ -16,6 +29,12 @@
     margin: _.unit(4) 0;
   }
 
+  ul,
+  ol {
+    margin-block: _.unit(4);
+    padding-inline-start: _.unit(4);
+  }
+
   ul > li,
   ol > li {
     font: var(--font-body-2);
@@ -52,4 +71,9 @@
     padding: _.unit(1);
     border-radius: 4px;
   }
+
+  img {
+    width: 90%;
+    border-radius: _.unit(2);
+  }
 }

packages/console/src/pages/EnterpriseSsoDetails/index.module.scss

@@ -1,10 +1,7 @@
 @use '@/scss/underscore' as _;
 
 .readme {
-  padding: 0 _.unit(6);
   margin: _.unit(6);
-  background-color: var(--color-layer-1);
-  border-radius: 16px;
 }
 
 .container {

packages/console/src/pages/EnterpriseSsoDetails/index.tsx

@@ -1,13 +1,12 @@
 import { withAppInsights } from '@logto/app-insights/react';
 import { type SsoProviderName } from '@logto/schemas';
 import { pick } from '@silverhand/essentials';
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useState } from 'react';
 import { toast } from 'react-hot-toast';
 import { useTranslation } from 'react-i18next';
 import { useLocation, useParams } from 'react-router-dom';
 import useSWR, { useSWRConfig } from 'swr';
 
-import ssoConnectorGuides, { type GuideComponentType } from '@/assets/docs/single-sign-on';
 import Delete from '@/assets/icons/delete.svg';
 import File from '@/assets/icons/file.svg';
 import DetailsPage from '@/components/DetailsPage';
@@ -90,13 +89,6 @@ function EnterpriseSsoConnectorDetails<T extends SsoProviderName>() {
     }
   };
 
-  const ConnectorGuide = useMemo<GuideComponentType | undefined>(() => {
-    if (!ssoConnector) {
-      return;
-    }
-    return ssoConnectorGuides[ssoConnector.providerName];
-  }, [ssoConnector]);
-
   if (!ssoConnectorId) {
     return null;
   }
@@ -151,7 +143,6 @@ function EnterpriseSsoConnectorDetails<T extends SsoProviderName>() {
               setIsReadmeOpen(false);
             }}
           >
-            {/* TODO: @darcyYe Add SSO connector README. */}
             <SsoGuide ssoConnector={ssoConnector} className={styles.readme} />
           </Drawer>
           <TabNav>