업그레이드 가이드

RH-SSO를 하나의 주요 릴리스에서 다른 릴리스로 업그레이드할 때 주요 업그레이드 또는 마이그레이션이 필요합니다(예: Red Hat Single Sign-On 7.2에서 Red Hat Single Sign-On 8.0으로 업그레이드). 애플리케이션 또는 서버 확장의 일부를 다시 작성해야 할 수 있는 주요 릴리스 간에 API 변경 사항이 중단될 수 있습니다.

Red Hat Single Sign-On은 버그 수정, 보안 수정 및 새로운 기능을 포함하는 마이너 업데이트인 포인트 릴리스를 주기적으로 제공합니다. 하나의 Red Hat Single Sign-On 포인트 릴리스에서 다른 릴리스로 업그레이드하려는 경우 (예: Red Hat Single Sign-On 7.3에서 Red Hat Single Sign-On 7.6로) Red Hat Single Sign-On 7.6으로 업그레이드하려는 경우 프라이빗, 지원되지 않거나 기술 프리뷰 API를 사용하지 않는 한 애플리케이션 또는 사용자 지정 서버 확장에는 코드 변경이 필요하지 않아야 합니다.

Red Hat Single Sign-On 7.6에서는 버그 및 보안 수정 사항이 포함된 마이크로 릴리스도 주기적으로 제공합니다. 마이크로 릴리스는 마이너 릴리스 버전을 마지막 숫자 (예: 7.6.0에서 7.6.1)로 증가시킵니다. 이러한 릴리스에서는 마이그레이션이 필요하지 않으며 서버 구성 파일에 영향을 미치지 않습니다. ZIP 설치를 위한 패치 관리 시스템은 패치 및 서버 구성을 롤백할 수도 있습니다.

마이크로 릴리스에는 변경된 아티팩트만 포함됩니다. 예를 들어 Red Hat Single Sign-On 7.6.1에 서버 및 JavaScript 어댑터에 대한 변경 사항이 포함되어 있지만 EAP 어댑터가 아닌 경우 서버 및 JavaScript 어댑터만 릴리스되고 업데이트해야 합니다.

단계별 인증은 새로운 기능입니다. 이 기능은 토큰에 acr 클레임을 추가해야 하는 프로토콜 매퍼가 포함된 acr 클라이언트 범위를 제공합니다. acr 클레임은 이 버전 이전과 마찬가지로 자동으로 추가되지 않지만 이 클라이언트 범위 및 프로토콜 매퍼를 사용하여 추가됩니다.

클라이언트 범위는 realm "default" 클라이언트 범위로 추가되므로 새로 생성된 모든 클라이언트에 추가됩니다. 성능상의 이유로 마이그레이션 중에 클라이언트 범위가 기존의 모든 클라이언트에 자동으로 추가되지 않습니다. 클라이언트는 마이그레이션 후 기본적으로 acr 클레임이 없습니다. 다음과 같은 가능한 작업을 고려하십시오.

insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE
from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect';

insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE
from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect';

이전 버전의 Red Hat Single Sign-On은 http(s)://example-host/auth/realms/my-realm-name/openid-connect/logout?redirect_uri=encodedRedirectUri와 같은 로그 아웃 끝점 URL을 열어 사용자의 자동 로그 아웃 및 리디렉션을 지원했습니다. 이러한 구현을 사용하기 쉽지만 성능과 보안에 잠재적으로 부정적인 영향을 미칠 수 있었습니다. 새 버전은 OpenID Connect RP-Initiated Logout 사양을 기반으로 logout을 더 잘 지원합니다. parameter redirect_uri 는 더 이상 지원되지 않습니다. 새 버전에서는 사용자가 로그아웃을 확인해야 합니다. 로그인에 사용되는 ID 토큰과 id_token_hint 매개변수와 함께 매개 변수 post_logout_redirect_uri 매개 변수를 포함하는 경우 확인을 생략하고 애플리케이션에 자동 리디렉션을 수행할 수 있습니다.

기존 배포는 다음과 같은 방식으로 영향을 받습니다.

이전 버전과의 호환성 옵션이 있으므로 애플리케이션이 여전히 이전 형식의 redirect_uri 매개변수를 사용할 수 있습니다.

standalone-*.xml 파일에 다음 구성을 포함하여 이 매개변수를 활성화할 수 있습니다.

<spi name="login-protocol">
    <provider name="openid-connect" enabled="true">
        <properties>
            <property name="legacy-logout-redirect-uri" value="true"/>
        </properties>
    </provider>
</spi>

<spi name="login-protocol">
    <provider name="openid-connect" enabled="true">
        <properties>
            <property name="legacy-logout-redirect-uri" value="true"/>
        </properties>
    </provider>
</spi>

이 구성을 사용하면 여전히 redirect_uri 매개변수와 함께 형식을 사용할 수 있습니다. id_token_hint 가 생략된 경우 확인 화면이 필요합니다.

이전 버전의 Red Hat Single Sign-On은 관리 콘솔 및 REST API와 같은 관리 인터페이스를 통해 JavaScript 코드 관리를 지원했습니다. 이 버전에서 시작하는 경우 더 이상 사용할 수 없으며 다음 공급자를 구성하기 위해 서버에 스크립트를 배포해야 합니다.

서버에 스크립트를 배포하는 방법에 대한 자세한 내용은 설명서에서 확인할 수 있습니다. 스크립트를 사용하려면 스크립트 기술 프리뷰 기능을 활성화해야 합니다.

./standalone.sh -Dkeycloak.profile=preview

./standalone.sh -Dkeycloak.profile=preview

스크립트를 배포할 때 서버는 인증 흐름, 매퍼 및 권한 부여 정책을 구성할 때 선택할 수 있도록 해당 공급자를 자동으로 생성합니다.

일반적으로 영역을 업데이트하는 단계는 다음과 같습니다.

Patternfly (PF) React 라이브러리가 업데이트되었으며, @patternfly/react-core from v3.153.3에서 v4.147.0, @patternfly/react-icons from v3.15.16에서 v 4.11.8로, @patternfly/react-styles 가 v4.11.8로 업데이트되었습니다. 계정 콘솔을 PF 설계 표준과 일치하도록 몇 가지 사소한 UI가 업데이트되었습니다.

PF의 중단으로 인해 사용자 정의 개발 계정 UI가 이러한 업데이트와 호환되지 않을 수 있습니다. 대부분의 변경 사항은 PF 구성 요소에 대한 props를 업데이트하여 재배치할 수 있어야 합니다.

resources:

변경 사항이 있는 것으로 알려진 구성 요소:

클라이언트 범위 조건을 포함하여 정책을 사용하고 JSON 문서를 직접 편집한 경우 JSON 문서의 "범위" 필드 이름을 "범위"로 변경해야 합니다.

Liquibase는 버전 3.5.5에서 4.6.2로 업데이트되었습니다. 여기에는 ServiceLoader 를 사용하여 사용자 정의 확장을 등록하는 새로운 방법이 포함되어 있습니다.

업그레이드 전에 기존 데이터베이스를 백업하는 등 업그레이드 가이드에 대해 자세히 따르십시오. Liquibase 업그레이드의 결과를 테스트하기 위해 최선을 다했지만 일부 설치에서는 알 수 없는 특정 설정을 사용할 수 있습니다.

이번 릴리스에서는 Red Hat Single Sign-On Operator의 Keycloak CR에 더 이상 사용되지 않는 podDisruptionBudget 필드가 있습니다. 이 선택적 필드는 Operator가 OCP 4.12 이상 버전에 배포되면 무시됩니다.

이 문제를 해결하려면 클러스터에서 Pod 중단 예산을 수동으로 생성할 수 있습니다. 예를 들면 다음과 같습니다.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  labels:
    app: keycloak
  name: keycloak
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      component: keycloak

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  labels:
    app: keycloak
  name: keycloak
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      component: keycloak

Kubernetes 문서 도 참조하십시오.

이전 버전의 Operator에 도입된 중요한 버그로 인해 RH-SSO StatefulSet의 Selector 필드가 잘못 구성되었습니다. 잘못된 구성로 인해 업그레이드 프로세스가 7.5에서 7.6로 중단되어 RH-SSO 배포가 성공할 수 있습니다.

Operator 패치 릴리스를 통해 수정 사항이 추가되었습니다. 수정의 일환으로 Operator는 7.5에서 7.6로 업그레이드하는 동안 RH-SSO StatefulSet을 삭제하고 다시 생성할 수 있습니다. 수정 사항이 제대로 작동하려면 재현 업그레이드 전략을 사용해야 합니다. 서버 설치 및 구성 가이드의 관련 장을 참조하십시오.

Red Hat Single Sign-On OpenShift 이미지의 변경 사항에 맞게 7.6.2에 도입된 OpenShift 이미지의 변경 사항에 맞게 Operator는 이제 사용자 정의 이미지를 사용하는 대신 이미지에 있는 기본 활성 및 준비 상태 프로브를 활용합니다. 기존 Red Hat Single Sign-On 배포의 경우 Operator는 업그레이드하는 동안 프로브를 자동으로 업데이트합니다. 그러나 keycloak-probes ConfigMap에 대한 수동 변경을 수행하여 프로브를 사용자 지정한 경우 Operator는 사용자 수정 사항을 재정의하지 않도록 프로브를 업데이트하지 않습니다. 이 경우 프로브를 수동으로 업데이트하거나 Operator를 다시 생성하려면 ConfigMap을 삭제해야 합니다. 그러지 않으면 업그레이드된 Red Hat Single Sign-On 7.6.2 배포가 준비되지 않은 상태로 표시됩니다.

FIPS가 활성화된 환경에서 실행할 수 있도록 프로브 인증 해시 알고리즘이 변경되었습니다. 프로브에 대한 기본 시간 초과가 1초이고 CPU 제한을 1보다 적게 지정하는 템플릿 기반 설치의 경우 프로브 오류가 발생할 수 있습니다. 이러한 실패가 다시 시작되면 DeploymentConfig를 변경하거나 새로 릴리스된 템플릿을 재지정하여 프로브 시간 초과를 늘려야 합니다. 이로 인해 Operator에서 사용되는 것과 일치하는 시간 초과 값이 더 많습니다.

단계별 인증과 관련하여 계정 콘솔 V1에 대한 제한 사항이 있습니다. 문제는 사용자가 암호를 사용하여 계정 콘솔 버전 1에 인증한 다음 TOTP 인증 정보를 사용자에게 추가하거나 기존 TOTP 인증 정보를 제거할 수 있다는 것입니다. 이는 사용자의 암호를 훔치기 위해 관리하는 모든 사람이 다른 TOTP를 추가하여 사용자의 두 번째 요인 인증을 우회할 수 있음을 의미합니다. 계정 콘솔 버전 2에서는 이 문제가 발생하지 않습니다(Red Hat Single Sign-On 7.6.8)에서 지원합니다. 해당 버전은 항상 사용자를 적용하여 사용자를 추가 또는 제거할 해당 수준의 자격 증명으로 인증합니다.

최상의 완화 방법은 단계별 인증을 사용할 때 계정 콘솔 버전 1을 사용하지 않는 것입니다. 계정 테마가 keycloak 테마로 명시적으로 전환되면 계정 콘솔 버전 1이 작동합니다.

PUT /admin/realms/{realm}/users/{id}/send-verify-email

PUT /admin/realms/{realm}/users/{id}/send-verify-email

이번 릴리스에서는 API에서 executeActions.ftl 대신 email-verification.ftl 템플릿을 사용합니다.

Perform the following action(s): Verify Email

Perform the following action(s): Verify Email

Confirm validity of e-mail address email@example.org.

Confirm validity of e-mail address email@example.org.

executeActions.ftl 템플릿을 사용자 지정하여 사용자가 이 API를 사용하여 이메일을 확인하는 방법을 수정한 경우 새 템플릿으로 수정 사항을 전송해야 합니다.

기본 라이프사이클 값(12시간)을 재정의할 수 있도록 lifespan 이라는 새 매개변수가 도입됩니다.

이전 동작을 선호하는 경우 다음과 같이 execute-actions-email API를 사용합니다.

PUT /admin/realms/{realm}/users/{id}/execute-actions-email
["VERIFY_EMAIL"]

PUT /admin/realms/{realm}/users/{id}/execute-actions-email
["VERIFY_EMAIL"]

Red Hat Single Sign-On 서버가 EAP 7.4를 기본 컨테이너로 사용하도록 업그레이드되었습니다. 이 변경 사항은 특정 Red Hat Single Sign-On 서버 기능과 직접적인 관련이 없지만 마이그레이션과 관련하여 몇 가지 변경 사항이 있습니다.

<extension module="org.wildfly.extension.microprofile.config-smallrye"/>
<extension module="org.wildfly.extension.microprofile.health-smallrye"/>
<extension module="org.wildfly.extension.microprofile.metrics-smallrye"/>

<extension module="org.wildfly.extension.microprofile.config-smallrye"/>
<extension module="org.wildfly.extension.microprofile.health-smallrye"/>
<extension module="org.wildfly.extension.microprofile.metrics-smallrye"/>

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"/>
<subsystem xmlns="urn:wildfly:microprofile-health-smallrye:2.0" security-enabled="false" empty-liveness-checks-status="${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" empty-readiness-checks-status="${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"/>
<subsystem xmlns="urn:wildfly:microprofile-metrics-smallrye:2.0" security-enabled="false" exposed-subsystems="*" prefix="${wildfly.metrics.prefix:wildfly}"/>

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"/>
<subsystem xmlns="urn:wildfly:microprofile-health-smallrye:2.0" security-enabled="false" empty-liveness-checks-status="${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" empty-readiness-checks-status="${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"/>
<subsystem xmlns="urn:wildfly:microprofile-metrics-smallrye:2.0" security-enabled="false" exposed-subsystems="*" prefix="${wildfly.metrics.prefix:wildfly}"/>

UserModel 에는 이제 사용자 지정 속성으로 변환되는 특정 필드, 사용자 이름 ,email,firstName 및 lastName 이 포함됩니다. 이러한 변경으로 인해 향후 버전에서 Red Hat Single Sign-On에 보다 정교한 사용자 프로필을 추가할 준비가 되었습니다.

이 경우 사용자 이름도 UserModel.getFirstAttribute(UserModel.USERNAME) 로 액세스하여 설정할 수 있습니다. 다른 필드에도 비슷한 영향이 있습니다. UserModel 을 직접 또는 간접적으로 분류하는 SPI 구현자는 setUsername 과 setSingleAttribute(UserModel.USERNAME, …​) 간 동작이 일관되도록 해야 합니다.

정책 평가 기능의 사용자는 평가에서 속성 수를 사용하는 경우 정책을 조정해야 합니다. 이제 모든 사용자에게 기본적으로 4개의 새 속성이 있습니다.

UserModel 공개 API는 변경되지 않았습니다. 프런트 엔드 리소스 또는 사용자 데이터에 액세스하는 SPI에 대한 변경 사항은 필요하지 않습니다. 또한 데이터베이스는 아직 변경되지 않았습니다.

Red Hat Single Sign-On 로그인me 구성 요소가 PatternFly 4로 업그레이드되었습니다. 이전 PatternFly 3은 새로운 패턴과 동시에 실행되므로 PF3 구성 요소를 유지할 수 있습니다.

그러나 로그인 주제 설계에 대한 일부 변경이 수행되었습니다. 사용자 정의 로그인 주제를 새 버전으로 업그레이드하십시오. 필요한 변경 사항이 있는 예는 examples/themes/theme/sunrise 디렉토리에서 확인할 수 있습니다. 추가 설정이 필요하지 않습니다.

Grafana IdP는 이제 새 API를 사용합니다. 이전 레거시 API는 더 이상 사용되지 않습니다. 이 변경에는 새 API 인증 정보가 필요합니다. 자세한 내용은 서버 관리 가이드를 참조하십시오.

OpenSSL IdP를 사용하여 OpenSSL에 로그인하는 사용자의 경우 암호와 같은 다른 인증 방법이 필요합니다. 로그인하면 Red Hat Single Sign-On에서 OpenSSL 소셜 링크를 수동으로 업데이트하거나 새 계정을 만들 수 있습니다. 이 제한은 이전 API의 OpenSSL 사용자 ID가 새 API와 호환되지 않기 때문에 존재합니다. 그러나 새 API는 일시적으로 새 ID와 이전 사용자 ID를 모두 반환하여 마이그레이션을 허용합니다. Red Hat Single Sign-On은 사용자가 로그인하면 ID를 자동으로 마이그레이션합니다.

OpenID Connect 매개변수 request_uri 를 사용하는 경우 클라이언트에 SSRF 공격으로부터 보호하도록 Valid Request URI 가 구성되어 있어야 합니다.

클라이언트 세부 정보 페이지의 Admin Console 또는 admin REST API 또는 클라이언트 등록 API를 통해 이 기능을 구성할 수 있습니다. 유효한 요청 URI에는 특정 클라이언트에 허용되는 Request URI 값 목록이 포함되어야 합니다.

대신 Valid Redirect URI 옵션과 같은 와일드카드 또는 상대 경로를 사용할 수 있습니다. 그러나 보안상의 이유로 가능한 특정 값을 사용하는 것이 좋습니다.

이제 읽기 전용 사용자 속성을 사용할 수 있습니다. 이러한 사용자 속성 중 일부는 REST API로 사용자를 업데이트하거나 Red Hat Single Sign-On 사용자 인터페이스로 업데이트할 때 사용자 또는 관리자가 편집할 수 없습니다. 특히 다음 사항을 사용할 때 이러한 변경 사항이 중요합니다.

자세한 내용은 위협 모델 완화 장 을 참조하십시오.

Docker 프로토콜을 사용한 인증 후 사용자 세션이 생성되지 않습니다. 자세한 내용은 서버 관리 가이드를 참조하십시오.

이 Red Hat Single Sign-On 버전의 경우 OAuth2 Client Credentials Grant 엔드포인트는 기본적으로 새로 고침 토큰을 발행하지 않습니다. 이 동작은 OAuth2 사양과 일치합니다.

따라서 클라이언트 자격 증명 인증에 성공한 후 Red Hat Single Sign-On 서버 측에서 사용자 세션이 생성되지 않습니다. 결과적으로 성능 및 메모리 사용량이 향상됩니다. Client Credentials grant을 사용하는 클라이언트는 새로 고침 토큰 사용을 중지하고 대신 refresh_token 을 부여 유형으로 사용하는 대신 grant_type=client_credentials 로 모든 요청에서 인증하는 것이 좋습니다.

이와 관련하여 Red Hat Single Sign-On은 OAuth2 해지 끝점에서 액세스 토큰 해지를 지원합니다. 따라서 필요한 경우 클라이언트가 개별 액세스 토큰을 취소할 수 있습니다.

이전 버전과의 호환성을 위해 이전 버전의 동작을 계속 사용할 수 있습니다. 이 방법을 사용하면 클라이언트 자격 증명 부여를 사용한 인증에 성공하고 사용자 세션이 생성된 후에도 새로 고침 토큰이 계속 발행됩니다. 특정 클라이언트의 경우 다음과 같이 관리 콘솔에서 이전 동작을 활성화할 수 있습니다.

이전 버전에서는 Red Hat Single Sign-On에서 두 개의 인트로스펙션 끝점인 token_introspection_endpoint 및 introspection_endpoint 를 알립니다. 후자는 RFC-8414 에 의해 정의된 것입니다. 전자는 더 이상 사용되지 않으며 제거되었습니다.

이전 Red Hat Single Sign-On 버전에서는 LDAP 공급자가 Import Users OFF로 설정된 경우 LDAP가 매핑되지 않은 일부 속성이 변경된 경우에도 사용자를 업데이트할 수 있었습니다. 이로 인해 혼란스러운 동작이 발생했습니다. 속성이 업데이트되었지만 업데이트되지 않은 것으로 표시되었습니다.

예를 들어 admin REST API를 사용하여 사용자를 업데이트하려고 했고 사용자가 잘못된 속성이 변경되면 업데이트가 가능했습니다. 현재 버전을 사용하면 업데이트를 사용할 수 없으며 이유를 즉시 알릴 수 있습니다.

Red Hat Single Sign-On 서버가 EAP 7.3을 기본 컨테이너로 사용하도록 업그레이드되었습니다. 이 변경 사항은 특정 Red Hat Single Sign-On 서버 기능과 직접적인 관련이 없지만 마이그레이션과 관련하여 몇 가지 변경 사항이 있습니다.

마이그레이션 중에 인증 흐름과 관련된 몇 가지 리팩토링 및 개선 사항을 수행했습니다.

이 릴리스에서는 영역에 중복된 최상위 수준 그룹을 생성할 수 있는 문제를 해결합니다. 그러나 이전 중복 그룹의 존재로 인해 업그레이드 프로세스가 실패합니다. Red Hat Single Sign-On 서버는 H2, MariaDB, MySQL 또는 PostgreSQL 데이터베이스를 사용하는 경우 이 문제의 영향을 받을 수 있습니다. 업그레이드를 시작하기 전에 서버에 중복된 최상위 그룹이 포함되어 있는지 확인합니다. 예를 들어 다음 SQL 쿼리는 데이터베이스 수준에서 실행하여 나열할 수 있습니다.For example, the following SQL query can be executed at database level to list them:

SELECT REALM_ID, NAME, COUNT(*) FROM KEYCLOAK_GROUP WHERE PARENT_GROUP is NULL GROUP BY REALM_ID, NAME HAVING COUNT(*) > 1;

SELECT REALM_ID, NAME, COUNT(*) FROM KEYCLOAK_GROUP WHERE PARENT_GROUP is NULL GROUP BY REALM_ID, NAME HAVING COUNT(*) > 1;

동일한 이름으로 각 영역에 하나의 최상위 그룹만 존재할 수 있습니다. 중복은 업그레이드 전에 검토 및 삭제해야 합니다. 업그레이드 오류에는 Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak failed 메시지가 포함됩니다.

사용자 자격 증명을 저장하는 데 더 많은 유연성을 추가했습니다. 특히 모든 사용자는 여러 OTP 자격 증명과 같이 동일한 유형의 자격 증명을 여러 개 가질 수 있습니다. 일부 변경 사항은 데이터베이스 스키마에 존재하지만 이전 버전의 자격 증명은 새 형식으로 업데이트됩니다. 사용자는 이전 버전에 정의된 암호 또는 OTP 인증 정보를 사용하여 로그인할 수 있습니다.

MicroProfile/JWT Auth Specification에 정의된 클레임을 처리하기 위해 microprofile-jwt 선택적 클라이언트 범위를 추가했습니다. 이 새로운 클라이언트 범위는 인증된 사용자의 사용자 이름을 upn 클레임으로 설정하고 영역 역할을 그룹 클레임으로 설정하는 프로토콜 매퍼를 정의합니다.

로그인 페이지의 로케일 선택 방법과 사용자의 로케일이 업데이트되는 시기에 대해 여러 가지 개선 사항이 추가되었습니다. 자세한 내용은 서버 관리 가이드를 참조하십시오.

더 이상 JavaScript 어댑터에서 commitmentType을 설정할 필요가 없으며 둘 다 동시에 사용할 수 있습니다. 레거시 API(uccess 및 error)가 특정 시점에서 제거되므로 가능한 한 빨리 네이티브 약속 API(함께 및 catch)를 사용하도록 애플리케이션을 업데이트하는 것이 좋습니다.

지금까지 관리자는 Red Hat Single Sign-On 관리 콘솔과 RESTful Admin API를 통해 서버에 스크립트를 업로드할 수 있었습니다. 이 기능은 이제 비활성화되어 있습니다. 사용자는 서버에 스크립트를 직접 배포해야 합니다. 자세한 내용은 JavaScript Provider를 참조하십시오.

이전 릴리스에서는 개발자가 JavaScript 어댑터에 클라이언트 자격 증명을 제공할 수 있었습니다. 현재는 클라이언트 측 애플리케이션이 시크릿을 유지하는 데 안전하지 않기 때문에 이 기능이 제거되었습니다. prompt=none을 기본 IDP에 전파하는 기능

message=none 쿼리 매개변수를 포함하는 전달된 요청을 처리할 수 있는 IDP를 식별하기 위해 클라이언트에서 Accepts prompt=none forward라는 OIDC ID 공급자 구성에 스위치를 추가했습니다.

지금까지 prompt=none을 사용하여 auth 요청을 수신할 때 사용자가 IDP에서 인증했는지 확인하지 않으면 영역에 login_required 오류가 반환됩니다. 이제부터 kc_idp_hint 쿼리 매개 변수를 사용하거나 영역의 기본 IDP를 설정하여 기본 IDP에 대한 기본 IDP를 결정할 수 있고 클라이언트 스위치에서 Accepts 프롬프트=none 전달이 IDP에 대해 활성화되었는지 인증 요청이 IDP에 대해 활성화되었는지 확인하도록 auth 요청이 IDP로 전달됩니다.

이 스위치는 기본 IDP가 지정된 경우에만 고려되며 이 경우 사용자에게 IDP를 선택하라는 메시지를 표시하지 않고 auth 요청을 전달할 위치를 알고 있습니다. 기본 IDP를 결정할 수 없는 경우 요청 전달이 수행되지 않도록 auth 요청을 이행하는 데 사용할 것을 가정할 수 없습니다.

요청 및 수정된 호스트 이름 공급자가 새 기본 호스트 이름 공급자로 교체되었습니다. 요청 및 수정된 호스트 이름 공급자는 더 이상 사용되지 않으며 가능한 한 빨리 기본 호스트 이름 공급자로 전환하는 것이 좋습니다.

일부 기능은 상태가 변경됩니다.

Authorization ServicesECDHE 정책이 제거되었습니다.

UMA 2.0에 대한 지원이 추가되었습니다. 이 버전의 UMA 사양에는 서버에서 권한을 얻는 방법에 대한 몇 가지 중요한 변경 사항이 도입되었습니다.

UMA 2.0 지원에 의해 도입된 주요 변경 사항은 다음과 같습니다. 자세한 내용은 인증 서비스 가이드를 참조하십시오.

마이그레이션 중에 몇 가지 주의가 필요한 클라이언트 범위에 대한 지원이 추가되었습니다.

새로운 영역의 기본 클라이언트 범위 역할과 웹 출처를 추가했습니다. 이러한 클라이언트 범위에는 사용자의 역할을 추가하고 웹 원본을 토큰에 허용하는 프로토콜 매퍼가 포함되어 있습니다. 마이그레이션 중에 이러한 클라이언트 범위는 모든 OpenID Connect 클라이언트에 기본 클라이언트 범위로 자동으로 추가되어야 합니다. 따라서 데이터베이스 마이그레이션이 완료된 후에는 설정이 필요하지 않습니다.

Red Hat Single Sign-On 서버가 EAP 7.2를 기본 컨테이너로 사용하도록 업그레이드되었습니다. 여기에는 특정 Red Hat Single Sign-On 서버 기능과 직접적인 관련이 없지만 마이그레이션과 관련하여 몇 가지 변경 사항이 있습니다.

이전 버전에서는 필터를 사용하여 허용된 호스트 이름을 지정하는 것이 좋습니다. 이제 유효한 호스트 이름이 사용되는지 확인하고 내부 애플리케이션에서 대체 URL(예: 내부 IP 주소)을 통해 Red Hat Single Sign-On을 호출할 수 있도록 고정 호스트 이름을 설정할 수 있습니다. 프로덕션 환경에서 이 방법으로 전환하는 것이 좋습니다.

JavaScript 어댑터와 함께 네이티브 JavaScript를 사용하려면 이제 init 옵션에서 commitment Type 을 네이티브 로 설정해야 합니다.

이전에는 네이티브 약속이 사용 가능한 경우 기존 Keycloak 약속과 네이티브 약속 모두를 제공하는 래퍼가 반환되었습니다. 이로 인해 오류 처리기가 기본 오류 이벤트 이전에 설정되지 않았기 때문에 문제가 발생하여 Uncaught(예: Promise) 오류가 발생했습니다.

Red Hat Single Sign-On의 Microsoft Identity Provider 구현은 라이브 SDK 엔드포인트를 사용하여 권한 부여 및 사용자 프로필을 얻는 데 사용되었습니다. 2018년 11월 부터 Microsoft는 새로운 Microsoft Graph API를 대신하여 Live SDK API에 대한 지원을 제거하고 있습니다. Red Hat Single Sign-On ID 공급자가 새 엔드포인트를 사용하도록 업데이트되었으므로 이 통합이 사용 중인 경우 최신 Red Hat Single Sign-On 버전으로 업그레이드해야 합니다.

"라이브 SDK 애플리케이션"에 등록된 기존 클라이언트 애플리케이션은 애플리케이션의 id 형식 변경으로 인해 Microsoft Graph 엔드 포인트에서 작동하지 않습니다. 디렉터리에 애플리케이션 ID를 찾을 수 없다는 오류가 발생하면 Microsoft Application 등록 포털에 클라이언트 애플리케이션을 다시 등록하여 새 애플리케이션 ID를 가져와야 합니다.

Red Hat Single Sign-On의 Google ID 공급자 구현은 Google+ API 엔드포인트를 사용하여 권한 부여 및 사용자 프로필을 가져오는 데 사용됩니다. 2019년 3월 부터 Google은 새로운 Google Sign-in 인증 시스템을 사용하기 위해 Google+ API에 대한 지원을 제거하고 있습니다. Red Hat Single Sign-On ID 공급자가 새 엔드포인트를 사용하도록 업데이트되었으므로 이 통합이 사용 중인 경우 최신 Red Hat Single Sign-On 버전으로 업그레이드해야 합니다.

디렉터리에 애플리케이션 ID를 찾을 수 없다는 오류가 발생하면 Google API 콘솔 포털에 클라이언트 애플리케이션을 다시 등록하여 새 애플리케이션 ID 및 시크릿을 가져와야 합니다.

Google+ 사용자 정보 끝점에서 제공한 비표준 클레임에 대해 사용자 지정 매퍼를 조정해야 하며 Google Sign-in API에서 다른 이름으로 제공될 수 있습니다. 사용 가능한 클레임에 대한 최신 정보는 Google 설명서를 참조하십시오.

이에 따라, 모든 개발자가 자신의 API 및 OAuth 2.0 버전 2.0으로 마이그레이션해야 합니다. 이에 따라, 당사는 NVIDIA social Broker를 업데이트했습니다.

이 브로커를 사용하는 기존 배포에서는 iPXE API 버전 2를 사용하여 사용자 프로필을 가져올 때 오류가 발생할 수 있습니다. 이 오류는 프로필 API에 액세스할 수 없거나 인증 프로세스 중에 특정 OAuth2 범위를 요청할 수 없는 브로커를 구성하는 데 사용되는 클라이언트 애플리케이션에 부여된 권한 부족과 관련이 있을 수 있습니다.

새로 생성된 iPXE 클라이언트 애플리케이션의 경우에도 클라이언트가 r_liteprofile 및 r_emailaddress OAuth2 범위를 요청할 수 있고 클라이언트 애플리케이션이 https://api.linkedin.com/v2/me 끝점에서 현재 멤버의 프로필을 가져올 수 있는지 확인해야 합니다.

이러한 개인 정보 보호 제한으로 인해 멤버의 정보에 대한 액세스 및 현재 멤버의 프로필 API에서 반환한 제한된 클레임 세트와 관련된 이러한 개인 정보 보호 제한으로 인해, 현재 Link Broker는 멤버의 이메일 주소를 기본 사용자 이름으로 사용하고 있습니다. 즉, 인증 중에 권한 부여 요청을 보낼 때 r_emailaddress 가 항상 설정됩니다.

두 개의 새로운 암호 해시 알고리즘 (pbkdf2-sha256 및 pbkdf2-sha512)을 추가했습니다. 새로운 영역은 27500 해시 반복과 함께 pbkdf2-sha256 해시 알고리즘을 사용합니다. pbkdf2-sha256은 pbkdf2보다 약간 빠르기 때문에 반복이ECDHE에서 27500으로 증가했습니다.

암호 정책에 해시 알고리즘(지정되지 않음) 및 반복(재정되지 않음)의 기본값이 포함된 경우 기존 영역이 업그레이드됩니다. 해시 반복을 변경한 경우 보다 안전한 해시 알고리즘을 사용하려는 경우 pbkdf2-sha256으로 수동으로 변경해야 합니다.

RH-SSO 7.0에서는 scope=openid 쿼리 매개변수가 있는지 또는 권한 부여 요청에 없는 ID 토큰이 반환되었습니다. OpenID Connect 사양에 따라 올바르지 않습니다.

RH-SSO 7.1에서는 이 쿼리 매개변수를 어댑터에 추가했지만 마이그레이션을 수용하기 위해 이전 동작을 그대로 유지합니다.

RH-SSO 7.2에서 이 동작이 변경되었으며, 이제 요청을 OpenID Connect 요청으로 표시하려면 scope=openid 쿼리 매개변수가 필요합니다. 이 쿼리 매개변수를 생략하면 ID 토큰이 생성되지 않습니다.

Microsoft JDBC Driver 6.0은 JDBC 드라이버 모듈에 추가 종속성을 추가해야 합니다. Microsoft SQL Server를 사용할 때 NoClassDefFoundError 오류가 관찰되는 경우 JDBC 드라이버 module.xml 파일에 다음 종속성을 추가하십시오.

<module name="javax.xml.bind.api"/>

<module name="javax.xml.bind.api"/>

OpenID Connect 세션 관리 사양에서는 session_state 가 OpenID Connect 인증 응답에 있어야 합니다.

RH-SSO 7.1에서는 이 매개변수가 없지만 이제 Red Hat Single Sign-On에서 사양에 따라 기본적으로 이 매개변수를 추가합니다.

그러나 일부 OpenID Connect/ OAuth2 어댑터 및 특히 이전 Red Hat Single Sign-On 어댑터(예: RH-SSO 7.1 이상)에는 이 새 매개변수에 문제가 있을 수 있습니다.

예를 들어, 매개 변수는 클라이언트 애플리케이션에 대한 인증이 성공한 후 항상 브라우저 URL에 표시됩니다. RH-SSO 7.1 또는 레거시 OAuth2 / OpenID Connect 어댑터를 사용하는 경우 session_state 매개변수를 인증 응답에 추가하는 것이 유용할 수 있습니다. 이 작업은 Red Hat Single Sign-On 관리 콘솔의 특정 클라이언트에 대해 가능하며, 4.1절. “이전 어댑터와의 호환성” 에 설명된 OpenID Connect 호환성 모드 섹션의 클라이언트 세부 정보에서 수행할 수 있습니다. session_state 매개 변수를 인증 응답에 추가하지 않도록 설정하도록 설정할 수 있는 Exclude Session State From Authentication Response 스위치가 있습니다.

Red Hat Single Sign-On의 Microsoft Identity Provider 구현은 최대 버전 7.2.4에서 라이브 SDK 엔드포인트를 사용하여 권한을 부여하고 사용자 프로필을 취득할 수 있습니다. 2018년 11월 부터 Microsoft는 새로운 Microsoft Graph API를 대신하여 Live SDK API에 대한 지원을 제거하고 있습니다. Red Hat Single Sign-On ID 공급자가 새 엔드포인트를 사용하도록 업데이트되었으므로 이 통합이 사용 중인 경우 Red Hat Single Sign-On 버전 7.2.5 이상으로 업그레이드해야 합니다.

"라이브 SDK 애플리케이션"에 등록된 기존 클라이언트 애플리케이션은 애플리케이션의 id 형식 변경으로 인해 Microsoft Graph 엔드 포인트에서 작동하지 않습니다. 디렉터리에 애플리케이션 ID를 찾을 수 없다는 오류가 발생하면 Microsoft Application 등록 포털에 클라이언트 애플리케이션을 다시 등록하여 새 애플리케이션 ID를 가져와야 합니다.

Red Hat Single Sign-On의 Google ID 공급자 구현은 최대 버전 7.2.5에 따라 승인 및 사용자 프로파일을 가져오기 위해 Google+ API 끝점에 의존합니다. 2019년 3월 부터 Google은 새로운 Google Sign-in 인증 시스템을 사용하기 위해 Google+ API에 대한 지원을 제거하고 있습니다. Red Hat Single Sign-On ID 공급자가 새 엔드포인트를 사용하도록 업데이트되었습니다. 따라서 이 통합이 사용 중인 경우 Red Hat Single Sign-On 버전 7.2.6 이상으로 업그레이드하십시오.

디렉터리에 애플리케이션 ID를 찾을 수 없다는 오류가 발생하면 Google API 콘솔 포털에 클라이언트 애플리케이션을 다시 등록하여 새 애플리케이션 ID 및 시크릿을 가져와야 합니다.

Google+ 사용자 정보 끝점에서 제공한 비표준 클레임에 대해 사용자 지정 매퍼를 조정해야 하며 Google Sign-in API에서 다른 이름으로 제공될 수 있습니다. 사용 가능한 클레임에 대한 최신 정보는 Google 설명서를 참조하십시오.

이에 따라, 모든 개발자가 자신의 API 및 OAuth 2.0 버전 2.0으로 마이그레이션해야 합니다. 따라서 이 통합이 사용 중인 경우 Red Hat Single Sign-On 버전 7.2.6 이상으로 업그레이드되었는지 확인하십시오.

이 브로커를 사용하는 기존 배포에서는 iPXE API 버전 2를 사용하여 사용자 프로필을 가져올 때 오류가 발생할 수 있습니다. 이 오류는 프로필 API에 액세스할 수 없거나 인증 프로세스 중에 특정 OAuth2 범위를 요청할 수 없는 브로커를 구성하는 데 사용되는 클라이언트 애플리케이션에 부여된 권한 부족과 관련이 있을 수 있습니다.

새로 생성된 iPXE 클라이언트 애플리케이션의 경우에도 클라이언트가 r_liteprofile 및 r_emailaddress OAuth2 범위를 요청할 수 있고 클라이언트 애플리케이션이 https://api.linkedin.com/v2/me 끝점에서 현재 멤버의 프로필을 가져올 수 있는지 확인해야 합니다.

이러한 개인 정보 보호 제한으로 인해 멤버의 정보에 대한 액세스 및 현재 멤버의 프로필 API에서 반환한 제한된 클레임 세트와 관련된 이러한 개인 정보 보호 제한으로 인해, 현재 Link Broker는 멤버의 이메일 주소를 기본 사용자 이름으로 사용하고 있습니다. 즉, 인증 중에 권한 부여 요청을 보낼 때 r_emailaddress 가 항상 설정됩니다.

RH-SSO 7.0의 경우 하나의 키 세트만 영역과 연결할 수 있습니다. 즉, 키를 변경할 때 현재 쿠키와 토큰이 모두 무효화되고 모든 사용자가 다시 인증해야 합니다. RH-SSO 7.1의 경우 한 영역에 대한 여러 키 지원이 추가되었습니다. 언제든지 하나의 키 세트가 서명 생성에 사용되는 활성 세트이지만 서명을 확인하는 데 사용되는 여러 키가 있을 수 있습니다. 즉, 이전 쿠키 및 토큰을 확인한 다음 새 서명으로 새로 고침하여 키가 변경될 때 사용자가 인증 상태를 유지할 수 있습니다. 또한 관리 콘솔 및 관리 REST API를 통해 키를 관리하는 방법에 대한 몇 가지 변경 사항이 있습니다. 자세한 내용은 서버 관리 가이드의 CloudEvent 키 를 참조하십시오.

키 교체를 원활하게 유지하려면 클라이언트 어댑터에서 하드 코드된 키를 제거해야 합니다. 영역 키가 지정되지 않은 한 클라이언트 어댑터는 서버에서 키를 자동으로 검색합니다. 또한 클라이언트 어댑터는 키가 순환될 때 새 키를 자동으로 검색합니다.

RH-SSO 7.0의 경우 클라이언트의 유효한 리디렉션 URI와 일치하는 경우 쿼리 매개변수가 무시됩니다. RH-SSO 7.1의 경우 쿼리 매개변수가 더 이상 무시되지 않습니다. 리디렉션 URI에 쿼리 매개변수를 포함해야 하는 경우 클라이언트의 유효한 리디렉션 URI에 쿼리 매개변수를 지정하거나 와일드카드(예: https://hostname/app/login/*)를 사용해야 합니다. 조각은 더 이상 유효한 리디렉션 URI (즉, https://hostname/app#fragment)에서 허용되지 않습니다.

RH-SSO 7.1의 경우 ID 공급자를 기본 인증 공급자로 설정할 수 없습니다. RH-SSO 7.1의 ID 공급자로 자동 리디렉션하려면 이제 ID 공급자 리디렉션기를 구성해야 합니다. 자세한 내용은 서버 관리 가이드의 기본 ID 공급자를 참조하십시오. 기본 인증 공급자 옵션이 설정된 ID 공급자가 이전에 있는 경우 이 값은 서버를 RH-SSO 7.1으로 업그레이드할 때 ID 공급자 리디렉션의 값으로 자동으로 사용됩니다.

RH-SSO 7.0의 경우 Admin REST API의 페이지를 매긴 끝점에서 maxResults 쿼리 매개변수가 지정되지 않은 경우 모든 결과를 반환합니다. 이로 인해 많은 결과가 반환되었을 때 (예: 사용자) 일시적인 부하 및 요청 시간 초과에 문제가 발생할 수 있습니다. RH-SSO 7.1의 경우 maxResults 값을 지정하지 않으면 최대 100개의 결과가 반환됩니다. maxResults를 -1로 지정하여 모든 결과를 반환할 수 있습니다.

RH-SSO 7.0의 경우 서버 구성은 keycloak-server.json 파일과 standalone/domain.xml 또는 domain.xml 파일로 나뉩니다. RH-SSO 7.1의 경우 keycloak-server.json 파일이 제거되고 standalone.xml 또는 domain.xml 파일을 통해 모든 서버 구성이 수행됩니다. RH-SSO 7.1의 업그레이드 프로시저는 keycloak-server.json 파일에서 standalone.xml 또는 domain.xml 파일로 서버 구성을 자동으로 마이그레이션합니다.

RH-SSO 7.1의 경우 이제 RSA-OAEP 암호화 체계를 사용하여 SAML 어설션 및 문서의 키가 암호화됩니다. 암호화된 어설션을 사용하려면 서비스 공급자가 이 암호화 스키마를 지원하는지 확인하십시오. RSA-OAEP를 지원하지 않는 서비스 공급자가 있는 경우 RH-SSO는 시스템 속성 "keycloak.saml.key_trans.rsa_v1.5"로 설정된 서버를 시작하여 레거시 RSA-v1.5 암호화 스키마를 사용하도록 구성할 수 있습니다. 이를 수행하는 경우 보다 안전한 RSA-OAEP 암호화 스키마로 되돌릴 수 있도록 서비스 공급자를 최대한 빨리 업그레이드해야 합니다.

업그레이드하기 전에 업그레이드 단계를 수행해야 하는 순서를 알고 있어야 합니다. 특히 어댑터를 업그레이드하기 전에 Red Hat Single Sign-On 서버를 업그레이드해야 합니다.

서버 업그레이드가 성공했는지 확인하려면 다음 지침을 따르십시오.

ZIP 파일 또는 설치에 사용한 방법에 따라 RPM 에서 서버를 업그레이드합니다.

이전 설치에 따라 상황에 적용되는 적절한 업그레이드 스크립트를 실행합니다.

Red Hat Single Sign-On은 데이터베이스 스키마를 자동으로 마이그레이션하거나 수동으로 수행하도록 선택할 수 있습니다. 기본적으로 새 설치를 처음 시작하면 데이터베이스가 자동으로 마이그레이션됩니다.

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </provider>
</spi>

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </provider>
</spi>

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)

<spi name="connectionsLiquibase">
    <provider name="default" enabled="true">
        <properties>
            <property name="indexCreationThreshold" value="300000"/>
        </properties>
    </provider>
</spi>

<spi name="connectionsLiquibase">
    <provider name="default" enabled="true">
        <properties>
            <property name="indexCreationThreshold" value="300000"/>
        </properties>
    </provider>
</spi>

/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)

/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="manual"/>
        </properties>
    </provider>
</spi>

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="manual"/>
        </properties>
    </provider>
</spi>

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)

사용자 지정 주제를 생성한 경우 새 서버로 마이그레이션해야 합니다. 내장된 주제의 모든 변경 사항은 사용자 지정 내용에 따라 사용자 지정 항목에 반영해야 할 수 있습니다.

이전 서버 themes 디렉터리의 사용자 지정 주제를 새 서버 themes 디렉터리에 복사해야 합니다. 그런 다음 아래 변경 사항을 검토하고 변경 사항을 사용자 지정 topic에 적용해야 하는지 고려해야 합니다.

요약하면 다음과 같습니다.

각 단계는 변경 사항 목록 아래에 자세히 설명되어 있습니다.

diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

RH-SSO의 ZIP 설치에 대한 패치는 Red Hat 고객 포털에서 다운로드할 수 있습니다.

관리형 도메인 환경의 여러 RH-SSO 호스트의 경우 RH-SSO 도메인 컨트롤러에서 개별 호스트를 패치할 수 있습니다.

패치를 적용하는 것 외에도 패치 적용을 롤백할 수 있습니다.

/core-service=patching:ageout-history

/core-service=patching:ageout-history

서브스크립션 리포지토리의 RPM을 통해 RH-SSO 패치를 설치하려면 다음 명령을 사용하여 Red Hat Enterprise Linux 시스템을 업데이트합니다.

yum update

yum update