2.3. Node.js 어댑터

Node.js 를 이미 설치했다고 가정하면 애플리케이션의 폴더를 생성합니다.

mkdir myapp && cd myapp

npm init 명령을 사용하여 애플리케이션에 대한 package.json 을 생성합니다. 이제 종속 항목 목록에 Red Hat Single Sign-On 연결 어댑터를 추가합니다.

    "dependencies": {
        "keycloak-connect": "file:keycloak-connect-18.0.7.tgz"
    }

프로젝트의 루트 디렉터리에서 server.js 라는 파일을 생성하고 다음 코드를 추가합니다.

    const session = require('express-session');
    const Keycloak = require('keycloak-connect');

    const memoryStore = new session.MemoryStore();
    const keycloak = new Keycloak({ store: memoryStore });

express-session 종속성을 설치합니다.

    npm install express-session

server.js 스크립트를 시작하려면 package.json 의 'scripts' 섹션에 다음 명령을 추가합니다.

    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "start" "node server.js"
    },

이제 다음 명령을 사용하여 서버를 실행할 수 있습니다.

    npm run start

기본적으로 이 명령은 애플리케이션의 기본 실행 파일과 함께 keycloak.json 이라는 파일을 찾고 루트 폴더의 경우 공개 키, 영역 이름, 다양한 URL과 같은 키클로크별 설정을 초기화합니다.

이 경우 Keycloak 관리 콘솔에 액세스하려면 Keycloak 배포가 필요합니다.

Podman 또는 Docker를 사용하여 Keycloak 관리 콘솔을 배포하는 방법에 대한 링크를 방문하십시오.

이제 Red Hat Single Sign-On 관리 콘솔 클라이언트(left sidebar) 클라이언트 설치 형식 옵션 Keycloak OIDC JSON을 선택하여 keycloak.json 파일을 가져올 준비가 되었습니다.

다운로드한 파일을 프로젝트의 루트 폴더에 붙여넣습니다.

이 방법을 사용하면 적절한 기본값이 모두 사용됩니다. 또는 keycloak.json 파일 대신 구성 오브젝트를 제공할 수도 있습니다.

    const kcConfig = {
        clientId: 'myclient',
        bearerOnly: true,
        serverUrl: 'http://localhost:8080/auth',
        realm: 'myrealm',
        realmPublicKey: 'MIIBIjANB...'
    };

    const keycloak = new Keycloak({ store: memoryStore }, kcConfig);

애플리케이션은 다음을 사용하여 사용자를 선호하는 ID 공급자로 리디렉션할 수도 있습니다.

    const keycloak = new Keycloak({ store: memoryStore, idpHint: myIdP }, kcConfig);

    const session = require('express-session');
    const memoryStore = new session.MemoryStore();

    // Configure session
    app.use(
      session({
        secret: 'mySecret',
        resave: false,
        saveUninitialized: true,
        store: memoryStore,
      })
    );

    const keycloak = new Keycloak({ store: memoryStore });

    const keycloak = new Keycloak({ scope: 'offline_access' });

인스턴스화한 후 연결 가능 앱에 미들웨어를 설치합니다.Once instantiated, install the middleware into your connect-able app:

이렇게 하려면 먼저 Express를 설치해야 합니다.

    npm install express

아래에 설명된 대로 프로젝트에 Express가 필요합니다.

    const express = require('express');
    const app = express();

아래 코드에 추가하여 Express에서 Keycloak 미들웨어를 구성합니다.

    app.use( keycloak.middleware() );

마지막으로 다음 코드를 main.js 에 추가하여 포트 3000에서 HTTP 요청을 수신하도록 서버를 설정해 보겠습니다.

    app.listen(3000, function () {
        console.log('App listening on port 3000');
    });

애플리케이션이 SSL 연결 Express를 종료하는 프록시 뒤에서 실행중인 경우 프록시 뒤의 표현 가이드에 따라 SSL 연결을 구성해야 합니다. 잘못된 프록시 설정을 사용하면 잘못된 리디렉션 URI가 생성될 수 있습니다.

설정 예:

    const app = express();

    app.set( 'trust proxy', true );

    app.use( keycloak.middleware() );

리소스에 액세스하기 전에 사용자가 인증되었는지 확인하려면 keycloak.checkSso() 를 사용합니다. 이는 사용자가 이미 로그인한 경우에만 인증됩니다. 사용자가 로그인하지 않은 경우 브라우저가 원래 요청된 URL로 다시 리디렉션되고 인증되지 않은 상태로 유지됩니다.

    app.get( '/check-sso', keycloak.checkSso(), checkSsoHandler );

    app.get( '/complain', keycloak.protect(), complaintHandler );

    app.get( '/special', keycloak.protect('special'), specialHandler );

다른 앱의 애플리케이션 역할로 리소스를 보호하려면 다음을 수행합니다.

    app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );

영역 역할을 사용하여 리소스를 보호하려면 다음을 수행합니다.

    app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );

    app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);

keycloak-enforcer 방법은 response_mode 구성 옵션의 값에 따라 두 가지 모드에서 작동합니다.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);

response_mode 가 토큰 으로 설정된 경우 애플리케이션에 전송된 전달자 토큰이 나타내는 주체를 대신하여 권한을 서버에서 가져옵니다. 이 경우 서버가 부여한 권한으로 Keycloak에서 새 액세스 토큰을 발행합니다. 서버가 예상 권한으로 토큰을 사용하여 응답하지 않으면 요청이 거부됩니다. 이 모드를 사용하는 경우 다음과 같이 요청에서 토큰을 가져올 수 있습니다.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
        const token = req.kauth.grant.access_token.content;
        const permissions = token.authorization ? token.authorization.permissions : undefined;

        // show user profile
    });

애플리케이션이 세션을 사용하고 있고 서버의 이전 결정을 캐시하고 새로 고침 토큰을 자동으로 처리하려는 경우 이 모드를 선호합니다. 이 모드는 클라이언트 및 리소스 서버 역할을 하는 애플리케이션에 특히 유용합니다.

response_mode 가 권한 (기본 모드)로 설정된 경우 서버는 새 액세스 토큰을 발행하지 않고 부여된 권한 목록만 반환합니다. 새 토큰을 발행하지 않는 것 외에도 이 방법은 다음과 같이 요청을 통해 서버에서 부여한 권한을 노출합니다.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
        const permissions = req.permissions;

        // show user profile
    });

사용 중인 response_mode 에 관계없이 keycloak.enforcer 방법은 먼저 애플리케이션에 전송된 전달자 토큰 내의 권한을 확인하려고 합니다. 전달자 토큰이 이미 예상 권한을 전달한 경우 결정을 받기 위해 서버와 상호 작용할 필요가 없습니다. 이 기능은 클라이언트가 보안 리소스에 액세스하기 전에 예상 권한으로 서버에서 액세스 토큰을 가져올 수 있으므로 증분 권한과 같은 Keycloak 인증 서비스에서 제공하는 일부 기능을 사용할 수 있고 keycloak.enforcer 가 리소스에 대한 액세스를 적용하는 경우 서버에 대한 추가 요청을 방지할 수 있는 경우에 특히 유용합니다.

기본적으로 정책 적용자는 애플리케이션에 정의된 client_id 를 사용합니다(예: keycloak.json)을 통해 Keycloak 인증 서비스를 지원하는 Keycloak의 클라이언트를 참조합니다. 이 경우 실제로 리소스 서버인 경우 클라이언트를 공용으로 제공할 수 없습니다.

애플리케이션이 공용 클라이언트(frontend) 및 리소스 서버(backend) 둘 다 역할을 하는 경우 다음 구성을 사용하여 적용하려는 정책과 함께 Keycloak의 다른 클라이언트를 참조할 수 있습니다.

      keycloak.enforcer('user:profile', {resource_server_id: 'my-apiserver'})

Keycloak에서 다른 클라이언트를 사용하여 프런트 엔드 및 백엔드를 나타내는 것이 좋습니다.

Keycloak 인증 서비스를 사용하여 보호하는 애플리케이션이 활성화되어 있고 keycloak.json 에 클라이언트 인증 정보가 정의된 경우 추가 클레임을 서버에 푸시하고 정책에서 해당 정보를 정책에서 사용할 수 있도록 할 수 있습니다. 이를 위해 푸시하려는 클레임 과 함께 JSON을 반환하는 함수 를 예상하는 클레임 구성 옵션을 정의할 수 있습니다.

      app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
          claims: function(request) {
            return {
              "http.uri": ["/protected/resource"],
              "user.agent": // get user agent  from request
            }
          }
        }), function (req, res) {
          // access granted

애플리케이션 리소스를 보호하기 위해 Keycloak을 구성하는 방법에 대한 자세한 내용은 인증 서비스 가이드를 참조하십시오.

    function protectBySection(token, request) {
      return token.hasRole( request.params.section );
    }

    app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );

고급 로그인 설정:

기본적으로 권한이 없는 모든 요청은 클라이언트가 전달하지 않는 한 Red Hat Single Sign-On 로그인 페이지로 리디렉션됩니다. 그러나 기밀 또는 공용 클라이언트는 검색 가능한 API 끝점을 모두 호스팅할 수 있습니다. 인증되지 않은 API 요청에서 리디렉션을 방지하고 대신 HTTP 401을 반환하려면 redirectToLogin 함수를 덮어쓸 수 있습니다.

예를 들어, 이 덮어쓰기는 URL에 /api/가 포함되어 있는지 확인하고 로그인 리디렉션을 비활성화합니다.

    Keycloak.prototype.redirectToLogin = function(req) {
    const apiReqMatcher = /\/api\//i;
    return !apiReqMatcher.test(req.originalUrl || req.url);
    };

    app.use( keycloak.middleware( { logout: '/logoff' } ));

user-triggered logout이 쿼리 매개변수 redirect_url 을 호출하면 다음을 전달할 수 있습니다.

https://example.com/logoff?redirect_url=https%3A%2F%2Fexample.com%3A3000%2Flogged%2Fout

이 매개변수는 OIDC 로그 아웃 끝점의 리디렉션 URL로 사용되며 사용자는 https://example.com/logged/out 로 리디렉션됩니다.

    app.use( keycloak.middleware( { admin: '/callbacks' } );

Node.js 어댑터 사용을 사용하는 전체 예제는 Node.js 용 Keycloak 빠른 시작에서 확인할 수 있습니다.