Fix minor typos in the 'Upgrading' guide (#1701)
This commit is contained in:
Marc Wrobel
GitHub
parent
8ce75864cb
commit
0ea743e15e
12 changed files with 38 additions and 38 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -234,7 +234,7 @@ 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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue