Add help url links (#1747)

* initial work

* add help urls for all main landing pages

src/authentication/AuthenticationSection.tsx

@@ -32,6 +32,7 @@ import { RequiredActions } from "./RequiredActions";
 import { Policies } from "./policies/Policies";
 
 import "./authentication-section.css";
+import helpUrls from "../help-urls";
 
 type UsedBy = "specificClients" | "default" | "specificProviders";
 
@@ -211,7 +212,12 @@ export default function AuthenticationSection() {
           }}
         />
       )}
-      <ViewHeader titleKey="authentication:title" divider={false} />
+      <ViewHeader
+        titleKey="authentication:title"
+        subKey="authentication:authenticationExplain"
+        helpUrl={helpUrls.authenticationUrl}
+        divider={false}
+      />
       <PageSection variant="light" className="pf-u-p-0">
         <KeycloakTabs isBox>
           <Tab

src/authentication/messages.ts

@@ -1,6 +1,7 @@
 export default {
   authentication: {
     title: "Authentication",
+    authenticationExplain: "Placeholder for authentication explanation.",
     flows: "Flows",
     requiredActions: "Required actions",
     policies: "Policies",

src/client-scopes/ClientScopesSection.tsx

@@ -45,6 +45,7 @@ import {
 } from "./details/SearchFilter";
 import type { Row } from "../clients/scopes/ClientScopes";
 import { getProtocolName } from "../clients/utils";
+import helpUrls from "../help-urls";
 
 export default function ClientScopesSection() {
   const { realm } = useRealm();
@@ -167,6 +168,7 @@ export default function ClientScopesSection() {
       <ViewHeader
         titleKey="clientScopes"
         subKey="client-scopes:clientScopeExplain"
+        helpUrl={helpUrls.clientScopesUrl}
       />
       <PageSection variant="light" className="pf-u-p-0">
         <KeycloakDataTable

src/client-scopes/messages.ts

@@ -5,7 +5,7 @@ export default {
     grantedClientScopes: "Granted client scopes",
     clientScopeDetails: "Client scope details",
     clientScopeExplain:
-      "Client scopes allow you to define a common set of protocol mappers and roles, which are shared between multiple clients",
+      "Client scopes allow you to define a common set of protocol mappers and roles, which are shared between multiple clients.",
     searchFor: "Search for client scope",
     protocol: "Protocol",
     assignedType: "Assigned type",

src/clients/ClientsSection.tsx

@@ -31,6 +31,7 @@ import { toAddClient } from "./routes/AddClient";
 import { toClient } from "./routes/Client";
 import { toImportClient } from "./routes/ImportClient";
 import { isRealmClient, getProtocolName } from "./utils";
+import helpUrls from "../help-urls";
 
 export default function ClientsSection() {
   const { t } = useTranslation("clients");
@@ -99,6 +100,7 @@ export default function ClientsSection() {
       <ViewHeader
         titleKey="clients:clientList"
         subKey="clients:clientsExplain"
+        helpUrl={helpUrls.clientsUrl}
         divider={false}
       />
       <PageSection variant="light" className="pf-u-p-0">

src/clients/messages.ts

@@ -122,7 +122,7 @@ export default {
     generalSettings: "General Settings",
     capabilityConfig: "Capability config",
     clientsExplain:
-      "Clients are applications and services that can request authentication of a user",
+      "Clients are applications and services that can request authentication of a user.",
     explainBearerOnly:
       "This is a special OIDC type. This client only allows bearer token requests and cannot participate in browser logins.",
     createSuccess: "Client created successfully",

src/components/help-enabler/HelpHeader.tsx

@@ -13,6 +13,7 @@ import React, { createContext, FunctionComponent, useState } from "react";
 import { useTranslation } from "react-i18next";
 import useRequiredContext from "../../utils/useRequiredContext";
 import "./help-header.css";
+import helpUrls from "../../help-urls";
 
 type HelpContextProps = {
   enabled: boolean;
@@ -44,7 +45,12 @@ export const HelpHeader = () => {
   const { t } = useTranslation();
 
   const dropdownItems = [
-    <DropdownItem key="link" id="link">
+    <DropdownItem
+      key="link"
+      id="link"
+      href={helpUrls.documentationUrl}
+      target="_blank"
+    >
       <Split>
         <SplitItem isFilled>{t("documentation")}</SplitItem>
         <SplitItem>

src/components/view-header/ViewHeader.tsx

@@ -22,12 +22,10 @@ import React, {
   Fragment,
 } from "react";
 import { useTranslation } from "react-i18next";
-import {
-  FormattedLink,
-  FormattedLinkProps,
-} from "../external-link/FormattedLink";
+import { FormattedLink } from "../external-link/FormattedLink";
 import { useHelp } from "../help-enabler/HelpHeader";
 import { HelpItem } from "../help-enabler/HelpItem";
+import "../../help-urls";
 
 export type ViewHeaderProps = {
   titleKey: string;
@@ -36,7 +34,7 @@ export type ViewHeaderProps = {
   isDropdownDisabled?: boolean;
   subKey?: string | ReactNode;
   actionsDropdownId?: string;
-  subKeyLinkProps?: FormattedLinkProps;
+  helpUrl?: string | undefined;
   dropdownItems?: ReactElement[];
   lowerDropdownItems?: any;
   lowerDropdownMenuTitle?: any;
@@ -59,7 +57,7 @@ export const ViewHeader = ({
   badges,
   isDropdownDisabled,
   subKey,
-  subKeyLinkProps,
+  helpUrl,
   dropdownItems,
   lowerDropdownMenuTitle,
   lowerDropdownItems,
@@ -166,9 +164,10 @@ export const ViewHeader = ({
                 : subKey
                 ? t(subKey as string)
                 : ""}
-              {subKeyLinkProps && (
+              {helpUrl && (
                 <FormattedLink
-                  {...subKeyLinkProps}
+                  title={t("common:learnMore")}
+                  href={helpUrl}
                   isInline
                   className="pf-u-ml-md"
                 />

src/events/EventsSection.tsx

@@ -43,6 +43,7 @@ import { toRealmSettings } from "../realm-settings/routes/RealmSettings";
 import { toUser } from "../user/routes/User";
 import { AdminEvents } from "./AdminEvents";
 import "./events.css";
+import helpUrls from "../help-urls";
 
 type UserEventSearchForm = {
   client: string;
@@ -413,6 +414,7 @@ export default function EventsSection() {
             page realm settings to configure.
           </Trans>
         }
+        helpUrl={helpUrls.eventsUrl}
         divider={false}
       />
       <PageSection variant="light" className="pf-u-p-0">

src/groups/GroupsSection.tsx

@@ -28,6 +28,7 @@ import { toGroupsSearch } from "./routes/GroupsSearch";
 import { GroupRoleMapping } from "./GroupRoleMapping";
 
 import "./GroupsSection.css";
+import helpUrls from "../help-urls";
 
 export default function GroupsSection() {
   const { t } = useTranslation("groups");
@@ -107,6 +108,7 @@ export default function GroupsSection() {
       <ViewHeader
         titleKey={!id ? "groups:groups" : currentGroup().name!}
         subKey={!id ? "groups:groupsDescription" : ""}
+        helpUrl={!id ? helpUrls.groupsUrl : ""}
         divider={!id}
         dropdownItems={
           id

src/groups/messages.ts

@@ -1,5 +1,6 @@
 export default {
   groups: {
+    groups: "Groups",
     groupDetails: "Group details",
     childGroups: "Child groups",
     createGroup: "Create group",
@@ -32,7 +33,7 @@ export default {
     moveGroupSuccess: "Group moved",
     moveGroupError: "Could not move group {{error}}",
     tableOfGroups: "Table of groups",
-    groupsDescription: "Description goes here",
+    groupsDescription: "Placeholder for groups explanation.",
     groupCreated: "Group created",
     couldNotCreateGroup: "Could not create group {{error}}",
     createAGroup: "Create a group",

src/help-urls.ts

@@ -0,0 +1,17 @@
+const adminGuide =
+  "https://www.keycloak.org/docs/latest/server_admin/index.html";
+
+export default {
+  documentationUrl: `${adminGuide}`,
+  clientsUrl: `${adminGuide}#assembly-managing-clients_server_administration_guide`,
+  clientScopesUrl: `${adminGuide}#_client_scopes`,
+  realmRolesUrl: `${adminGuide}#assigning-permissions-and-access-using-roles-and-groups`,
+  usersUrl: `${adminGuide}#assembly-managing-users_server_administration_guide`,
+  groupsUrl: `${adminGuide}#assigning-permissions-and-access-using-roles-and-groups`,
+  sessionsUrl: `${adminGuide}#managing-user-sessions`,
+  eventsUrl: `${adminGuide}#configuring-auditing-to-track-events`,
+  realmSettingsUrl: `${adminGuide}#configuring-realms`,
+  authenticationUrl: `${adminGuide}#configuring-authentication`,
+  identityProvidersUrl: `${adminGuide}#_identity_broker`,
+  userFederationUrl: `${adminGuide}#_user-storage-federation`,
+};

src/identity-providers/IdentityProvidersSection.tsx

@@ -37,6 +37,7 @@ import { ProviderIconMapper } from "./ProviderIconMapper";
 import { ManageOderDialog } from "./ManageOrderDialog";
 import { toIdentityProvider } from "./routes/IdentityProvider";
 import { toIdentityProviderCreate } from "./routes/IdentityProviderCreate";
+import helpUrls from "../help-urls";
 
 export default function IdentityProvidersSection() {
   const { t } = useTranslation("identity-providers");
@@ -168,6 +169,7 @@ export default function IdentityProvidersSection() {
       <ViewHeader
         titleKey="common:identityProviders"
         subKey="identity-providers:listExplain"
+        helpUrl={helpUrls.identityProvidersUrl}
       />
       <PageSection
         variant={providers.length === 0 ? "default" : "light"}

src/realm-roles/RealmRolesSection.tsx

@@ -3,6 +3,7 @@ import { PageSection } from "@patternfly/react-core";
 import { ViewHeader } from "../components/view-header/ViewHeader";
 import { useAdminClient } from "../context/auth/AdminClient";
 import { RolesList } from "./RolesList";
+import helpUrls from "../help-urls";
 
 export default function RealmRolesSection() {
   const adminClient = useAdminClient();
@@ -24,7 +25,11 @@ export default function RealmRolesSection() {
 
   return (
     <>
-      <ViewHeader titleKey="roles:title" subKey="roles:roleExplain" />
+      <ViewHeader
+        titleKey="roles:title"
+        subKey="roles:roleExplain"
+        helpUrl={helpUrls.realmRolesUrl}
+      />
       <PageSection variant="light" padding={{ default: "noPadding" }}>
         <RolesList loader={loader} />
       </PageSection>

src/realm-settings/RealmSettingsTabs.tsx

@@ -52,6 +52,7 @@ import { UserRegistration } from "./UserRegistration";
 import { toDashboard } from "../dashboard/routes/Dashboard";
 import environment from "../environment";
 import { UserProfileTab } from "./UserProfileTab";
+import helpUrls from "../help-urls";
 
 type RealmSettingsHeaderProps = {
   onChange: (value: boolean) => void;
@@ -118,6 +119,8 @@ const RealmSettingsHeader = ({
       />
       <ViewHeader
         titleKey={toUpperCase(realmName)}
+        subKey="realm-settings:realmSettingsExplain"
+        helpUrl={helpUrls.realmSettingsUrl}
         divider={false}
         dropdownItems={[
           <DropdownItem

src/realm-settings/messages.ts

@@ -1,5 +1,6 @@
 export default {
   "realm-settings": {
+    realmSettingsExplain: "Placeholder for realm settings explanation.",
     partialImport: "Partial import",
     partialExport: "Partial export",
     deleteRealm: "Delete realm",

src/sessions/SessionsSection.tsx

@@ -22,6 +22,7 @@ import "./SessionsSection.css";
 import { RevocationModal } from "./RevocationModal";
 import type ClientRepresentation from "@keycloak/keycloak-admin-client/lib/defs/clientRepresentation";
 import { LogoutAllSessionsModal } from "./LogoutAllSessionsModal";
+import helpUrls from "../help-urls";
 
 const Clients = (row: UserSessionRepresentation) => {
   return (
@@ -121,6 +122,7 @@ export default function SessionsSection() {
         dropdownItems={dropdownItems}
         titleKey="sessions:title"
         subKey="sessions:sessionExplain"
+        helpUrl={helpUrls.sessionsUrl}
       />
       <PageSection variant="light" className="pf-u-p-0">
         {revocationModalOpen && (

src/sessions/messages.ts

@@ -1,7 +1,7 @@
 export default {
   sessions: {
     title: "Sessions",
-    sessionExplain: "Some description about sessions",
+    sessionExplain: "Placeholder for sessions explanation.",
     searchForSession: "Search session",
     subject: "Subject",
     lastAccess: "Last access",

src/user-federation/UserFederationSection.tsx

@@ -25,6 +25,7 @@ import { ViewHeader } from "../components/view-header/ViewHeader";
 import { useAdminClient, useFetch } from "../context/auth/AdminClient";
 import { useRealm } from "../context/realm-context/RealmContext";
 import "./user-federation.css";
+import helpUrls from "../help-urls";
 
 export default function UserFederationSection() {
   const [userFederations, setUserFederations] =
@@ -69,10 +70,10 @@ export default function UserFederationSection() {
     </DropdownItem>,
   ];
 
-  const learnMoreLinkProps = {
-    title: t("common:learnMore"),
-    href: "https://www.keycloak.org/docs/latest/server_admin/index.html#_user-storage-federation",
-  };
+  // const learnMoreLinkProps = {
+  //   title: t("common:learnMore"),
+  //   href: "https://www.keycloak.org/docs/latest/server_admin/index.html#_user-storage-federation",
+  // };
 
   let cards;
 
@@ -142,8 +143,8 @@ export default function UserFederationSection() {
     <>
       <ViewHeader
         titleKey="userFederation"
-        subKey="user-federation:userFederationExplanation"
-        subKeyLinkProps={learnMoreLinkProps}
+        subKey="user-federation:userFederationExplain"
+        helpUrl={helpUrls.userFederationUrl}
         {...(userFederations && userFederations.length > 0
           ? {
               lowerDropdownItems: ufAddProviderDropdownItems,

src/user-federation/messages.ts

@@ -3,7 +3,7 @@ export default {
     userFederation: "User federation",
     descriptionLanding:
       "This is the description for the user federation landing page",
-    userFederationExplanation:
+    userFederationExplain:
       "Keycloak can federate external user databases. Out of the box we have support for LDAP and Active Directory.",
     getStarted: "To get started, select a provider from the list below.",
     providers: "Add providers",

src/user/UsersSection.tsx

@@ -41,6 +41,7 @@ import { toUser } from "./routes/User";
 import { toAddUser } from "./routes/AddUser";
 
 import "./user-section.css";
+import helpUrls from "../help-urls";
 
 type BruteUser = UserRepresentation & {
   brute?: Record<string, object>;
@@ -260,7 +261,11 @@ export default function UsersSection() {
     <>
       <DeleteConfirm />
       <UnlockUsersConfirm />
-      <ViewHeader titleKey="users:title" />
+      <ViewHeader
+        titleKey="users:title"
+        subKey="users:usersExplain"
+        helpUrl={helpUrls.usersUrl}
+      />
       <PageSection
         data-testid="users-page"
         variant="light"

src/user/messages.ts

@@ -1,6 +1,7 @@
 export default {
   users: {
     title: "Users",
+    usersExplain: "Placeholder for users explanation.",
     searchForUser: "Search user",
     startBySearchingAUser: "Start by searching for users",
     searchForUserDescription: