feat: organization logo

.changeset/dull-goats-help.md

@@ -0,0 +1,33 @@
+---
+"@logto/experience": minor
+"@logto/console": minor
+"@logto/core": minor
+"@logto/integration-tests": patch
+"@logto/phrases": patch
+"@logto/schemas": patch
+---
+
+support organization logo and sign-in experience override
+
+Now it's able to set light and dark logos for organizations. You can upload the logos in the organization settings page.
+
+Also, it's possible to override the sign-in experience logo from an organization. Simply add the `organization_id` parameter to the authentication request. In most Logto SDKs, it can be done by using the `extraParams` field in the `signIn` method.
+
+For example, in the JavaScript SDK:
+
+```ts
+import LogtoClient from '@logto/client';
+
+const logtoClient = new LogtoClient(/* your configuration */);
+
+logtoClient.signIn({
+  redirectUri: 'https://your-app.com/callback',
+  extraParams: {
+    organization_id: '<organization-id>'
+  },
+});
+```
+
+The value `<organization-id>` can be found in the organization settings page.
+
+If you could not find the `extraParams` field in the SDK you are using, please let us know.

.changeset/lazy-geese-bow.md

@@ -0,0 +1,5 @@
+---
+"@logto/demo-app": minor
+---
+
+support extra token params in dev panel

packages/connectors/connector-mock-social/src/index.ts

@@ -30,7 +30,7 @@ const getAuthorizationUri: GetAuthorizationUri = async (
     }
   }
 
-  return `http://mock.social.com/?state=${state}&redirect_uri=${redirectUri}`;
+  return `http://mock-social/?state=${state}&redirect_uri=${redirectUri}`;
 };
 
 const getUserInfo: GetUserInfo = async (data, getSession) => {

packages/console/src/hooks/use-user-assets-service.ts

@@ -9,6 +9,15 @@ import { GlobalRoute } from '@/contexts/TenantsProvider';
 import useApi, { useStaticApi, type RequestError } from './use-api';
 import useSwrFetcher from './use-swr-fetcher';
 
+/**
+ * Hook to check if the user assets service (file uploading) is ready.
+ *
+ * Caveats: When using it in a form, remember to check `isLoading` first and don't render the form
+ * until it's settled. Otherwise, the form may be rendered with unexpected behavior, such as
+ * registering a unexpected validate function. If you really need to render the form while loading,
+ * you can use the `shouldUnregister` option from `react-hook-form` to unregister the field when
+ * the component is unmounted.
+ */
 const useUserAssetsService = () => {
   const adminApi = useStaticApi({
     prefixUrl: adminTenantEndpoint,
@@ -27,6 +36,10 @@ const useUserAssetsService = () => {
   );
 
   return {
+    /**
+     * Whether the user assets service (file uploading) is ready.
+     * @see {@link useUserAssetsService} for caveats.
+     */
     isReady: data?.status === 'ready',
     isLoading: !error && !data,
   };

packages/console/src/pages/OrganizationDetails/Settings/Branding.tsx

@@ -0,0 +1,72 @@
+import { Theme, themeToLogoKey } from '@logto/schemas';
+import { Controller, type UseFormReturn } from 'react-hook-form';
+import { useTranslation } from 'react-i18next';
+
+import FormCard, { FormCardSkeleton } from '@/components/FormCard';
+import FormField from '@/ds-components/FormField';
+import TextInput from '@/ds-components/TextInput';
+import ImageUploaderField from '@/ds-components/Uploader/ImageUploaderField';
+import useUserAssetsService from '@/hooks/use-user-assets-service';
+import { uriValidator } from '@/utils/validator';
+
+import * as styles from './index.module.scss';
+import { type FormData } from './utils';
+
+type Props = {
+  readonly form: UseFormReturn<FormData>;
+};
+
+function Branding({ form }: Props) {
+  const { isReady: isUserAssetsServiceReady, isLoading } = useUserAssetsService();
+  const {
+    control,
+    formState: { errors },
+    register,
+  } = form;
+  const { t } = useTranslation(undefined, { keyPrefix: 'admin_console' });
+
+  if (isLoading) {
+    return <FormCardSkeleton />;
+  }
+
+  return (
+    <FormCard
+      title="organization_details.branding.title"
+      description="organization_details.branding.description"
+    >
+      <div className={styles.branding}>
+        {Object.values(Theme).map((theme) => (
+          <section key={theme}>
+            <FormField title={`organization_details.branding.${theme}_logo`}>
+              {isUserAssetsServiceReady ? (
+                <Controller
+                  control={control}
+                  name={`branding.${themeToLogoKey[theme]}`}
+                  render={({ field: { onChange, value, name } }) => (
+                    <ImageUploaderField
+                      name={name}
+                      value={value ?? ''}
+                      actionDescription={t('organization_details.branding.logo_upload_description')}
+                      onChange={onChange}
+                    />
+                  )}
+                />
+              ) : (
+                <TextInput
+                  {...register(`branding.${themeToLogoKey[theme]}`, {
+                    validate: (value?: string) =>
+                      !value || uriValidator(value) || t('errors.invalid_uri_format'),
+                  })}
+                  error={errors.branding?.[themeToLogoKey[theme]]?.message}
+                  placeholder={t('sign_in_exp.branding.logo_image_url_placeholder')}
+                />
+              )}
+            </FormField>
+          </section>
+        ))}
+      </div>
+    </FormCard>
+  );
+}
+
+export default Branding;

packages/console/src/pages/OrganizationDetails/Settings/index.module.scss

@@ -22,6 +22,12 @@
   gap: _.unit(3);
 }
 
+.branding {
+  section + section {
+    margin-top: _.unit(6);
+  }
+}
+
 .mfaWarning {
   margin-top: _.unit(3);
 }

packages/console/src/pages/OrganizationDetails/Settings/index.tsx

@@ -20,6 +20,7 @@ import { trySubmitSafe } from '@/utils/form';
 
 import { type OrganizationDetailsOutletContext } from '../types';
 
+import Branding from './Branding';
 import JitSettings from './JitSettings';
 import * as styles from './index.module.scss';
 import { assembleData, isJsonObject, normalizeData, type FormData } from './utils';
@@ -136,6 +137,7 @@ function Settings() {
           )}
         </FormField>
       </FormCard>
+      <Branding form={form} />
       <JitSettings form={form} />
       <UnsavedChangesAlertModal hasUnsavedChanges={!isDeleting && isDirty} />
     </DetailsForm>

packages/console/src/pages/OrganizationDetails/Settings/utils.ts

@@ -25,14 +25,24 @@ export const normalizeData = (
   customData: JSON.stringify(data.customData, undefined, 2),
 });
 
+const assembleBranding = (branding?: Organization['branding']) => {
+  if (!branding) {
+    return {};
+  }
+
+  return Object.fromEntries(Object.entries(branding).filter(([, value]) => Boolean(value)));
+};
+
 export const assembleData = ({
   jitEmailDomains,
   jitRoles,
   jitSsoConnectorIds,
   customData,
+  branding,
   ...data
 }: FormData): Partial<Organization> => ({
   ...data,
+  branding: assembleBranding(branding),
   // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
   customData: JSON.parse(customData ?? '{}'),
 });

packages/core/src/libraries/sign-in-experience/index.test.ts

@@ -149,7 +149,7 @@ describe('getFullSignInExperience()', () => {
       wellConfiguredSsoConnector,
     ]);
 
-    const fullSignInExperience = await getFullSignInExperience('en');
+    const fullSignInExperience = await getFullSignInExperience({ locale: 'en' });
     const connectorFactory = ssoConnectorFactories[wellConfiguredSsoConnector.providerName];
 
     expect(fullSignInExperience).toStrictEqual({
@@ -183,7 +183,7 @@ describe('getFullSignInExperience()', () => {
       wellConfiguredSsoConnector,
     ]);
 
-    const fullSignInExperience = await getFullSignInExperience('en');
+    const fullSignInExperience = await getFullSignInExperience({ locale: 'en' });
     const connectorFactory = ssoConnectorFactories[wellConfiguredSsoConnector.providerName];
 
     expect(fullSignInExperience).toStrictEqual({
@@ -224,7 +224,7 @@ describe('get sso connectors', () => {
       singleSignOnEnabled: false,
     });
 
-    const { ssoConnectors } = await getFullSignInExperience('en');
+    const { ssoConnectors } = await getFullSignInExperience({ locale: 'en' });
 
     expect(ssoConnectorLibrary.getAvailableSsoConnectors).not.toBeCalled();
 
@@ -239,7 +239,7 @@ describe('get sso connectors', () => {
       wellConfiguredSsoConnector,
     ]);
 
-    const { ssoConnectors } = await getFullSignInExperience('jp');
+    const { ssoConnectors } = await getFullSignInExperience({ locale: 'jp' });
 
     const connectorFactory = ssoConnectorFactories[wellConfiguredSsoConnector.providerName];
 
@@ -270,7 +270,7 @@ describe('get sso connectors', () => {
 
     const connectorFactory = ssoConnectorFactories[wellConfiguredSsoConnector.providerName];
 
-    const { ssoConnectors } = await getFullSignInExperience('en');
+    const { ssoConnectors } = await getFullSignInExperience({ locale: 'en' });
 
     expect(ssoConnectors).toEqual([
       {

packages/core/src/libraries/sign-in-experience/index.ts

@@ -4,10 +4,12 @@ import type {
   ConnectorMetadata,
   FullSignInExperience,
   LanguageInfo,
+  SignInExperience,
   SsoConnectorMetadata,
 } from '@logto/schemas';
 import { ConnectorType } from '@logto/schemas';
-import { deduplicate } from '@silverhand/essentials';
+import { deduplicate, trySafe } from '@silverhand/essentials';
+import deepmerge from 'deepmerge';
 
 import { EnvSet } from '#src/env-set/index.js';
 import RequestError from '#src/errors/RequestError/index.js';
@@ -37,6 +39,7 @@ export const createSignInExperienceLibrary = (
   const {
     customPhrases: { findAllCustomLanguageTags },
     signInExperiences: { findDefaultSignInExperience, updateDefaultSignInExperience },
+    organizations,
   } = queries;
 
   const validateLanguageInfo = async (languageInfo: LanguageInfo) => {
@@ -109,12 +112,38 @@ export const createSignInExperienceLibrary = (
     return plan.id === developmentTenantPlanId;
   };
 
-  const getFullSignInExperience = async (locale: string): Promise<FullSignInExperience> => {
-    const [signInExperience, logtoConnectors, isDevelopmentTenant] = await Promise.all([
-      findDefaultSignInExperience(),
-      getLogtoConnectors(),
-      getIsDevelopmentTenant(),
-    ]);
+  /**
+   * Get the override data for the sign-in experience by reading from organization data. If the
+   * entity is not found, return `undefined`.
+   */
+  const getOrganizationOverride = async (
+    organizationId?: string
+  ): Promise<Partial<SignInExperience> | undefined> => {
+    if (!organizationId) {
+      return;
+    }
+    const organization = await trySafe(organizations.findById(organizationId));
+    if (!organization?.branding) {
+      return;
+    }
+
+    return { branding: organization.branding };
+  };
+
+  const getFullSignInExperience = async ({
+    locale,
+    organizationId,
+  }: {
+    locale: string;
+    organizationId?: string;
+  }): Promise<FullSignInExperience> => {
+    const [signInExperience, logtoConnectors, isDevelopmentTenant, organizationOverride] =
+      await Promise.all([
+        findDefaultSignInExperience(),
+        getLogtoConnectors(),
+        getIsDevelopmentTenant(),
+        getOrganizationOverride(organizationId),
+      ]);
 
     // Always return empty array if single-sign-on is disabled
     const ssoConnectors = signInExperience.singleSignOnEnabled
@@ -167,7 +196,7 @@ export const createSignInExperienceLibrary = (
     };
 
     return {
-      ...signInExperience,
+      ...deepmerge(signInExperience, organizationOverride ?? {}),
       socialConnectors,
       ssoConnectors,
       forgotPassword,

packages/core/src/oidc/utils.ts

@@ -101,5 +101,11 @@ export const buildLoginPromptUrl = (params: ExtraParamsObject, appId?: unknown):
     return path.join('direct', method ?? '', target ?? '') + getSearchParamString();
   }
 
+  // Append other valid params as-is
+  const { first_screen: _, interaction_mode: __, direct_sign_in: ___, ...rest } = params;
+  for (const [key, value] of Object.entries(rest)) {
+    searchParams.append(key, value);
+  }
+
   return firstScreen + getSearchParamString();
 };

packages/core/src/routes/well-known.ts

@@ -1,5 +1,5 @@
 import { isBuiltInLanguageTag } from '@logto/phrases-experience';
-import { adminTenantId, guardFullSignInExperience } from '@logto/schemas';
+import { ExtraParamsKey, adminTenantId, guardFullSignInExperience } from '@logto/schemas';
 import { conditionalArray } from '@silverhand/essentials';
 import { z } from 'zod';
 
@@ -41,9 +41,14 @@ export default function wellKnownRoutes<T extends AnonymousRouter>(
 
   router.get(
     '/.well-known/sign-in-exp',
-    koaGuard({ response: guardFullSignInExperience, status: 200 }),
+    koaGuard({
+      query: z.object({ [ExtraParamsKey.OrganizationId]: z.string().optional() }),
+      response: guardFullSignInExperience,
+      status: 200,
+    }),
     async (ctx, next) => {
-      ctx.body = await getFullSignInExperience(ctx.locale);
+      const { [ExtraParamsKey.OrganizationId]: organizationId } = ctx.guard.query;
+      ctx.body = await getFullSignInExperience({ locale: ctx.locale, organizationId });
 
       return next();
     }

packages/demo-app/src/App.tsx

@@ -16,6 +16,7 @@ import { getLocalData, setLocalData } from './utils';
 void initI18n();
 
 const Main = () => {
+  const config = getLocalData('config');
   const params = new URL(window.location.href).searchParams;
   const { isAuthenticated, isLoading, getIdTokenClaims, signIn, signOut } = useLogto();
   const [user, setUser] = useState<Pick<IdTokenClaims, 'sub' | 'username'>>();
@@ -53,10 +54,24 @@ const Main = () => {
     if (!isAuthenticated) {
       void signIn({
         redirectUri: window.location.origin + window.location.pathname,
-        extraParams: Object.fromEntries(new URLSearchParams(window.location.search).entries()),
+        extraParams: Object.fromEntries(
+          new URLSearchParams([
+            ...new URLSearchParams(config.signInExtraParams).entries(),
+            ...new URLSearchParams(window.location.search).entries(),
+          ]).entries()
+        ),
       });
     }
-  }, [error, getIdTokenClaims, isAuthenticated, isInCallback, isLoading, signIn, user]);
+  }, [
+    config.signInExtraParams,
+    error,
+    getIdTokenClaims,
+    isAuthenticated,
+    isInCallback,
+    isLoading,
+    signIn,
+    user,
+  ]);
 
   useEffect(() => {
     const onThemeChange = (event: MediaQueryListEvent) => {