2.2. JavaScript adapter

기본적으로 JavaScript 어댑터는 Single-Sign Out이 발생했는지를 감지하는 데 사용되는 숨겨진 iframe을 만듭니다. 이 명령은 네트워크 트래픽이 필요하지 않으며, 대신 특수 상태 쿠키를 확인하여 상태를 검색합니다. 이 기능은 init 메서드로 전달되는 옵션에서 checkLoginIframe: false 를 설정하여 비활성화할 수 있습니다.

이 쿠키를 직접 확인하는 데 의존해서는 안 됩니다. 해당 형식은 변경될 수 있으며 애플리케이션이 아닌 Red Hat Single Sign-On 서버의 URL과도 연결됩니다.

기본적으로 JavaScript 어댑터는 인증 코드 흐름을 사용합니다.

이 흐름을 통해 Red Hat Single Sign-On 서버는 인증 토큰이 아닌 권한 부여 코드를 애플리케이션에 반환합니다. JavaScript 어댑터는 브라우저가 애플리케이션으로 리디렉션된 후 액세스 토큰과 새로 고침 토큰을 교체합니다.

Red Hat Single Sign-On은 Red Hat Single Sign-On을 사용한 성공적인 인증 직후 액세스 토큰이 전송되는 Implicit flow를 지원합니다. 토큰 코드를 교환하라는 추가 요청이 없기 때문에 표준 흐름보다 성능이 향상될 수 있지만 액세스 토큰이 만료되면 영향을 미칩니다.

그러나 URL 조각에 액세스 토큰을 전송하는 것은 보안 취약점이 될 수 있습니다. 예를 들어 웹 서버 로그 및 브라우저 기록을 통해 토큰이 유출될 수 있습니다.

암시적 흐름을 활성화하려면 Red Hat Single Sign-On 관리 콘솔에서 클라이언트에 대해 Implicit Flow Enabled 플래그를 활성화해야 합니다. 또한 값이 암시적인 init 메서드로 매개변수 흐름을 전달해야 합니다.

keycloak.init({
    flow: 'implicit'
})

한 가지 주목할 점은 액세스 토큰만 제공되며 새로 고침 토큰이 없다는 것입니다. 즉, 액세스 토큰이 만료되면 애플리케이션이 Red Hat Single Sign-On으로 리디렉션하여 새 액세스 토큰을 다시 가져와야 합니다.

Red Hat Single Sign-On은 하이브리드 흐름도 지원합니다.

이를 위해 클라이언트는 관리 콘솔에서 표준 흐름 사용 및 Implicit Flow Enabled 플래그를 모두 사용하도록 설정해야 합니다. 그러면 Red Hat Single Sign-On 서버가 애플리케이션에 코드와 토큰을 모두 보냅니다. 액세스 및 새로 고침 토큰을 위해 코드를 교환하는 동안 즉시 액세스 토큰을 사용할 수 있습니다. 암시적 흐름과 유사하게, 액세스 토큰을 즉시 사용할 수 있기 때문에 하이브리드 흐름이 성능에 적합합니다. 그러나 토큰은 URL로 계속 전송되며 이전에 언급한 보안 취약점이 계속 적용될 수 있습니다.

하이브리드 흐름의 한 가지 장점은 새로 고침 토큰을 애플리케이션에 사용할 수 있다는 것입니다.

하이브리드 흐름의 경우 값 하이브리드 를 사용하여 매개 변수 흐름을 init 메서드에 전달해야 합니다.

keycloak.init({
    flow: 'hybrid'
})

Keycloak은 Apache Cordova 로 개발된 하이브리드 모바일 애플리케이션을 지원합니다. JavaScript 어댑터에는 cordova 및 cordova-native 의 두 가지 모드가 있습니다.

기본값은 cordova이며 어댑터 유형이 구성되지 않은 경우 어댑터가 자동으로 선택되고 window.cordova가 있습니다. 로그인할 때 사용자가 Red Hat Single Sign-On과 상호 작용하고 나중에 http://localhost 로 리디렉션하여 애플리케이션으로 돌아갈 수 있는 InApp browser가 열립니다. 이로 인해 Admin Console의 클라이언트 구성 섹션에 이 URL을 유효한 redirect-uri로 허용 목록에 추가해야 합니다.

이 모드는 설정하기 쉽지만 몇 가지 단점도 있습니다.

이 예제 앱을 사용하여 시작하는 데 도움이 됩니다. https://github.com/keycloak/keycloak/tree/master/examples/cordova

대체 모드 cordova-native 는 다른 접근 방식을 취합니다. 시스템 브라우저를 사용하여 로그인 페이지를 엽니다. 사용자가 인증되면 브라우저가 특수 URL을 사용하여 앱에 다시 리디렉션됩니다. 여기에서 Red Hat Single Sign-On 어댑터는 URL에서 코드 또는 토큰을 읽고 로그인을 완료할 수 있습니다.

어댑터 유형 cordova-native 를 init 메서드에 전달하여 기본 모드를 활성화할 수 있습니다.

keycloak.init({
    adapter: 'cordova-native'
})

이 어댑터에는 두 개의 추가 플러그인이 필요합니다.

앱에 연결하는 데 필요한 기술적 세부 사항은 플랫폼마다 다르며 특수 설정이 필요합니다. 자세한 내용은 딥링크 플러그인 문서 의 안 드 로이드 및 iOS 섹션을 참조하십시오.

앱 열기 방법에는 사용자 지정 체계(예: myapp://login 또는 iPXE -app://com.example.myapp/https/example.com/login) 및 Universal Links (iOS)) / Deep Links( octavia)의 다양한 종류가 있습니다. 전자는 설정하기가 쉽고 더 안정적으로 작동하는 경향이 있지만 나중에 고유하므로 도메인 소유자 만 추가 보안을 제공합니다. Custom-URLs는 iOS에서 더 이상 사용되지 않습니다. 최상의 안정성을 위해 사용자 정의 URL 링크가 포함된 대체 사이트와 결합된 범용 링크를 사용하는 것이 좋습니다.

또한 Keycloak 어댑터와의 호환성을 개선하기 위해 다음 단계를 권장합니다.

<preference name="AndroidLaunchMode" value="singleTask" />

네이티브 모드 사용 방법을 보여주는 앱 예제: https://github.com/keycloak/keycloak/tree/master/examples/cordova-native

경우에 따라 기본적으로 지원되지 않는 환경에서 JavaScript 클라이언트를 실행해야 합니다(예: Capacitor). 이러한 종류의 알 수 없는 환경에서 JavasScript 클라이언트를 사용할 수 있도록 사용자 지정 어댑터를 전달할 수 있습니다. 예를 들어, 타사 라이브러리에서는 이러한 어댑터를 제공하여 문제 없이 JavaScript 클라이언트를 실행할 수 있습니다.

import Keycloak from 'keycloak-js';
import KeycloakCapacitorAdapter from 'keycloak-capacitor-adapter';

const keycloak = new Keycloak();

keycloak.init({
    adapter: KeycloakCapacitorAdapter,
});

이 특정 패키지는 존재하지 않지만 이러한 어댑터를 클라이언트에 전달하는 방법에 대한 좋은 예를 제공합니다.

또한 고유한 어댑터를 만들 수 있으므로 KeycloakAdapter 인터페이스에 설명된 메서드를 구현해야 합니다. 예를 들어 다음 TypeScript 코드는 모든 메서드가 올바르게 구현되도록 합니다.

import Keycloak, { KeycloakAdapter } from 'keycloak-js';

// Implement the 'KeycloakAdapter' interface so that all required methods are guaranteed to be present.
const MyCustomAdapter: KeycloakAdapter = {
    login(options) {
        // Write your own implementation here.
    }

    // The other methods go here...
};

const keycloak = new Keycloak();

keycloak.init({
    adapter: MyCustomAdapter,
});

당연히 유형 정보를 생략하여 TypeScript 없이 이 작업을 수행할 수도 있지만, 인터페이스를 올바르게 구현하는 것은 전적으로 사용자에게 맡겨집니다.

JavaScript 어댑터는 Base64(window.btoa 및 window.atob), HTML5 기록 API 및 선택적으로 Promise API에 따라 다릅니다. 사용할 수 없는 브라우저 (예: IE9)를 지원해야 하는 경우 polyfiller를 추가해야 합니다.

예제 polyfill 라이브러리:

일부 브라우저의 최신 버전에서 다양한 쿠키 정책이 적용되어 Chrome의 SameSite와 같은 타사 쿠키를 추적하거나 타사 쿠키를 완전히 차단할 수 있습니다. 이러한 정책이 더욱 제한되고 시간이 지남에 따라 다른 브라우저에서 채택되어 결국 타사 컨텍스트에서 쿠키가 완전히 지원되고 차단될 것으로 예상됩니다. 이 문제의 영향을 받는 어댑터 기능은 나중에 더 이상 사용되지 않을 수 있습니다.

JavaScript 어댑터는 세션 상태 iframe, 자동 검사에 대한 타사 쿠키를 사용하고 일부는 일반 (비일명) 검사를 위해 부분적으로 사용됩니다. 이러한 기능은 기능이 제한되거나 브라우저가 쿠키와 관련하여 제한적인 방법에 따라 완전히 비활성화되어 있습니다. 어댑터는 이 설정을 탐지하여 적절하게 대응합니다.