Fix minor typos in the 'Upgrading' guide (#1701)

This commit is contained in:
Marc Wrobel 2022-10-19 08:42:12 +02:00 committed by GitHub
parent 8ce75864cb
commit 0ea743e15e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 38 additions and 38 deletions

View file

@ -19,7 +19,7 @@ A number of things have changed since the preview Quarkus distribution was relea
* Clearer separation between `build options` and `runtime configuration`.
* Custom Quarkus configuration is done through `conf/quarkus.properties`.
* `h2-mem` and `h2-file` databases renamed to `dev-mem` and `dev-file`.
* Features are now enabled/disabled with `--features` and `--features-disabled` replacing the previous approach that had an separate config key for each feature.
* Features are now enabled/disabled with `--features` and `--features-disabled` replacing the previous approach that had a separate config key for each feature.
* Runtime configuration can no longer be passed to `kc.[sh|bat] build` and is no longer persisted in the build
* Logging level and format is now configured with `--log-level` and `--log-format`, while in the past these had to be configured using unsupported Quarkus properties.

View file

@ -80,9 +80,9 @@ In general, the steps to update your realms are the following:
= Account console Patternfly upgrade
The Patternfly (PF) React libraries have been updated updated, `@patternfly/react-core` from v3.153.3 to v4.147.0, `@patternfly/react-icons` from v3.15.16 to v 4.11.8, and `@patternfly/react-styles` from v3.7.14 to v4.11.8. Several minor UI updates were made to bring the account console into alignment with PF design standards.
The Patternfly (PF) React libraries have been updated, `@patternfly/react-core` from v3.153.3 to v4.147.0, `@patternfly/react-icons` from v3.15.16 to v 4.11.8, and `@patternfly/react-styles` from v3.7.14 to v4.11.8. Several minor UI updates were made to bring the account console into alignment with PF design standards.
Custom developed account UIs might not be compatible with these updates due to the breaking changes in PF. Most breaking changes should be resovlable by updating props on PF components.
Custom developed account UIs might not be compatible with these updates due to the breaking changes in PF. Most breaking changes should be resolvable by updating props on PF components.
Resources:

View file

@ -8,7 +8,7 @@ bin/kc.sh start-dev --features-disabled=admin2
An alternative approach to continue using the old admin console is to set the theme for the master realm or any other realm to `keycloak`.
As the new admin console is signficiantly different to the old admin console, is now based on React and uses a newer version of PatternFly, any custom themes will most likely have to be re-implemented from scratch. To create a custom theme for the new admin console the theme should extend `keycloak.v2` instead of `keycloak`.
As the new admin console is significantly different to the old admin console, is now based on React and uses a newer version of PatternFly, any custom themes will most likely have to be re-implemented from scratch. To create a custom theme for the new admin console the theme should extend `keycloak.v2` instead of `keycloak`.
If you have explicitly set the admin console theme to `keycloak` for the master realm or any other realm, it will continue to use the old admin console. To update to the new admin console you need to change the theme to `keycloak.v2`.
@ -132,7 +132,7 @@ stating the modified dependencies as shown below:
Several methods have been deprecated in `KeycloakSession` and will be removed in a future version.
`KeycloakSession` session contains several methods for obtaining a provider for a particular object type, such as for a `UserProvider` there are `users()`, `userLocalStorage()`, `userCache()`, `userStorageManager()`, and `userFederatedStorage()`.
This situaton may be confusing for the developer who has to understand the exact meaning of each method, and depends on current store layout.
This situation may be confusing for the developer who has to understand the exact meaning of each method, and depends on current store layout.
The new store does not distinguish federated from local storage.
For those reasons, only the `users()` method will be kept in `KeycloakSession`, and should replace all other calls listed above.
@ -227,7 +227,7 @@ public class MyClass extends LegacyRealmModel {
== Interface `UserCache` moved to the legacy module
As the caching status of objects will be trasparent to services, the interface `UserCache`
As the caching status of objects will be transparent to services, the interface `UserCache`
has been moved to the module `keycloak-legacy`.
Calls to `session.userCache()` will therefore return only a `UserProvider`, which is a breaking change.

View file

@ -1,7 +1,7 @@
= OpenID Connect Logout Prompt
At Keycloak 18.0.0, the logout is now compatible with the new OIDC specification, which changed the handling for the url parameters. However, to also remain compatible with earlier versions, a compatibility flag is introduced. See the link:{upgradingguide_link}#openid-connect-logout[{upgradingguide_name}] for further information for the backwards compatibility option, which allows your application to still use the old format for the url parameters.
While the url parameters can now be configured to be compatible, there was still one incompatibility with keycloak 17 and earlier releases. If the user does not provide an valid `idTokenHint`, a logout prompt appears instead of a successful logout redirect. Therefore, a new compatibility flag `suppress-logout-confirmation-screen` is introduced to suppress the logout screen.
While the url parameters can now be configured to be compatible, there was still one incompatibility with keycloak 17 and earlier releases. If the user does not provide a valid `idTokenHint`, a logout prompt appears instead of a successful logout redirect. Therefore, a new compatibility flag `suppress-logout-confirmation-screen` is introduced to suppress the logout screen.
You can enable this parameter when you start the server by entering the following command:

View file

@ -102,7 +102,7 @@ use:
* Custom JavaScript authorization policies, which establish authorization based on some user attribute
* X.509 authenticator with custom attribute for mapping the X.509 certificate to the user identity
* Any other custom functionality, where some of the user attributes are used as the metadata for storing authentication/authorization/identity context rather
than simple user profile informations.
than simple user profile information.
See the details in the link:{adminguide_link}#_read_only_user_attributes[Threat model mitigation chapter].
@ -165,7 +165,7 @@ No additional setup is required.
==== Client Credentials Grant without refresh token by default
From this {project_name} version, the OAuth2 Client Credentials Grant endpoint does not issue refresh tokens by default. This behavior is aligned with the OAuth2 specification.
As a side-effect of this change, no user session is created on the {project_name} server side after successful Client Credentials authentication, which results
As a side effect of this change, no user session is created on the {project_name} server side after successful Client Credentials authentication, which results
in improved performance and memory consumption. Clients that use Client Credentials Grant are encouraged to stop using
refresh tokens and instead always authenticate at every request with `grant_type=client_credentials` instead of using `refresh_token` as grant type.
In relation to this, {project_name} has support for revocation of access tokens in the OAuth2 Revocation Endpoint, hence clients are allowed
@ -226,15 +226,15 @@ Instagram IdP now uses new API as the old legacy API was *deprecated*. This requ
please refer to the link:{adminguide_link}#instagram[{adminguide_name}].
Special attention is required for existing users that use Instagram IdP, specially the ones for whom it is the only authentication
option. Such users have to login to Keycloak using Instagram IdP before September 30th, 2020. After that day they'll have
to use a different authentication method (like password) to login to manually update their Instagram social link, or create
option. Such users have to log in to Keycloak using Instagram IdP before September 30th, 2020. After that day they'll have
to use a different authentication method (like password) to log in to manually update their Instagram social link, or create
a new account in Keycloak. This is because Instagram user IDs are not compatible between the old and new API, however the
new API temporarily returns both new and old user IDs to allow migration. Keycloak automatically migrates the ID once user
logs in.
==== Non-standard token introspection endpoint removed
In previous versions, Keycloak advertized two introspection endpoints: `token_introspection_endpoint` and `introspection_endpoint`.
In previous versions, Keycloak advertised two introspection endpoints: `token_introspection_endpoint` and `introspection_endpoint`.
The latter is the one defined by https://datatracker.ietf.org/doc/html/rfc8414#section-2[RFC-8414]. The former, previously deprecated,
has now been removed.
@ -250,7 +250,7 @@ recommended to update applications to use native promise API (`then` and `catch`
Version 9.0.1 fixes a problem which could create duplicated top level groups in the realm. Nevertheless the existence
of previous duplicated groups makes the upgrade process fail. The {project_name} server can be affected by this issue
if it is using a H2, MariaDB, MySQL or PostgreSQL database. Before launching the upgrade, check if the server contains
if it is using an H2, MariaDB, MySQL or PostgreSQL database. Before launching the upgrade, check if the server contains
duplicated top level groups. For example the following SQL query can be executed at database level to list them:
----
@ -289,7 +289,7 @@ REQUIRED and ALTERNATIVE executions not supported at same flow::
So when migrating to the newest version, your existing authentication flows will be automatically migrated preserved the same behavior as existed in the previous version.
If they contain ALTERNATIVE executions at the same level as some REQUIRED executions, then the ALTERNATIVE executions will be added to the separate REQUIRED subflow. This
should ensure same/similar behavior of the particular authentication flow as in the previous version. We always recommend
to doublecheck the configuration of your authentication flow and test it to doublecheck that everything works as expected.
to double-check the configuration of your authentication flow and test it to double-check that everything works as expected.
This recommendation is true in particular if you have some more customized authentication flows with custom authenticator implementations.
=== Migrating to 8.0.0
@ -343,12 +343,12 @@ Changes in the Java SPI::
Some changes exist in the Java Authentication SPI and Credential Provider SPI. The interface `Authenticator` is not changed,
but you may be affected if you're developing more advanced authenticators, which introduce some new credential types (subclasses of `CredentialModel`).
There are changes on the `CredentialProvider` interface and introduction of some new interfaces like `CredentialValidator`. Also you
may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended to double check the latest authentication
may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended to double-check the latest authentication
examples in the server development guide for more details.
Freemarker template changes::
Some changes in the freemarker templates exist. You may be affected if you have your own theme with custom freemarker
templates for login forms or some account forms, especially for the forms related to OTP. It is recommended to double check changes in
templates for login forms or some account forms, especially for the forms related to OTP. It is recommended to double-check changes in
the Freemarker templates in the latest {project_name} and align your templates according to it.
==== User credentials changes
@ -437,7 +437,7 @@ Cross-Datacenter Replication changes::
==== Google Identity Provider updated to use Google Sign-in authentication system
The Google Identity Provider implementation in {project_name} up to version 4.8.1 relies on the Google+ API endpoints
endpoints for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for the Google+ API in favor of the new Google Sign-in authentication system. The {project_name} identity provider has been updated
to use the new endpoints so if this integration is in use make sure you upgrade to {project_name} version 4.8.2 or later.
@ -605,7 +605,7 @@ We added support for UMA 2.0. This version of the UMA specification introduced s
Here are the main changes introduced by UMA 2.0 support. See link:{authorizationguide_link}[{authorizationguide_name}] for details.
Authorization API was removed::
Prior to UMA 2.0 (UMA 1.0), client applications were using the Authorization API to obtain permissions from the server in the format of a RPT. The new version
Prior to UMA 2.0 (UMA 1.0), client applications were using the Authorization API to obtain permissions from the server in the format of an RPT. The new version
of UMA specification has removed the Authorization API which was also removed from {project_name}. In UMA 2.0, RPTs can now be obtained from the token endpoint by using a specific grant type.
See link:{authorizationguide_link}#_service_obtaining_permissions[{authorizationguide_name}] for details.
@ -691,7 +691,7 @@ Second change is changing of some signatures in methods of authentication SPI. T
`RequiredActionProvider`. Classes `AuthenticationFlowContext` and `RequiredActionContext` now allow to retrieve authentication session
instead of client session.
We also added some initial support for sticky sessions. You may want to change your loadbalancer/proxy server and configure it if you don't want to suffer from it and want to have better performance.
We also added some initial support for sticky sessions. You may want to change your load balancer/proxy server and configure it if you don't want to suffer from it and want to have better performance.
The route is added to the new `AUTH_SESSION_ID` cookie. More info in the clustering documentation.
Another change is, that `token.getClientSession()` was removed. This may affect you for example if you're using Client Initiated Identity Broker Linking feature.
@ -720,7 +720,7 @@ refreshed tokens will have KID in the header, so after all users exchange their
==== Changes to the Infinispan caches
The `realms` cache defined in the infinispan subsystem in `standalone.xml` or `standalone-ha.xml` configuration file, now has the eviction with the 10000 records by default.
This is the same default like the `users` cache.
This is the same default as the `users` cache.
Also the `authorization` cache now doesn't have any eviction on it by default.
@ -824,7 +824,7 @@ We've removed the option auth-server-url-for-backend-requests due to issues in s
it was possible to access the Keycloak server from 2 different contexts (internal and external), which was causing issues in token validations etc.
If you still want to use the optimization of network, which this option provided (avoid the application to send backchannel requests
through loadbalancer but send them to local Keycloak server directly) you may need to handle it at hosts configuration (DNS) level.
through load balancer but send them to local Keycloak server directly) you may need to handle it at hosts configuration (DNS) level.
=== Migrating to 1.9.0
@ -996,7 +996,7 @@ The Direct Grant API is now always enabled and the option to enable/disable for
==== Database changed
There are again few database changes.
Remember to backup your database prior to upgrading.
Remember to back up your database prior to upgrading.
==== UserFederationProvider changed
@ -1039,7 +1039,7 @@ It also contains all documentation and examples.
This release contains again a number of changes to the database.
The biggest one is Application and OAuth client merge.
Remember to backup your database prior to upgrading.
Remember to back up your database prior to upgrading.
==== Application and OAuth client merge
@ -1053,7 +1053,7 @@ The previously set Applications will be converted into Clients with `Consent req
==== Database changed
This release contains a number of changes to the database.
Remember to backup your database prior to upgrading.
Remember to back up your database prior to upgrading.
==== `iss` in access and id tokens
@ -1085,7 +1085,7 @@ This was used to configure which attributes should go into access token for part
This was removed and is replaced with protocol mappers which are more flexible.
You don't need to care about migration of database from previous version.
We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it's safer to backup DB before migrating to newer version though). Same applies for exported JSON representation from previous version.
We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it's safer to back up DB before migrating to newer version though). Same applies for exported JSON representation from previous version.
==== Social migration to identity brokering

View file

@ -62,7 +62,7 @@ https://account.live.com/developers/applications/create[Microsoft Application Re
=== Google Identity Provider updated to use Google Sign-in authentication system
The Google Identity Provider implementation in {project_name} up to version 7.2.5 relies on the Google+ API endpoints
endpoints for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for the Google+ API in favor of the new Google Sign-in authentication system. The {project_name} identity provider has been updated
to use the new endpoints so if this integration is in use make sure you upgrade to {project_name} version 7.2.6 or later.

View file

@ -9,7 +9,7 @@ We added support for UMA 2.0. This version of the UMA specification introduced s
Here are the main changes introduced by UMA 2.0 support. See link:{authorizationguide_link}[{authorizationguide_name}] for details.
Authorization API was removed::
Prior to UMA 2.0 (UMA 1.0), client applications were using the Authorization API to obtain permissions from the server in the format of a RPT. The new version
Prior to UMA 2.0 (UMA 1.0), client applications were using the Authorization API to obtain permissions from the server in the format of an RPT. The new version
of UMA specification has removed the Authorization API which was also removed from {project_name}. In UMA 2.0, RPTs can now be obtained from the token endpoint by using a specific grant type.
See link:{authorizationguide_link}#_service_obtaining_permissions[{authorizationguide_name}] for details.
@ -140,7 +140,7 @@ https://account.live.com/developers/applications/create[Microsoft Application Re
=== Google Identity Provider updated to use Google Sign-in authentication system
The Google Identity Provider implementation in {project_name} used to rely on the Google+ API endpoints
endpoints for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for the Google+ API in favor of the new Google Sign-in authentication system. The {project_name} identity provider has been updated
to use the new endpoints so if this integration is in use make sure you upgrade to the latest {project_name} version.

View file

@ -28,7 +28,7 @@ Previously, it was possible to have REQUIRED and ALTERNATIVE executions in the s
So when migrating to this version, your existing authentication flows will be migrated but retain the behavior of the previous version. If an authentication flow contains ALTERNATIVE executions at the same level as REQUIRED executions, the ALTERNATIVE executions are added to the separate REQUIRED subflow.
This strategy should ensure the same or similar behavior of the each authentication flow as in the previous version. However, you may review the configuration of your authentication flow and double check that it works as expected. This recommendation applies in particular for customized authentication flows with custom authenticator implementations.
This strategy should ensure the same or similar behavior of each authentication flow as in the previous version. However, you may review the configuration of your authentication flow and double check that it works as expected. This recommendation applies in particular for customized authentication flows with custom authenticator implementations.
==== OPTIONAL execution requirement removed
@ -42,7 +42,7 @@ Some changes exist in the Java Authentication SPI and Credential Provider SPI.
The interface Authenticator is not changed, but you may be affected if you develop advanced authenticators that introduce some new credential types (subclasses of CredentialModel). Changes exist on the CredentialProvider interface and introduction of some new interfaces such as CredentialValidator.
Also, you may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended that you double check the latest authentication examples in the server development guide for more details.
Also, you may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended that you double-check the latest authentication examples in the server development guide for more details.
==== Freemarker template changes

View file

@ -90,9 +90,9 @@ In general, the steps to update your realms are the following:
=== Account console Patternfly upgrade
The Patternfly (PF) React libraries have been updated updated, `@patternfly/react-core` from v3.153.3 to v4.147.0, `@patternfly/react-icons` from v3.15.16 to v 4.11.8, and `@patternfly/react-styles` from v3.7.14 to v4.11.8. Several minor UI updates were made to bring the account console into alignment with PF design standards.
The Patternfly (PF) React libraries have been updated, `@patternfly/react-core` from v3.153.3 to v4.147.0, `@patternfly/react-icons` from v3.15.16 to v 4.11.8, and `@patternfly/react-styles` from v3.7.14 to v4.11.8. Several minor UI updates were made to bring the account console into alignment with PF design standards.
Custom developed account UIs might not be compatible with these updates due to the breaking changes in PF. Most breaking changes should be resovlable by updating props on PF components.
Custom developed account UIs might not be compatible with these updates due to the breaking changes in PF. Most breaking changes should be resolvable by updating props on PF components.
Resources:

View file

@ -38,7 +38,7 @@ custom server extensions as long as no private, unsupported, or tech preview API
Red Hat Single Sign-On {project_versionDoc} also periodically provides micro releases that contain bug and security fixes.
Micro releases increment the minor release version by the last digit, for example from {project_versionDoc}.0 to {project_versionDoc}.1. These releases
do not require migration and should not impact the server configuration files. The patch management system for ZIP
installations can also rollback the patch and server configuration.
installations can also roll back the patch and server configuration.
A micro release only contains the artifacts that have changed. For example if Red Hat Single Sign-On {project_versionDoc}.1 contains changes to
the server and the JavaScript adapter, but not the EAP adapter, only the server and JavaScript adapter are released and require

View file

@ -2,7 +2,7 @@
= Patching an RPM Installation
.Prerequisites
* Ensure that the base operating system is up to date, and is subscribed and enabled to get updates from the standard Red Hat Enterprise Linux repositories.
* Ensure that the base operating system is up-to-date, and is subscribed and enabled to get updates from the standard Red Hat Enterprise Linux repositories.
* Ensure that you are subscribed to the relevant RH-SSO repository for the update.
* Back up all configuration files, deployments, and user data.

View file

@ -70,7 +70,7 @@ image:images/patching-standalone-tab.png[The Patch Management Screen for a Stand
image:images/patching-domain-tab.png[The Patch Management Screen for a Managed Domain]
. Click *Apply a New Patch*.
.. If you are patching a managed domain host, on the next screen select whether to shutdown the servers on the host, and click *Next*.
.. If you are patching a managed domain host, on the next screen select whether to shut down the servers on the host, and click *Next*.
. Click the *Browse* button, select the downloaded patch you want to apply, and then click *Next*.
+
@ -137,7 +137,7 @@ shutdown --restart=true
+
.Recent Patch History Screen
image:images/patching-rollback-table.png[Recent Patch History Screen]
.. If you are rolling back a patch on a managed domain host, on the next screen select whether to shutdown the servers on the host, and click *Next*.
.. If you are rolling back a patch on a managed domain host, on the next screen select whether to shut down the servers on the host, and click *Next*.
. Choose your options for the rollback process, then click *Next*.
+
@ -145,7 +145,7 @@ image:images/patching-rollback-table.png[Recent Patch History Screen]
image:images/patching-rollback-options.png[Patch Rollback Options]
. Confirm the options and the patch to be rolled back, then click *Next*.
.. If there are any conflicts in attempting to rollback the patch and the *Override all* option was not selected, a warning will be displayed. Click *View error details* to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or click *Choose Options* and try the operation again with the *Override all* check box selected. Overriding conflicts will result in the rollback operation overriding any user modifications.
.. If there are any conflicts in attempting to roll back the patch and the *Override all* option was not selected, a warning will be displayed. Click *View error details* to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or click *Choose Options* and try the operation again with the *Override all* check box selected. Overriding conflicts will result in the rollback operation overriding any user modifications.
. After the patch has been successfully rolled back, select whether to restart the RH-SSO server now for the changes to take effect, and click *Finish*.