Correcting JavaScript spelling.
This commit is contained in:
AndyMunro
Bruno Oliveira da Silva
parent
d2fe06ed33
commit
851fdbae43
20 changed files with 156 additions and 95 deletions
|
|
@ -45,7 +45,7 @@
|
|||
:adminguide_name: Server Administration Guide
|
||||
:adminguide_link: {project_doc_base_url}/server_administration_guide/
|
||||
:adminguide_authentication_flow_name: authentication flow
|
||||
:adminguide_authentication_flow_link: {adminguide_link}#authentication-flows
|
||||
:adminguide_authentication_flow_link: {adminguide_link}#_authentication-flows
|
||||
:adminguide_bruteforce_name: Password guess: brute force attacks
|
||||
:adminguide_bruteforce_link: {adminguide_link}#password-guess-brute-force-attacks
|
||||
:adminguide_disabling_automatic_user_creation_name: disabling automatic user creation
|
||||
|
|
|
|||
|
|
@ -10,4 +10,5 @@ include::topics/templates/document-attributes-product.adoc[]
|
|||
= {upgradingguide_name}
|
||||
|
||||
include::topics/templates/making-open-source-more-inclusive.adoc[]
|
||||
|
||||
include::topics.adoc[]
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[[_install_new_version]]
|
||||
|
||||
== Upgrading {project_name} server
|
||||
== Upgrading the {project_name} server
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
|
|
@ -11,9 +11,10 @@ Please refer to the migration changes for details on the version you are upgradi
|
|||
|
||||
It is important that you upgrade {project_name} server before upgrading the adapters.
|
||||
|
||||
To upgrade {project_name} server, complete the following steps:
|
||||
.Prerequisites
|
||||
* Handle any open transactions and delete the data/tx-object-store/ transaction directory.
|
||||
|
||||
. Prior to applying the upgrade, handle any open transactions and delete the data/tx-object-store/ transaction directory.
|
||||
.Procedure
|
||||
. Download the new server archive
|
||||
. Move the downloaded archive to the desired location.
|
||||
. Extract the archive. This step installs a clean instance of the latest {project_name} release.
|
||||
|
|
@ -31,11 +32,30 @@ Files in the bin directory should not be overwritten by the files from previous
|
|||
. Copy any custom modules that have been added to the modules directory.
|
||||
. Run the applicable upgrade script below.
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
To upgrade {project_name} server RPM distribution, complete the following steps:
|
||||
[id="upgrade-script"]
|
||||
== Run the server upgrade script
|
||||
|
||||
. Prior to applying the upgrade, handle any open transactions and delete the /var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ transaction directory.
|
||||
. Make sure you have subscribed to proper repositories containing JBOSS EAP and {project_name}.
|
||||
Based on your previous installation, run the appropriate upgrade script that applies to your situation:
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
* xref:rpm-upgrade[RPM distribution]
|
||||
endif::[]
|
||||
* xref:standalone-mode[Standalone mode]
|
||||
* xref:standalone-ha[Standalone high availability mode]
|
||||
* xref:domain-mode[Domain mode]
|
||||
* xref:domain-clustered[Domain-clustered mode]
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
|
||||
[id="rpm-upgrade"]
|
||||
=== Run the RPM distribution script
|
||||
|
||||
.Prerequisites
|
||||
* Handle any open transactions and delete the /var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ transaction directory.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Make sure you have subscribed to the proper repositories containing JBOSS EAP and {project_name}.
|
||||
+
|
||||
For Red Hat Enterprise Linux 7:
|
||||
+
|
||||
|
|
@ -72,8 +92,10 @@ Use it when calling migration scripts below.
|
|||
====
|
||||
endif::[]
|
||||
|
||||
=== Running the Standalone Mode Upgrade Script
|
||||
To run the upgrade script for standalone mode, complete the following steps:
|
||||
[id="standalone-mode"]
|
||||
=== Running the Standalone Mode upgrade script
|
||||
|
||||
.Procedure
|
||||
|
||||
. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
|
||||
. Stop the server.
|
||||
|
|
@ -81,26 +103,38 @@ To run the upgrade script for standalone mode, complete the following steps:
|
|||
|
||||
bin/jboss-cli.sh --file=bin/migrate-standalone.cli
|
||||
|
||||
=== Running the Standalone-High Availability Mode Upgrade Script
|
||||
[id="standalone-ha"]
|
||||
=== Running the Standalone-High Availability Mode upgrade script
|
||||
For standalone-high availability (HA) mode, all instances must be upgraded at the same time.
|
||||
|
||||
To run the upgrade script for standalone-HA mode, complete the following steps:
|
||||
|
||||
.Procedure
|
||||
. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
|
||||
. Stop the server.
|
||||
. Run the upgrade script:
|
||||
|
||||
bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
|
||||
|
||||
=== Running the Domain Mode Upgrade Script
|
||||
[id="domain-mode"]
|
||||
=== Running the Domain Mode upgrade script
|
||||
For domain mode, all instances must be upgraded at the same time.
|
||||
|
||||
To run the upgrade script for domain mode, complete the following steps:
|
||||
.Procedure
|
||||
|
||||
. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
|
||||
. Edit the domain script to include the location of the keycloak-server.json file.
|
||||
. Stop the server.
|
||||
. Run the upgrade script on the domain controller only:
|
||||
|
||||
. Run the upgrade script on the domain controller
|
||||
bin/jboss-cli.sh --file=bin/migrate-domain.cli
|
||||
|
||||
[id="domain-clustered"]
|
||||
=== Running the Domain-clustered Mode upgrade script
|
||||
For domain-clustered mode, all instances must be upgraded at the same time.
|
||||
|
||||
.Procedure
|
||||
|
||||
. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
|
||||
. Edit the domain-clustered script to include the location of the keycloak-server.json file.
|
||||
. Stop the server.
|
||||
. Run the upgrade script on the domain controller only:
|
||||
|
||||
bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli
|
||||
|
|
|
|||
|
|
@ -112,7 +112,7 @@ use:
|
|||
|
||||
* Custom user storage providers
|
||||
* Custom authenticators
|
||||
* Custom Javascript authorization policies, which establish authorization based on some user attribute
|
||||
* 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.
|
||||
|
|
@ -499,7 +499,7 @@ Audiences of all the clients, for which authenticated user has at least one clie
|
|||
to the `aud` claim in the access token now. On the other hand, an access token may not automatically contain the audience of the
|
||||
frontend client, for which it was issued. Read the link:{adminguide_link}#audience-support[{adminguide_name}] for more details.
|
||||
|
||||
==== JavaScript Adapter Promise
|
||||
==== JavaScript adapter Promise
|
||||
|
||||
To use native JavaScript promise with the JavaScript adapter it is now required to set `promiseType` to `native` in the
|
||||
init options.
|
||||
|
|
@ -631,8 +631,8 @@ Entitlement API was removed::
|
|||
Changes to UMA Discovery Endpoint::
|
||||
UMA Discovery document changed, see link:{authorizationguide_link}#_service_authorization_api[{authorizationguide_name}] for details.
|
||||
|
||||
Changes to {project_name} Authorization JavaScript Adapter::
|
||||
The {project_name} Authorization JavaScript Adapter (keycloak-authz.js) changed in order to comply with the changes introduced by UMA 2.0 while keeping
|
||||
Changes to {project_name} Authorization JavaScript adapter::
|
||||
The {project_name} Authorization JavaScript adapter (keycloak-authz.js) changed in order to comply with the changes introduced by UMA 2.0 while keeping
|
||||
the same behavior as before. The main change is on how you invoke both `authorization` and `entitlement` methods which now
|
||||
expect a specific object type representing an authorization request. This new object type provides more flexibility on how
|
||||
permissions can be obtained from the server by supporting the different parameters supported by the UMA grant type.
|
||||
|
|
@ -848,7 +848,7 @@ We've moved the themes and providers directories from `standalone/configuration/
|
|||
If you have added custom themes and providers you need to move them to the new location.
|
||||
You also need to update `keycloak-server.json` as it's changed due to this.
|
||||
|
||||
==== Adapter Subsystems only bring in dependencies if Keycloak is on
|
||||
==== adapter Subsystems only bring in dependencies if Keycloak is on
|
||||
|
||||
Previously, if you had installed our SAML or OIDC Keycloak subsystem adapters into WildFly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not.
|
||||
These libraries are now only added to your deployment if you have Keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml)
|
||||
|
|
@ -882,9 +882,9 @@ Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycl
|
|||
To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/WildFly, Jetty 9), the Keycloak OIDC and SAML adapters will change the session id after login.
|
||||
You can turn off this behavior check adapter config switches.
|
||||
|
||||
==== SAML SP Client Adapter Changes
|
||||
==== SAML SP Client adapter Changes
|
||||
|
||||
Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP.
|
||||
Keycloak SAML SP Client adapter now requires a specific endpoint, `/saml` to be registered with your IDP.
|
||||
|
||||
=== Migrating to 1.8.0
|
||||
|
||||
|
|
@ -1115,7 +1115,7 @@ Facebook admin console).
|
|||
|
||||
=== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2
|
||||
|
||||
* Adapters are now a separate download. They are not included in appliance and war distribution. We have too many now and the distro
|
||||
* adapters are now a separate download. They are not included in appliance and war distribution. We have too many now and the distro
|
||||
is getting bloated.
|
||||
* `org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve`
|
||||
+`org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve`
|
||||
|
|
@ -1182,7 +1182,7 @@ Facebook admin console).
|
|||
AccessToken, AccessScope, KeycloakPrincipal, and KeycloakAuthenticatedSession respectively.
|
||||
* ServletOAuthClient.getBearerToken() method signature has changed. It now returns an AccessTokenResponse
|
||||
so that you can obtain a refresh token too.
|
||||
* Adapters now check the access token expiration with every request. If the token is expired, they will
|
||||
* adapters now check the access token expiration with every request. If the token is expired, they will
|
||||
attempt to invoke a refresh on the auth server using a saved refresh token.
|
||||
* Subject in AccessToken has been changed to the User ID.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[[intro]]
|
||||
|
||||
== Introduction
|
||||
== Upgrading Keycloak
|
||||
|
||||
This guide describes how to upgrade {project_name}. It is recommended that you start by upgrading the {project_name}
|
||||
server first and {project_name} adapters second.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ include::../migrate_db.adoc[leveloffset=1]
|
|||
include::../migrate_themes.adoc[leveloffset=1]
|
||||
|
||||
|
||||
== Upgrading {project_name} Adapters
|
||||
== Upgrading {project_name} adapters
|
||||
|
||||
include::../upgrade_adapters.adoc[leveloffset=1]
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
[[_migrate_db]]
|
||||
|
||||
== Migrating the Database
|
||||
== Database migration
|
||||
|
||||
{project_name} can automatically migrate the database schema, or you can choose to do it manually. By default the
|
||||
database is automatically migrated when you start the new installation for the first time.
|
||||
|
||||
=== Automatic Relational Database Migration
|
||||
=== Automatic relational database migration
|
||||
|
||||
To enable automatic upgrading of the database schema, set the migrationStrategy property value to "update" for the
|
||||
default connectionsJpa provider:
|
||||
|
|
@ -60,7 +60,7 @@ Or run this CLI command:
|
|||
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)
|
||||
----
|
||||
|
||||
=== Manual Relational Database Migration
|
||||
=== Manual relational database migration
|
||||
|
||||
To enable manual upgrading of the database schema, set the migrationStrategy property value to "manual" for the default
|
||||
connectionsJpa provider:
|
||||
|
|
@ -87,4 +87,5 @@ Or run this CLI command:
|
|||
When you start the server with this configuration it checks if the database needs to be migrated. The required changes
|
||||
are written to an SQL file that you can review and manually run against the database. For further details on how to
|
||||
apply this file to the database, see the documentation for the relational database you're using. After the changes have
|
||||
been written to the file, the server exits.
|
||||
been written to the file, the server exits.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[[_migrate_themes]]
|
||||
|
||||
== Migrating Themes
|
||||
== Theme migration
|
||||
|
||||
If you have created any custom themes they must be migrated to the new server. Any changes to the built-in themes might
|
||||
need to be reflected in your custom themes, depending on which aspects you have customized.
|
||||
|
|
@ -24,7 +24,7 @@ include::rhsso/migrate_themes-changes-72.adoc[leveloffset=0]
|
|||
include::rhsso/migrate_themes-changes-71.adoc[leveloffset=0]
|
||||
endif::[]
|
||||
|
||||
=== Migrating Templates
|
||||
=== Migrating templates
|
||||
|
||||
If you have customized any of the templates you need to carefully review the changes that have been made to the templates
|
||||
to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same
|
||||
|
|
@ -54,7 +54,7 @@ From this comparison it is easy to identify what has been changed in the base te
|
|||
make the same changes to your modified template. Since this approach is not as simple as the first approach, only use
|
||||
this approach if the first one is not feasible.
|
||||
|
||||
=== Migrating Messages
|
||||
=== Migrating messages
|
||||
|
||||
If you have added support for another language, you need to apply all the changes listed above. If you have not added
|
||||
support for another language, you might not need to change anything; you only have to make changes if you have changed
|
||||
|
|
@ -66,7 +66,7 @@ For renamed keys, rename the key in your custom theme.
|
|||
|
||||
For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.
|
||||
|
||||
=== Migrating Styles
|
||||
=== Migrating styles
|
||||
|
||||
If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect
|
||||
changes made to the styles from the built-in themes.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[[_prep_migration]]
|
||||
|
||||
== Preparing for Upgrading
|
||||
== Preparing for upgrading
|
||||
|
||||
Before you upgrade, be aware of the order in which you need to perform the upgrade steps. Also note potential issues
|
||||
that can occur within the upgrade process. In general, you must upgrade {project_name} server first, and then upgrade
|
||||
|
|
@ -11,7 +11,10 @@ the adapters.
|
|||
In a minor upgrade of {project_name}, all user sessions are lost. After the upgrade, all users will have to log in again.
|
||||
====
|
||||
|
||||
. Prior to applying the upgrade, handle any open transactions and delete the data/tx-object-store/ transaction directory.
|
||||
.Prerequisites
|
||||
* Prior to applying the upgrade, handle any open transactions and delete the data/tx-object-store/ transaction directory.
|
||||
|
||||
.Procedure
|
||||
. Back up the old installation (configuration, themes, and so on).
|
||||
. Back up the database. For detailed information on how to back up the database, see the documentation for the relational
|
||||
database you are using.
|
||||
|
|
@ -22,4 +25,3 @@ In a minor upgrade of {project_name}, all user sessions are lost. After the upgr
|
|||
* Ensure the upgraded server is functional before upgrading adapters in production.
|
||||
. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy.
|
||||
. Upgrade the adapters.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,23 +2,23 @@
|
|||
|
||||
The following changes have occurred from RH-SSO 7.0 to RH-SSO 7.1.
|
||||
|
||||
=== Realm Keys
|
||||
=== Realm keys
|
||||
For RH-SSO 7.0, only one set of keys could be associated with a realm. This meant that when changing the keys, all current cookies and tokens would be invalidated and all users would have to re-authenticate. For RH-SSO 7.1, support for multiple keys for one realm has been added. At any given time, one set of keys is the active set used for creating signatures, but there can be multiple keys used to verify signatures. This means that old cookies and tokens can be verified, then refreshed with the new signatures, allowing users to remain authenticated when keys are changed. There are also some changes to how keys are managed through the Admin Console and Admin REST API; for more details see link:{adminguide_link}#realm_keys[Realm Keys] in the {adminguide_name}.
|
||||
|
||||
To allow seamless key rotation you must remove hard-coded keys from client adapters. The client adapters will automatically retrieve keys from the server as long as the realm key is not specified. Client adapters will also retrieve new keys automatically when keys are rotated.
|
||||
|
||||
=== Client Redirect URI Matching
|
||||
=== Client redirect URI matching
|
||||
For RH-SSO 7.0, query parameters are ignored when matching valid redirect URIs for a client. For RH-SSO 7.1, query parameters are no longer ignored. If you need to include query parameters in the redirect URI you must specify the query parameters in the valid redirect URI for the client (for example, \https://hostname/app/login?foo=bar) or use a wildcard (for example, \https://hostname/app/login/*). Fragments are also no longer permitted in Valid Redirect URIs (that is, \https://hostname/app#fragment).
|
||||
|
||||
=== Automatically Redirect to Identity Provider
|
||||
=== Automatically redirect to Identity Provider
|
||||
For RH-SSO 7.1, identity providers cannot be set as the default authentication provider. To automatically redirect to an identity provider for RH-SSO 7.1, you must now configure the identity provider redirector. For more information see link:{adminguide_link}#default_identity_provider[Default Identity Provider] in the _{adminguide_name}_. If you previously had an identity provider with the default authentication provider option set, this value is automatically used as the value for the identity provider redirector when the server is upgraded to RH-SSO 7.1.
|
||||
|
||||
=== Admin REST API
|
||||
For RH-SSO 7.0, paginated endpoints in the Admin REST API return all results if the maxResults query parameter was not specified. This could cause issues with a temporary high load and requests timing out when a large number of results were returned (for example, users). For RH-SSO 7.1, a maximum of 100 results are returned if a value for maxResults is not specified. You can return all results by specifying maxResults as -1.
|
||||
|
||||
=== Server Configuration
|
||||
=== Server configuration
|
||||
For RH-SSO 7.0, server configuration is split between the keycloak-server.json file and the standalone/domain.xml or domain.xml file. For RH-SSO 7.1, the keycloak-server.json file has been removed and all server configuration is done through the standalone.xml or domain.xml file. The upgrading procedure for RH-SSO 7.1 automatically migrates the server configuration from the keycloak-server.json file to the standalone.xml or domain.xml file.
|
||||
|
||||
=== Key Encryption Algorithm in SAML Assertions
|
||||
=== Key encryption algorithm in SAML assertions
|
||||
For RH-SSO 7.1, keys in SAML assertions and documents are now encrypted using the RSA-OAEP encryption scheme. To use encrypted assertions, ensure your service providers support this encryption scheme. In the event that you have service providers that do not support RSA-OAEP, RH-SSO can be configured to use the legacy RSA-v1.5 encryption scheme by starting the server with the system property "keycloak.saml.key_trans.rsa_v1.5" set to true. If you do this, you should upgrade your service providers as soon as possible to be able to revert to the more secure RSA-OAEP encryption scheme.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
The following changes have occurred from RH-SSO 7.1 to RH-SSO 7.2.
|
||||
|
||||
=== New Password Hashing algorithms
|
||||
=== New password hashing algorithms
|
||||
|
||||
We have added two new password hashing algorithms (pbkdf2-sha256 and pbkdf2-sha512). New realms will use the pbkdf2-sha256
|
||||
hashing algorithm with 27500 hashing iterations. Since pbkdf2-sha256 is slightly faster than pbkdf2 the iterations was
|
||||
|
|
@ -73,7 +73,7 @@ It is possible that you will need to adjust custom mappers for non-standard clai
|
|||
information endpoint and are provided under different name by Google Sign-in API. Please consult Google documentation
|
||||
for the most up-to-date information on available claims.
|
||||
|
||||
=== LinkedIn Social Broker Updated to Version 2 of LinkedIn APIs
|
||||
=== LinkedIn Social Broker updated to Version 2 of LinkedIn APIs
|
||||
|
||||
Accordingly with LinkedIn, all developers need to migrate to version 2.0 of their APIs and OAuth 2.0. As such, we have updated
|
||||
our LinkedIn Social Broker so if this integration is in use make sure you upgrade to {project_name} version 7.2.6 or later.
|
||||
|
|
@ -88,4 +88,5 @@ Even for newly created LinkedIn client applications, you need to make sure that
|
|||
Due to these privacy restrictions imposed by LinkedIn in regards to access to member's information and the limited set of claims returned by the
|
||||
current member's Profile API, the LinkedIn Social Broker
|
||||
is now using the member's email address as the default username. That means that the `r_emailaddress` is always set when
|
||||
sending authorization requests during the authentication.
|
||||
sending authorization requests during the authentication.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
The following changes have occurred from RH-SSO 7.2 to RH-SSO 7.3.
|
||||
|
||||
=== Changes to Authorization Services
|
||||
=== Changes to authorization services
|
||||
|
||||
We added support for UMA 2.0. This version of the UMA specification introduced some important changes on how permissions are obtained from the server.
|
||||
|
||||
|
|
@ -22,8 +22,8 @@ Entitlement API was removed::
|
|||
Changes to UMA Discovery Endpoint::
|
||||
UMA Discovery document changed, see link:{authorizationguide_link}#_service_authorization_api[{authorizationguide_name}] for details.
|
||||
|
||||
Changes to {project_name} Authorization JavaScript Adapter::
|
||||
The {project_name} Authorization JavaScript Adapter (keycloak-authz.js) changed in order to comply with the changes introduced by UMA 2.0 while keeping
|
||||
Changes to {project_name} Authorization JavaScript adapter::
|
||||
The {project_name} Authorization JavaScript adapter (keycloak-authz.js) changed in order to comply with the changes introduced by UMA 2.0 while keeping
|
||||
the same behavior as before. The main change is on how you invoke both `authorization` and `entitlement` methods which now
|
||||
expect a specific object type representing an authorization request. This new object type provides more flexibility on how
|
||||
permissions can be obtained from the server by supporting the different parameters supported by the UMA grant type.
|
||||
|
|
@ -116,7 +116,7 @@ set a fixed hostname which makes it easier to make sure the valid hostname is us
|
|||
applications to invoke {project_name} through an alternative URL, for example an internal IP address. It is
|
||||
recommended that you switch to this approach in production.
|
||||
|
||||
=== JavaScipt Adapter Promise
|
||||
=== JavaScript adapter promise
|
||||
|
||||
To use native JavaScript promise with the JavaScript adapter it is now required to set `promiseType` to `native` in the
|
||||
init options.
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ Read-only user attributes are now available. Some of these user attributes are
|
|||
|
||||
* Custom user storage providers
|
||||
* Custom authenticators
|
||||
* Custom Javascript authorization policies that establish authorization based on a user attribute
|
||||
* Custom JavaScript authorization policies that establish authorization based on a user attribute
|
||||
* X.509 authenticator with a 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 information.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[[intro]]
|
||||
|
||||
== Introduction
|
||||
== Upgrading Red Hat Single Sign-On
|
||||
|
||||
Red Hat Single Sign-On (RH-SSO) {project_versionDoc} is based on the Keycloak project and provides security for your web applications by
|
||||
providing Web single sign-on capabilities based on popular standards such as SAML 2.0, OpenID Connect, and OAuth 2.0.
|
||||
|
|
@ -16,22 +16,24 @@ implemented. Specific instructions for each mode are provided where applicable.
|
|||
The purpose of this guide is to document the steps that are required to successfully upgrade from
|
||||
Red Hat Single Sign-On 7.x to Red Hat Single Sign-On {project_versionDoc}.
|
||||
|
||||
=== About Upgrades
|
||||
=== About upgrades
|
||||
|
||||
==== Major Upgrades
|
||||
Depending on your version of RH-SSO, you choose one of three types of upgrade. However, if you starting from Keycloak, you choose xref:keycloak-migration[this procedure].
|
||||
|
||||
==== Major upgrades
|
||||
|
||||
A major upgrade or migration is required when RH-SSO is upgraded from one major release to another, for example, from
|
||||
Red Hat Single Sign-On 7.2 to Red Hat Single Sign-On 8.0. There may be breaking API changes between major releases
|
||||
that could require rewriting parts of applications or server extensions.
|
||||
|
||||
==== Minor Updates
|
||||
==== Minor updates
|
||||
|
||||
Red Hat Single Sign-On periodically provides point releases, which are minor updates that include bug fixes, security
|
||||
fixes, and new features. If you plan to upgrade from one Red Hat Single Sign-On point release to another, for example,
|
||||
from Red Hat Single Sign-On 7.3 to Red Hat Single Sign-On {project_versionDoc}, code changes should not be required for applications or
|
||||
custom server extensions as long as no private, unsupported, or tech preview APIs are used.
|
||||
|
||||
==== Micro Updates
|
||||
==== Micro updates
|
||||
|
||||
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
|
||||
|
|
@ -42,7 +44,8 @@ A micro release only contains the artifacts that have changed. For example if Re
|
|||
the server and the JavaScript adapter, but not the EAP adapter, only the server and JavaScript adapter are released and require
|
||||
updating.
|
||||
|
||||
=== Migration from Keycloak
|
||||
[id="keycloak-migration"]
|
||||
=== Migrating Keycloak to RH-SSO
|
||||
|
||||
You can migrate to Red Hat Single Sign-On, the supported Red Hat product, from Keycloak, the community project.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,10 +11,10 @@
|
|||
For a managed domain, the RH-SSO domain controller should be updated first.
|
||||
====
|
||||
|
||||
|
||||
To install a RH-SSO patch via RPM from your subscribed repository, update your Red Hat Enterprise Linux system using the following command:
|
||||
|
||||
[source,bash,options="nowrap"]
|
||||
----
|
||||
yum update
|
||||
----
|
||||
----
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[zip-patching]]
|
||||
= Patching a ZIP/Installer Installation
|
||||
= ZIP/installer installation patching
|
||||
|
||||
Patches for a ZIP installation of RH-SSO are available to download from the
|
||||
link:https://access.redhat.com/[Red Hat Customer Portal].
|
||||
|
|
@ -8,23 +8,23 @@ For multiple RH-SSO hosts in a managed domain environment, individual hosts can
|
|||
|
||||
In addition to applying a patch, you can also roll back the application of a patch.
|
||||
|
||||
== Important Notes on ZIP Installation Patching
|
||||
== Important notes on ZIP installation patching
|
||||
|
||||
* If you apply a patch that updates a module, the new patched JARs that are used at runtime are stored in `RHSSO_HOME/modules/system/layers/base/.overlays/_PATCH_ID_/_MODULE_`. The original unpatched files are left in `RHSSO_HOME/modules/system/layers/base/_MODULE_`, but these JARs are *not* used at runtime.
|
||||
* In order to significantly decrease the size of cumulative patch releases for RH-SSO 7 you cannot perform a partial roll back of a cumulative patch. For a patch that has been applied, you will only be able to roll back the whole patch.
|
||||
+
|
||||
For example, if you apply CP03 to RH-SSO 7.0.0, you will not be able to roll back to CP01 or CP02. If you would like the ability to roll back to each cumulative patch release, each cumulative patch must be applied separately in the order they were released.
|
||||
|
||||
== Applying a Patch
|
||||
== Applying a patch
|
||||
|
||||
NOTE: RH-SSO servers that have been installed using the RPM method cannot be updated using these instructions. See the xref:rpm-patching[RPM instructions for applying a patch] instead.
|
||||
|
||||
|
||||
You can apply downloaded patches to a RH-SSO server using either the xref:zip_patching_management_cli[management CLI] or the xref:zip_patching_management_console[management console].
|
||||
|
||||
[[zip_patching_management_cli]]
|
||||
.Applying a Patch to RH-SSO Using the Management CLI
|
||||
.Applying a patch to RH-SSO using the management CLI
|
||||
|
||||
.Procedure
|
||||
. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.
|
||||
|
||||
. From the link:{appserver_managementcli_link}[management CLI], apply the patch using the following command, including the appropriate path to the patch file:
|
||||
|
|
@ -54,7 +54,10 @@ shutdown --restart=true
|
|||
----
|
||||
|
||||
[[zip_patching_management_console]]
|
||||
.Applying a Patch to RH-SSO Using the Management Console
|
||||
.Applying a patch to RH-SSO using the Management Console
|
||||
|
||||
.Procedure
|
||||
|
||||
. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.
|
||||
. Open the link:{appserver_managementconsole_link}[management console] and navigate to the *Patch Management* view.
|
||||
.. For a standalone server, click the *Patching* tab.
|
||||
|
|
@ -77,7 +80,7 @@ image:images/patching-select-patch.png[Apply Patch Screen]
|
|||
|
||||
. After the patch has been successfully applied, select whether to restart RH-SSO now for the patch to take effect, and click *Finish*.
|
||||
|
||||
== Rolling Back a Patch
|
||||
== Rolling back a patch
|
||||
|
||||
You can roll back a previously applied RH-SSO patch using either the xref:zip_rollback_management_cli[management CLI] or the xref:zip_rollback_management_console[management console].
|
||||
|
||||
|
|
@ -97,6 +100,9 @@ If set to `FALSE`, the server configuration files will not be rolled back. In th
|
|||
|
||||
[[zip_rollback_management_cli]]
|
||||
.Rolling Back a Patch Using the Management CLI
|
||||
|
||||
.Procedure
|
||||
|
||||
. From the management CLI, use the `patch history` command to find the ID of the patch that you want to roll back.
|
||||
+
|
||||
--
|
||||
|
|
@ -120,7 +126,9 @@ shutdown --restart=true
|
|||
----
|
||||
|
||||
[[zip_rollback_management_console]]
|
||||
.Rolling Back a Patch Using the Management Console
|
||||
.Rolling back a patch using the Management Console
|
||||
|
||||
.Procedure
|
||||
. Open the management console and navigate to the *Patch Management* view.
|
||||
.. For a standalone server, click the *Patching* tab.
|
||||
.. For a server in a managed domain, click the *Patching* tab, then select the host that you want to patch from the table, and click *View*.
|
||||
|
|
@ -141,7 +149,7 @@ image:images/patching-rollback-options.png[Patch Rollback Options]
|
|||
|
||||
. 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*.
|
||||
|
||||
== Clearing Patch History
|
||||
== Clearing patch history
|
||||
|
||||
When patches are applied to a RH-SSO server, the content and history of the patches are preserved for use in rollback operations. If multiple cumulative patches are applied, the patch history may use a significant amount of disk space.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,10 @@
|
|||
[[_patching_js_adapter]]
|
||||
==== Patching the JavaScript Adapter
|
||||
==== Patching the JavaScript adapter
|
||||
|
||||
There are no patching mechanism available for the JavaScript adapter and this is distributed as a complete new download.
|
||||
|
||||
.Procedure
|
||||
|
||||
To upgrade a JavaScript adapter that has been copied to your web application, complete the following steps:
|
||||
|
||||
. Download the new archive.
|
||||
|
|
@ -9,9 +12,11 @@ To upgrade a JavaScript adapter that has been copied to your web application, co
|
|||
|
||||
|
||||
[[_patching_nodejs_adapter]]
|
||||
==== Patching the Node.js Adapter
|
||||
==== Patching the Node.js adapter
|
||||
|
||||
There are no patching mechanism available for the Node.js adapter and this is distributed as a complete new download.
|
||||
|
||||
.Procedure
|
||||
To upgrade a Node.js adapter that has been copied to your web application, complete the following steps:
|
||||
|
||||
. Download the new archive.
|
||||
|
|
|
|||
|
|
@ -1,21 +1,23 @@
|
|||
[[_patching_local_maven]]
|
||||
= Patching a local Maven installation
|
||||
|
||||
If you have installed the RH-SSO Client Adapters Maven Repository using a ZIP file downloaded from the link:https://access.redhat.com/[Red Hat Customer Portal], it may also need to be patched.
|
||||
If you have installed the RH-SSO Client adapters Maven Repository using a ZIP file downloaded from the link:https://access.redhat.com/[Red Hat Customer Portal], it may also need to be patched.
|
||||
|
||||
The RH-SSO Client Adapters Maven Repository is available online or as a downloaded ZIP file. If you use the publicly hosted online Maven repository, updates are automatically applied, and no action is required to update it. However, if you installed the Maven repository locally using the ZIP file, you are responsible for applying updates to the repository.
|
||||
The RH-SSO Client adapters Maven Repository is available online or as a downloaded ZIP file. If you use the publicly hosted online Maven repository, updates are automatically applied, and no action is required to update it. However, if you installed the Maven repository locally using the ZIP file, you are responsible for applying updates to the repository.
|
||||
|
||||
Whenever a cumulative patch is released for RH-SSO, a corresponding patch is provided for the RH-SSO Client Adapters Maven Repository. This patch is available in the form of an incremental ZIP file that is unzipped into the existing local repository. It does not overwrite or remove any existing files, so there is no rollback requirement.
|
||||
Whenever a cumulative patch is released for RH-SSO, a corresponding patch is provided for the RH-SSO Client adapters Maven Repository. This patch is available in the form of an incremental ZIP file that is unzipped into the existing local repository. It does not overwrite or remove any existing files, so there is no rollback requirement.
|
||||
|
||||
Use the following procedure to apply updates to your locally installed RH-SSO Client Adapters Maven Repository.
|
||||
Use the following procedure to apply updates to your locally installed RH-SSO Client adapters Maven Repository.
|
||||
|
||||
== Prerequisites
|
||||
== Updating a locally installed RH-SSO client adapters maven repository
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* Valid access and subscription to the Red Hat Customer Portal.
|
||||
|
||||
* The RH-SSO Client Adapters Maven Repository, previously downloaded and installed locally.
|
||||
* The RH-SSO Client adapters Maven Repository, previously downloaded and installed locally.
|
||||
|
||||
== Update a locally installed RH-SSO Client Adapters Maven Repository
|
||||
.Procedure
|
||||
|
||||
. Open a browser and log into the link:https://access.redhat.com/[Red Hat Customer Portal].
|
||||
|
||||
|
|
@ -25,9 +27,9 @@ Use the following procedure to apply updates to your locally installed RH-SSO Cl
|
|||
|
||||
. Select the correct version of Red Hat Single Sign-On from the Version drop-down menu, then select the *Patches* tab.
|
||||
|
||||
. Find `Red Hat Single Sign-On 7.x.y Client Adapters Incremental Maven Repository` from the list, where `x.y` match the cumulative patch number you want to update to. Select *Download*.
|
||||
. Find `Red Hat Single Sign-On 7.x.y Client adapters Incremental Maven Repository` from the list, where `x.y` match the cumulative patch number you want to update to. Select *Download*.
|
||||
|
||||
. Locate the path to your RH-SSO Client Adapters Maven Repository. This is referred to in the commands below as `RH-SSO_MAVEN_REPOSITORY_PATH`. Unzip the downloaded Maven patch file directly into this directory, like this:
|
||||
. Locate the path to your RH-SSO Client adapters Maven Repository. This is referred to in the commands below as `RH-SSO_MAVEN_REPOSITORY_PATH`. Unzip the downloaded Maven patch file directly into this directory, like this:
|
||||
|
||||
.. For Red Hat Enterprise Linux, open a terminal and run the following command, replacing the values for the cumulative patch number and your Maven repository path:
|
||||
+
|
||||
|
|
@ -36,4 +38,5 @@ $ unzip -o rh-sso-7.x.y-incremental-maven-repository.zip -d RH-SSO_MAVEN_REPOSI
|
|||
```
|
||||
+
|
||||
|
||||
.. For Microsoft Windows, use the Windows extraction utility to extract the ZIP file into the root of the `RH-SSO_MAVEN_REPOSITORY_PATH` directory.
|
||||
.. For Microsoft Windows, use the Windows extraction utility to extract the ZIP file into the root of the `RH-SSO_MAVEN_REPOSITORY_PATH` directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[[_upgrading]]
|
||||
|
||||
== Upgrading {project_name} Server
|
||||
== Upgrading the {project_name} server
|
||||
|
||||
The upgrade or migration process for the {project_name} server depends on the previous version of the software.
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ The upgrade or migration process for the {project_name} server depends on the pr
|
|||
* If you are upgrading to a new micro release, for example from 7.1.0 to 7.1.1, follow the steps in xref:_upgrading_micro[Micro Upgrades].
|
||||
|
||||
[[_upgrading_minor]]
|
||||
=== Minor Upgrades
|
||||
=== Performing a minor upgrade
|
||||
|
||||
include::../prep_migration.adoc[leveloffset=2]
|
||||
|
||||
|
|
@ -22,12 +22,11 @@ include::../migrate_db.adoc[leveloffset=2]
|
|||
include::../migrate_themes.adoc[leveloffset=2]
|
||||
|
||||
[[_upgrading_micro]]
|
||||
=== Micro Upgrades
|
||||
=== Performing a micro upgrade
|
||||
|
||||
include::patching-zip-installation.adoc[leveloffset=3]
|
||||
include::patching-rpm-installation.adoc[leveloffset=3]
|
||||
include::patching_maven_repo.adoc[leveloffset=3]
|
||||
include::patching-rpm-installation.adoc[leveloffset=3]include::patching_maven_repo.adoc[leveloffset=3]
|
||||
|
||||
== Upgrading {project_name} Adapters
|
||||
== Upgrading {project_name} adapters
|
||||
|
||||
include::../upgrade_adapters.adoc[leveloffset=1]
|
||||
|
|
|
|||
|
|
@ -16,18 +16,19 @@ In those cases, we added Compatibility modes. For OpenId Connect clients, there
|
|||
in the {project_name} admin console, on the page with client details. Here, you can disable some new aspects of the {project_name} server
|
||||
to preserve compatibility with older client adapters. More details are available in the tool tips of individual switches.
|
||||
|
||||
|
||||
[[_upgrade_eap_adapter]]
|
||||
== Upgrading the EAP Adapter
|
||||
== Upgrading the EAP adapter
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
|
||||
If you originally installed the adapter using a downloaded archive, to upgrade the {appserver_name} adapter, complete the following steps:
|
||||
.Procedure
|
||||
If you originally installed the adapter using a downloaded archive, to upgrade the {appserver_name} adapter, perform the following procedure.
|
||||
|
||||
. Download the new adapter archive.
|
||||
. Remove the previous adapter modules by deleting the `{appserver_dirref}/modules/system/add-ons/keycloak/` directory.
|
||||
. Unzip the downloaded archive into {appserver_dirref}.
|
||||
|
||||
.Procedure
|
||||
If you originally installed the adapter using RPM, to upgrade the adapter, complete the following steps, which are different depending on whether you are performing a minor or a micro upgrade:
|
||||
|
||||
. For minor upgrades, use Yum to uninstall any adapters you currently have installed and then use Yum to install the new version of the adapters.
|
||||
|
|
@ -42,6 +43,7 @@ endif::[]
|
|||
|
||||
ifeval::[{project_community}==true]
|
||||
|
||||
.Procedure
|
||||
To upgrade the {appserver_name} adapter, complete the following steps:
|
||||
|
||||
. Download the new adapter archive.
|
||||
|
|
@ -51,19 +53,21 @@ To upgrade the {appserver_name} adapter, complete the following steps:
|
|||
endif::[]
|
||||
|
||||
[[_upgrade_js_adapter]]
|
||||
== Upgrading the JavaScript Adapter
|
||||
== Upgrading the JavaScript adapter
|
||||
|
||||
To upgrade a JavaScript adapter that has been copied to your web application, complete the following steps:
|
||||
To upgrade a JavaScript adapter that has been copied to your web application, perform the following procedure.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Download the new adapter archive.
|
||||
. Overwrite the keycloak.js file in your application with the keycloak.js file from the downloaded archive.
|
||||
|
||||
|
||||
[[_upgrade_nodejs_adapter]]
|
||||
== Upgrading the Node.js Adapter
|
||||
== Upgrading the Node.js adapter
|
||||
|
||||
To upgrade a Node.js adapter that has been copied to your web application, complete the following steps:
|
||||
To upgrade a Node.js adapter that has been copied to your web application, perform the following procedure.
|
||||
|
||||
.Procedure
|
||||
. Download the new adapter archive.
|
||||
. Remove the existing Node.js adapter directory
|
||||
. Unzip the updated file into its place
|
||||
|
|
|
|||
Loading…
Reference in a new issue