Checklist in SSO configuration documentation

docusaurus/docs/cms/configurations/guides/configure-sso.md

@@ -71,6 +71,17 @@ export default ({ env }) => ({
 
 ## Setting up provider configuration
 
+Parts of the documentation below assume that some steps have been done previously both in Strapi and in your identity provider. If these steps are skipped, the login button might appear on the Strapi login page but the flow will fail with a redirect or "invalid client" error. Make sure to follow all the steps of the checklist before moving onto the rest of the documentation.
+
+<Checklist title="SSO setup checklist">
+  <ChecklistItem>[Enable SSO in Strapi](/cms/features/sso#admin-panel-settings) <br/> Go to <em>Global settings > Single Sign-On</em> in the admin panel and set up the feature (e.g. toggle auto-registration and choose the default role).</ChecklistItem>
+  <ChecklistItem>Register Strapi in your identity provider <br/> In the provider's dashboard (e.g. Azure AD, Okta, Google, GitHub), create a new OAuth/OIDC application for Strapi. Copy the client ID and client secret generated by the provider.</ChecklistItem>
+  <ChecklistItem>[Add the Strapi callback URL to the provider](#the-createstrategy-factory) <br/> Set the redirect/callback URL in the provider configuration to the value generated by <code>{"strapi.admin.services.passport.getStrategyCallbackURL('<provider_uid>')"}</code> (e.g. <code>/admin/connect/google</code> if the UID is <code>google</code>). The provider must accept this URL or the login will be blocked.</ChecklistItem>
+  <ChecklistItem>[Provide credentials to Strapi](#configuring-the-provider) <br/> Add the client ID and client secret as environment variables (e.g. <code>GOOGLE_CLIENT_ID</code>/<code>GOOGLE_CLIENT_SECRET</code>) so they can be read in <code>{"/config/admin.js|ts"}</code>.</ChecklistItem>
+  <ChecklistItem>[Configure the provider in code](#configuring-the-provider) <br/> Import the provider's Passport strategy and add it to <code>auth.providers</code>.</ChecklistItem>
+  <ChecklistItem>Rebuild and restart Strapi <br/> Run <code>yarn build && yarn develop</code> or <code>npm run build && npm run develop</code> so the new provider appears on the login page. If the admin panel is hosted separately, also ensure the <code>url</code> setting matches the deployed admin URL (see [Host, port and path](/cms/admin-panel-customization/host-port-path).</ChecklistItem>
+</Checklist>
+
 A provider's configuration is a JavaScript object built with the following properties:
 
 | Name             | Required | Type     | Description                                                                                                            |

docusaurus/src/components/Checklist/Checklist.jsx

@@ -0,0 +1,39 @@
+import React, { useState, useId } from 'react';
+import clsx from 'clsx';
+
+export function ChecklistItem({ children }) {
+  const id = useId();
+  const [checked, setChecked] = useState(false);
+
+  return (
+    <li className="checklist__item">
+      <label className="checklist__label" htmlFor={id}>
+        <input
+          type="checkbox"
+          id={id}
+          className="checklist__input"
+          checked={checked}
+          onChange={() => setChecked(!checked)}
+        />
+        <span className="checklist__checkbox" aria-hidden="true" />
+        <span className="checklist__text">{children}</span>
+      </label>
+    </li>
+  );
+}
+
+export default function Checklist({
+  title = 'Checklist',
+  children,
+  className,
+  ...rest
+}) {
+  return (
+    <div className={clsx('checklist', className)} {...rest}>
+      <div className="checklist__header">{title}</div>
+      <ul className="checklist__list" role="list">
+        {children}
+      </ul>
+    </div>
+  );
+}

docusaurus/src/components/Checklist/index.js

@@ -0,0 +1,4 @@
+import Checklist, { ChecklistItem } from './Checklist';
+
+export { ChecklistItem };
+export default Checklist;

docusaurus/src/scss/__index.scss

@@ -23,6 +23,7 @@
 @use 'breadcrumbs.scss';
 @use 'breaking-change-id-card.scss';
 @use 'card.scss';
+@use 'checklist.scss';
 @use 'code.scss';
 @use 'code-block.scss';
 @use 'columns.scss';

docusaurus/src/scss/checklist.scss

@@ -0,0 +1,184 @@
+/** Component: Checklist */
+@use 'mixins' as *;
+
+.checklist {
+  --checklist-header-font-size: 11px;
+  --checklist-header-line-height: 16px;
+  --checklist-header-font-weight: 600;
+  --checklist-content-font-size: 14px;
+  --checklist-content-line-height: 20px;
+
+  border: 1px solid var(--strapi-neutral-150);
+  border-radius: 4px;
+  background-color: var(--strapi-neutral-0);
+  overflow: hidden;
+  margin-bottom: 40px;
+
+  &__header {
+    background-color: var(--strapi-neutral-100);
+    color: var(--strapi-neutral-600);
+    text-transform: uppercase;
+    font-size: var(--checklist-header-font-size) !important;
+    line-height: var(--checklist-header-line-height);
+    font-weight: var(--checklist-header-font-weight);
+    padding: 8px 16px 6px;
+    letter-spacing: 0.4px;
+    border-bottom: 1px solid var(--strapi-neutral-150);
+  }
+
+  &__list {
+    list-style: none;
+    margin: 0;
+    padding: 12px 0;
+  }
+
+  &__item {
+    padding: 0;
+
+    &::before {
+      display: none;
+    }
+  }
+
+  &__label {
+    display: flex;
+    align-items: flex-start;
+    padding: 8px 16px;
+    cursor: pointer;
+    gap: 12px;
+  }
+
+  &__input {
+    position: absolute;
+    opacity: 0;
+    width: 0;
+    height: 0;
+    pointer-events: none;
+  }
+
+  &__checkbox {
+    flex-shrink: 0;
+    width: 16px;
+    height: 16px;
+    border: 1.5px solid var(--strapi-neutral-300);
+    border-radius: 50%;
+    background-color: transparent;
+    position: relative;
+    top: 3px;
+    transition: all 0.2s ease;
+
+    &::before {
+      content: '';
+      position: absolute;
+      inset: -1.5px;
+      background-color: var(--strapi-primary-600);
+      transform: scale(0);
+      transition: transform 0.15s ease;
+      border-radius: 50%;
+      z-index: 1;
+    }
+
+    &::after {
+      content: '';
+      position: absolute;
+      left: 4px;
+      top: 2px;
+      width: 3px;
+      height: 6px;
+      border: solid white;
+      border-width: 0 2px 2px 0;
+      transform: rotate(45deg);
+      opacity: 0;
+      transition: opacity 0.1s ease 0.05s;
+      z-index: 2;
+    }
+  }
+
+  &__input:checked + &__checkbox {
+    border-color: transparent;
+
+    &::before {
+      transform: scale(1);
+    }
+
+    &::after {
+      opacity: 1;
+    }
+  }
+
+  &__input:focus-visible + &__checkbox {
+    outline: 2px solid var(--strapi-primary-500);
+    outline-offset: 2px;
+  }
+
+  &__text {
+    flex: 1;
+    color: var(--strapi-neutral-800);
+    font-size: var(--checklist-content-font-size);
+    line-height: var(--checklist-content-line-height);
+    word-break: break-word;
+
+    code {
+      background-color: var(--strapi-neutral-100);
+      color: var(--strapi-neutral-700);
+      border: 1px solid var(--strapi-neutral-200);
+      border-radius: 3px;
+      padding: 1px 4px;
+      font-size: 13px;
+      word-break: break-all;
+    }
+
+    a {
+      color: var(--strapi-primary-600);
+      text-decoration: none;
+
+      &:hover {
+        text-decoration: underline;
+      }
+    }
+  }
+}
+
+@include dark {
+  .checklist {
+    background-color: #212134;
+    border-color: #4a4a6a;
+
+    &__header {
+      background-color: var(--strapi-neutral-150);
+      color: var(--strapi-neutral-400);
+      border-color: #4a4a6a;
+    }
+
+    &__checkbox {
+      background-color: transparent;
+      border-color: #6a6a8a;
+
+      &::before {
+        background-color: var(--strapi-primary-500);
+      }
+    }
+
+    &__label:hover .checklist__checkbox {
+      border-color: var(--strapi-primary-400);
+    }
+
+    &__input:checked + .checklist__checkbox {
+      border-color: var(--strapi-primary-500);
+    }
+
+    &__text {
+      color: #DCDCE4;
+
+      code {
+        background-color: var(--strapi-neutral-150);
+        color: #DCDCE4;
+        border-color: #4a4a6a;
+      }
+
+      a {
+        color: var(--strapi-primary-500);
+      }
+    }
+  }
+}

docusaurus/src/theme/MDXComponents.js

@@ -38,6 +38,7 @@ import { ExternalLink } from '../components/ExternalLink';
 import BreakingChangeIdCard from '../components/BreakingChangeIdCard';
 import MermaidWithFallback from '../components/MermaidWithFallback.js';
 import IdentityCard, { IdentityCardItem } from '../components/IdentityCard';
+import Checklist, { ChecklistItem } from '../components/Checklist';
 // Debug component for testing, for instance the AIToolbar configuration
 import DebugComponent from '../components/DebugComponent';
 
@@ -91,6 +92,8 @@ export default {
   Icon,
   ExternalLink,
   BreakingChangeIdCard,
+  Checklist,
+  ChecklistItem,
   IdentityCard,
   IdentityCardItem,
   Tldr,