From 9703e101da28b00a98a6fbf808563d7cb9d0f0a2 Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Wed, 14 Oct 2026 12:55:03 +0200 Subject: [PATCH] Adjust links to upstream/downstream for the upcoming 26.8 release Closes #53819 Signed-off-by: AndyMunro Signed-off-by: Alexander Schwartz Co-authored-by: AndyMunro --- docs/guides/attributes.adoc | 3 ++- docs/guides/high-availability/pinned-guides | 12 +++++----- .../migration/migrating-to-quarkus.adoc | 5 +++-- docs/guides/observability/telemetry.adoc | 6 ++--- .../securing-apps/distribution-registry.adoc | 2 +- ...ity-assertion-jwt-authorization-grant.adoc | 4 ++-- .../guides/securing-apps/mod-auth-mellon.adoc | 4 ++-- docs/guides/securing-apps/oidc-layers.adoc | 10 ++++----- .../partials/oidc/fapi-support.adoc | 2 +- .../partials/overview/getting-started.adoc | 4 ++-- docs/guides/securing-apps/ssf-support.adoc | 22 +++++++++---------- docs/guides/securing-apps/token-exchange.adoc | 2 +- .../server/bootstrap-admin-recovery.adoc | 2 +- .../guides/server/configuration-provider.adoc | 2 +- docs/guides/ui-customization/themes.adoc | 4 ++-- 15 files changed, 43 insertions(+), 41 deletions(-) diff --git a/docs/guides/attributes.adoc b/docs/guides/attributes.adoc index 86fdb6a037c..b040c2f3249 100644 --- a/docs/guides/attributes.adoc +++ b/docs/guides/attributes.adoc @@ -30,6 +30,7 @@ :adminguide_name_short: Server Administration :adminguide_link: {project_doc_base_url}/server_admin/ :adminguide_vault: {adminguide_link}#_vault-key-resolvers +:adminguide_user_locale: {adminguide_link}#_user_locale_selection :quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts :quickstartRepo_name: Keycloak Quickstarts Repository :quickstartRepo_dir: keycloak-quickstarts @@ -45,4 +46,4 @@ :keycloak_benchmark_name: Keycloak Benchmark Project :ui_customization_guide_name: UI Customization Guide :ui_customization_guide_link: {project_doc_base_url}/ui-customization/ - +:server_providers: {developerguide_link}#_providers diff --git a/docs/guides/high-availability/pinned-guides b/docs/guides/high-availability/pinned-guides index dbe2f940d44..7e48cc213a1 100644 --- a/docs/guides/high-availability/pinned-guides +++ b/docs/guides/high-availability/pinned-guides @@ -12,6 +12,12 @@ single-cluster/monitoring-cnpg single-cluster/deploy-cnpg-recovery single-cluster/deploy-keycloak single-cluster/operate-cnpg-switchover +multi-cluster-v2/introduction +multi-cluster-v2/concepts +multi-cluster-v2/deploy-keycloak-kubernetes +multi-cluster-v2/deploy-keycloak-bare-metal +multi-cluster-v2/upgrades +multi-cluster-v2/migrate-from-v1-to-v2 multi-cluster/introduction multi-cluster/concepts multi-cluster/building-blocks @@ -29,9 +35,3 @@ multi-cluster/operate-site-online multi-cluster/operate-synchronize multi-cluster/health-checks multi-cluster/upgrades -multi-cluster-v2/introduction -multi-cluster-v2/concepts -multi-cluster-v2/deploy-keycloak-kubernetes -multi-cluster-v2/deploy-keycloak-bare-metal -multi-cluster-v2/upgrades -multi-cluster-v2/migrate-from-v1-to-v2 diff --git a/docs/guides/migration/migrating-to-quarkus.adoc b/docs/guides/migration/migrating-to-quarkus.adoc index 20011d7c0e2..43f0c7f95ad 100644 --- a/docs/guides/migration/migrating-to-quarkus.adoc +++ b/docs/guides/migration/migrating-to-quarkus.adoc @@ -1,4 +1,5 @@ <#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> <@tmpl.guide title="Migrating to Quarkus distribution" @@ -77,7 +78,7 @@ Depending on what APIs your providers use you may also need to make some changes == Migrating containers -The container images for the Quarkus distribution derive from UBI Micro instead of UBI Minimal. This means that some binaries or configuration files (those not necessary for Keycloak's main functionality) may be missing. The solution is to add these files in as part of the container customization process explained in the https://www.keycloak.org/server/containers[Container guide]. +The container images for the Quarkus distribution derive from UBI Micro instead of UBI Minimal. This means that some binaries or configuration files (those not necessary for Keycloak's main functionality) may be missing. The solution is to add these files in as part of the container customization process explained in the <@links.server id="containers" /> {section}. For example, for the Kerberos authentication features you will need to add `/etc/krb5.conf`. The `krb5-libs` RPM previously supplied this file, but was removed in the switch to UBI Micro. Note that binaries from `krb5-libs` are not required for Keycloak's Kerberos authentication features to work. @@ -108,7 +109,7 @@ When using `kubectl` commands, and the 2 CRDs are installed in the cluster, make $ kubectl get keycloaks.k8s.keycloak.org ---- -The new operator doesn't support Client, User and Realm CRDs directly. Instead, it provides one CRD to perform a https://www.keycloak.org/operator/realm-import.html[Realm import]. +The new operator doesn't support Client, User and Realm CRDs directly. Instead, it provides one CRD to perform a realm import as described in <@links.operator id="realm-import" />. Using this new CR you can import Users, Clients and more through the wrapping Realm. == Priority of X-Forwarded-* Headers diff --git a/docs/guides/observability/telemetry.adoc b/docs/guides/observability/telemetry.adoc index 7c6e5721be7..4f3e0d22e85 100644 --- a/docs/guides/observability/telemetry.adoc +++ b/docs/guides/observability/telemetry.adoc @@ -116,7 +116,7 @@ spec: == Traces -See the https://www.keycloak.org/observability/tracing[Root cause analysis with tracing guide]. +See the <@links.observability id="tracing" /> {section}. You can override the global OpenTelemetry settings via the Tracing options if you want to export traces to a different OpenTelemetry collector. @@ -133,7 +133,7 @@ You can enable OpenTelemetry Logs via CLI as follows: <@kc.start parameters="--features=opentelemetry-logs --telemetry-logs-enabled=true"/> -For more information on how to set up logging, see the https://www.keycloak.org/server/logging[Configuring Logging guide]. +For more information on how to set up logging, see the <@links.server id="logging" />. === Log level By default, all log levels are exported by {project_name}. @@ -171,7 +171,7 @@ You can enable the OpenTelemetry Metrics via CLI as follows: NOTE: Metrics (`metrics-enabled`) needs to be enabled as well -For more information on how to set up metrics, see the configuration options below or visit the https://www.keycloak.org/observability/configuration-metrics[Gaining insights with metrics guide]. +For more information on how to set up metrics, see the configuration options below or visit the <@links.observability id="configuration-metrics" />. === Request headers As stated for the general configuration of headers, you can configure custom request headers that will be used when exporting metrics. diff --git a/docs/guides/securing-apps/distribution-registry.adoc b/docs/guides/securing-apps/distribution-registry.adoc index db62ee7eb69..ab02c72716d 100644 --- a/docs/guides/securing-apps/distribution-registry.adoc +++ b/docs/guides/securing-apps/distribution-registry.adoc @@ -8,7 +8,7 @@ summary="Configure a Distribution Registry to use {project_name}."> NOTE: Docker Registry has been renamed to Distribution Registry, however feature, endpoint and protocol are still called Docker. -NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. +NOTE: Docker authentication is disabled by default. To enable see the <@links.server id="features" /> {section}. This section describes how you can configure a Distribution registry to use {project_name} as its authentication server. diff --git a/docs/guides/securing-apps/identity-assertion-jwt-authorization-grant.adoc b/docs/guides/securing-apps/identity-assertion-jwt-authorization-grant.adoc index a1b3fbad3b1..45b45309aff 100644 --- a/docs/guides/securing-apps/identity-assertion-jwt-authorization-grant.adoc +++ b/docs/guides/securing-apps/identity-assertion-jwt-authorization-grant.adoc @@ -35,7 +35,7 @@ As this is an evolving draft, Keycloak's implementation of ID-JAG is being deliv == Use Case Example: MCP (Model Context Protocol) -A primary use case for ID-JAG is securing interactions in AI ecosystems, such as those using the **Model Context Protocol (MCP)**. +A primary use case for ID-JAG is securing interactions in AI ecosystems, such as those using the **Model Context Protocol (MCP)**. In this scenario, an AI Assistant (Client App A / MCP Client) needs to access a backend resource or tool (Client App B / MCP Authorization Server and MCP Resource Server) on behalf of an authenticated user. Instead of sharing credentials or prompting the user again, the MCP Client uses ID-JAG to seamlessly securely exchange its identity assertion for an access token scoped for the MCP Resource Server. == Architecture Flow (ID-JAG / Cross-App Access) @@ -187,6 +187,6 @@ A successful response will return a JSON object containing the newly issued loca * https://oauth.net/cross-app-access/[oauth.net: Cross-App Access (XAA) Overview] * https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/[IETF draft: Identity Assertion JWT Authorization Grant (ID-JAG)] * https://datatracker.ietf.org/doc/html/rfc7523[RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants] -* https://www.keycloak.org/securing-apps/oauth-identity-authorization-chaining-across-domains[Keycloak Documentation: OAuth Identity and Authorization Chaining Across Domains] +* <@links.securingapps id="oauth-identity-authorization-chaining-across-domains" /> diff --git a/docs/guides/securing-apps/mod-auth-mellon.adoc b/docs/guides/securing-apps/mod-auth-mellon.adoc index 7338003802d..251cec537c6 100644 --- a/docs/guides/securing-apps/mod-auth-mellon.adoc +++ b/docs/guides/securing-apps/mod-auth-mellon.adoc @@ -209,10 +209,10 @@ Use this procedure to set important client configuration parameters. . Ensure *Force POST Binding* is On. . Add paosResponse to the *Valid Redirect URIs* list: . Copy the postResponse URL in *Valid Redirect URIs* and paste it into the empty add text fields just below the "+". -. Change `postResponse` to paosResponse`. (The paosResponse URL is needed for SAML ECP.) +. Change `postResponse` to `paosResponse`. (The paosResponse URL is needed for SAML ECP.) . Click *Save* at the bottom. -Many SAML SPs determine authorization based on a user's membership in a group. The {project_name} IdP can manage user group information but it does not supply the user's groups unless the IdP is configured to supply it as a SAML attribute. +Many SAML SPs determine authorization based on a user's membership in a group. The {project_name} IdP can manage user group information, but it does not supply the user's groups unless the IdP is configured to supply it as a SAML attribute. Perform the following procedure to configure the IdP to supply the user's groups as a SAML attribute. diff --git a/docs/guides/securing-apps/oidc-layers.adoc b/docs/guides/securing-apps/oidc-layers.adoc index e8fc4f5a691..78b2106457b 100644 --- a/docs/guides/securing-apps/oidc-layers.adoc +++ b/docs/guides/securing-apps/oidc-layers.adoc @@ -8,14 +8,14 @@ summary="Use OpenID Connect with {project_name} to secure applications and servi <#include "partials/oidc/available-endpoints.adoc" /> -include::partials/oidc/supported-grant-types.adoc[] +<#include "partials/oidc/supported-grant-types.adoc" /> -include::partials/oidc/oidc-errors.adoc[] +<#include "partials/oidc/oidc-errors.adoc" /> -include::partials/oidc/fapi-support.adoc[] +<#include "partials/oidc/fapi-support.adoc" /> -include::partials/oidc/oauth21-support.adoc[] +<#include "partials/oidc/oauth21-support.adoc" /> -include::partials/oidc/recommendations.adoc[] +<#include "partials/oidc/recommendations.adoc" /> diff --git a/docs/guides/securing-apps/partials/oidc/fapi-support.adoc b/docs/guides/securing-apps/partials/oidc/fapi-support.adoc index 3fa2b176f08..ba6a60742fa 100644 --- a/docs/guides/securing-apps/partials/oidc/fapi-support.adoc +++ b/docs/guides/securing-apps/partials/oidc/fapi-support.adoc @@ -47,4 +47,4 @@ If you want to apply the Australia CDR security profile, you need to use `fapi-1 As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS). Moreover, there are some requirements in the FAPI specification for the cipher suites and TLS protocol versions used. To match these requirements, you can consider configure allowed ciphers. This configuration can be done by setting the `https-protocols` and `https-cipher-suites` options. {project_name} uses `TLSv1.3` by default and hence it is possibly not needed to change the default settings. However it -may be needed to adjust ciphers if you need to fall back to lower TLS version for some reason. For more details, see https://www.keycloak.org/server/enabletls[Configuring TLS] {section}. +may be needed to adjust ciphers if you need to fall back to lower TLS version for some reason. For more details, see <@links.server id="enabletls" /> {section}. diff --git a/docs/guides/securing-apps/partials/overview/getting-started.adoc b/docs/guides/securing-apps/partials/overview/getting-started.adoc index dc687aaec99..a280bc081ba 100644 --- a/docs/guides/securing-apps/partials/overview/getting-started.adoc +++ b/docs/guides/securing-apps/partials/overview/getting-started.adoc @@ -16,10 +16,10 @@ ifeval::[{project_community}==true] endif::[] ==== JavaScript (client-side) -* https://www.keycloak.org/securing-apps/javascript-adapter[Keycloak JS adapter] +* <@links.securingapps id="javascript-adapter" /> ==== Node.js (server-side) -* https://www.keycloak.org/securing-apps/nodejs-adapter[Keycloak Node.js adapter] +* <@links.securingapps id="nodejs-adapter" /> ifeval::[{project_community}==true] ==== C# diff --git a/docs/guides/securing-apps/ssf-support.adoc b/docs/guides/securing-apps/ssf-support.adoc index a0a44134b2a..a5e53a1e9ba 100644 --- a/docs/guides/securing-apps/ssf-support.adoc +++ b/docs/guides/securing-apps/ssf-support.adoc @@ -14,7 +14,7 @@ changed, an account was disabled, an assurance level changed etc. to other relyi are encoded as JWS-signed https://www.rfc-editor.org/rfc/rfc8417[Security Event Tokens (SETs)] whose payloads are described by profiles such as https://openid.net/specs/openid-caep-1_0-final.html[CAEP] (Continuous Access Evaluation Profile) and https://openid.net/specs/openid-risc-1_0-final.html[RISC] (Risk Incident Sharing and Coordination). Receivers verify -each SET against the transmitter's JWKS and act on it locally, e.g. for example, by terminating cached sessions when +each SET against the transmitter's JWKS and act on it locally, for example, by terminating cached sessions when {project_name} signals a logout. {project_name} plays the *Transmitter* role: it observes user, session, and credential events, maps them to typed @@ -26,8 +26,8 @@ https://www.rfc-editor.org/rfc/rfc8935[RFC 8935] (PUSH) and https://www.rfc-edit The {project_name} SSF Transmitter exposes four moving parts that an administrator works with: * *Realm-level transmitter capability* a per-realm switch that turns SSF on for a single realm. Discovery metadata - is published at `/.well-known/ssf-configuration/realms/{realm}` (and the alternative - `/realms/{realm}/.well-known/ssf-configuration`). + is published at `+/.well-known/ssf-configuration/realms/{realm}+` (and the alternative + `+/realms/{realm}/.well-known/ssf-configuration+`). * *SSF Receivers* regular OAuth/OIDC clients marked as SSF receivers. Each receiver describes how it wants events delivered (PUSH or POLL), which event types it supports, and which subjects it is interested in. * *Streams* one stream per receiver, representing the active subscription. The stream carries the delivery @@ -131,7 +131,7 @@ authenticates with a service account). . Configure the receiver on the *Receiver* sub-tab (see <>). . Hand the receiver its credentials and let it register its own stream against the SSF management API. This is the default flow: the receiver discovers the transmitter via `/.well-known/ssf-configuration`, calls -`POST /realms/{realm}/ssf/transmitter/streams` with the delivery method and event types it wants, and continues +`+POST /realms/{realm}/ssf/transmitter/streams+` with the delivery method and event types it wants, and continues to manage the subscription itself. Streams registered this way are marked as <>. The receiver authenticates SSF management API calls using a bearer token issued for this client. Required scopes @@ -174,8 +174,8 @@ Empty means both are allowed. |*Valid push URLs* |`##`-separated allow-list of URL patterns the receiver may register as its push endpoint. Required when PUSH -is allowed. Each entry is matched as either an exact URL or a trailing-`*` suffix wildcard -(e.g. `\https://receiver.example.com/ssf/*`). Bare `*` is not honoured, this is the SSRF defence on outbound +is allowed. Each entry is matched as either an exact URL or a trailing-`+*+` suffix wildcard +(e.g. `++https://receiver.example.com/ssf/*++`). Bare `+*+` is not honored, this is the SSRF defense on outbound PUSH delivery. |*Allow synthetic events* / *Emit events role* @@ -225,7 +225,7 @@ management API. A poll request carries `maxEvents`, optional `ack` (jti list to `setErrs` (jti list to negative-acknowledge). The response delivers up to `maxEvents` signed SETs and a `moreAvailable` flag. -NOTE: HTTP long-polling (`returnImmediately=false`, `maxWait`) is parsed but not yet honoured. This means every poll +NOTE: HTTP long-polling (`returnImmediately=false`, `maxWait`) is parsed but not yet honored. This means every poll returns immediately. Receivers should configure their own polling cadence accordingly. === Switching delivery method @@ -283,7 +283,7 @@ inactivity timeout. A verification SET (containing only an opaque `sub_id = stream_id`) can be triggered: -* By the receiver via `POST /realms/{realm}/ssf/transmitter/verify`, rate-limited per receiver via the +* By the receiver via `+POST /realms/{realm}/ssf/transmitter/verify+`, rate-limited per receiver via the `min_verification_interval` setting; over-frequent calls receive `429 Too Many Requests`. * By an administrator via the *Verify* button on the *Stream* sub-tab, bypasses the rate limit. * Automatically by the transmitter shortly after stream creation. @@ -298,7 +298,7 @@ registered it: client is the conceptual owner of the configuration; the admin UI flags admin edits as overrides. This is also the implicit value for streams that pre-date the introduction of the marker. * *KEYCLOAK* the stream was registered through the admin-facing - `POST /admin/realms/{realm}/ssf/clients/{clientId}/stream` endpoint, driven by the *Stream* sub-tab in the + `+POST /admin/realms/{realm}/ssf/clients/{clientId}/stream+` endpoint, driven by the *Stream* sub-tab in the admin console. The receiver never called the SSF management endpoints; the operator drives the stream lifecycle. The marker is purely informational. Both modes accept both admin-driven and receiver-driven updates; the @@ -361,13 +361,13 @@ Two authorized call paths exist: * *Administrator emit* -- callers with permission to manage the receiver client may emit any registered event type via the *Emit Events* sub-tab in the admin console, or via - `POST /admin/realms/{realm}/ssf/clients/{clientId}/events/emit`. + `+POST /admin/realms/{realm}/ssf/clients/{clientId}/events/emit+`. * *Trusted-emitter service account* -- with `ssf.allowEmitEvents=true` and `ssf.emitEventsRole=` set on the receiver, an external system can post events to the same endpoint using its own OAuth service-account credentials, provided the service account holds the configured role. Stream-internal lifecycle event types (`stream-verification`, `stream-updated`) cannot be emitted, as they are -reserved to the transmitter so external callers cannot forge transmitter behaviour towards a receiver. +reserved to the transmitter so external callers cannot forge transmitter behavior toward a receiver. == Specifications diff --git a/docs/guides/securing-apps/token-exchange.adoc b/docs/guides/securing-apps/token-exchange.adoc index 62a7c6aa946..fe62b89364f 100644 --- a/docs/guides/securing-apps/token-exchange.adoc +++ b/docs/guides/securing-apps/token-exchange.adoc @@ -673,7 +673,7 @@ If you still need legacy token exchange feature, you also need link:{adminguide_ link:{adminguide_link}#_fine_grained_permissions[Fine-grained admin permissions version 2] (FGAP:v2) does not have support for token exchange permissions. This is on purpose because token-exchange is conceptually not really an "admin" permission and hence there is no plan to add token exchange permissions to FGAP:v2. -For details, see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}. +For details, see the <@links.server id="features" /> {section}. ==== === How token exchange works diff --git a/docs/guides/server/bootstrap-admin-recovery.adoc b/docs/guides/server/bootstrap-admin-recovery.adoc index 45a8a962c2c..678e825c679 100644 --- a/docs/guides/server/bootstrap-admin-recovery.adoc +++ b/docs/guides/server/bootstrap-admin-recovery.adoc @@ -12,7 +12,7 @@ A user or service admin account created using one of the methods described below == Bootstrapping a temporary admin account at {project_name} startup -{project_name} `start` and `start-dev` commands support options for bootstrapping both temporary admin users and admin service accounts. These options are standard configuration options, so they can be specified in any of the https://www.keycloak.org/server/configuration#_configuring_sources_for_keycloak[configuration sources] such as environment variables or CLI parameters. For instance, the following examples demonstrate how to use the `start` and `start-dev` commands with CLI parameters to bootstrap a temporary admin user and an admin service account, respectively: +{project_name} `start` and `start-dev` commands support options for bootstrapping both temporary admin users and admin service accounts. These options are standard configuration options, so they can be specified through any of the sources described in <@links.server id="configuration" anchor="_configuring_sources_for_keycloak" />, such as environment variables or CLI parameters. For instance, the following examples demonstrate how to use the `start` and `start-dev` commands with CLI parameters to bootstrap a temporary admin user and an admin service account, respectively: <@kc.start parameters="--bootstrap-admin-username tmpadm --bootstrap-admin-password pass"/> diff --git a/docs/guides/server/configuration-provider.adoc b/docs/guides/server/configuration-provider.adoc index 654b31900b7..b5a75223cbe 100644 --- a/docs/guides/server/configuration-provider.adoc +++ b/docs/guides/server/configuration-provider.adoc @@ -136,6 +136,6 @@ Once you do that, the server is going to make these additional dependencies avai == References * <@links.server id="configuration"/> -* https://www.keycloak.org/docs/latest/server_development/#_providers[Server Developer Documentation] +* {server_providers}[Service Provider Interfaces] diff --git a/docs/guides/ui-customization/themes.adoc b/docs/guides/ui-customization/themes.adoc index 7ecc59d7770..1ecfd4430da 100644 --- a/docs/guides/ui-customization/themes.adoc +++ b/docs/guides/ui-customization/themes.adoc @@ -514,7 +514,7 @@ and resources. By default, the locale is selected using the `DefaultLocaleSelectorProvider` which implements the `LocaleSelectorProvider` interface. English is the default language when internationalization is disabled. -With internationalization enabled, the locale is resolved according to the logic described in the https://www.keycloak.org/docs/latest/server_admin/#_user_locale_selection[Server Administration documentation]. +With internationalization enabled, the locale is resolved according to the logic described in the {adminguide_user_locale}[Server Administration documentation]. This behavior can be changed through the `LocaleSelectorSPI` by implementing the `LocaleSelectorProvider` and `LocaleSelectorProviderFactory`. @@ -523,4 +523,4 @@ The `LocaleSelectorProvider` interface has a single method, `resolveLocale`, whi Custom implementations can extend the `DefaultLocaleSelectorProvider` in order to reuse parts of the default behavior. For example to ignore the `Accept-Language` request header, a custom implementation could extend the default provider, override it's `getAcceptLanguageHeaderLocale`, and return a null value. As a result the locale selection will fall back on the realm's default language. === Additional resources for Locale selector -* For more details on creating and deploying a custom provider, see https://www.keycloak.org/docs/latest/server_development/index.html#_providers[Service Provider Interfaces]. +* For more details on creating and deploying a custom provider, see {server_providers}[Service Provider Interfaces].