Keycloak 인증 서비스 개요

Keycloak 은 관리 UI와 RESTful API를 기반으로 하며, 보호된 리소스 및 범위(Scope)에 대한 사용 권한을 생성하고, 이러한 사용 권한을 정책과 연결하며, 애플리케이션 및 서비스에 권한 결정을 적용하는 데 필요한 수단을 제공합니다. 또한 Keycloak은 세분화된 인증 정책을 지원하며 다음과 같은 접 제어 메커니즘이 있습니다.

  • Attribute-based access control (ABAC) – 속성 기반 접근 제어는 사용자, 리소스 속성, 환경에 기반으로 접근을 제어하는 방식입니다.
  • Role-based access control (RBAC) – 역할 기반 접근 제어는 사용자에게 할당된 역할에 기반하여 접근을 제어하는 방식입니다.
  • User-based access control (UBAC) – 사용자 기반 접근 제어는 사용자에 따라 접근을 제어하는 방식입니다.
  • Context-based access control (CBAC) – 컨텍스트 기반 접근 제어는 애플리케이션 계층 프로토콜 세션 정보를 기반으로 접근을 제어하는 방식입니다.
  • Rule-based access control – 규칙 기반 접근 제어는 관리자가 사전에 설정한 규칙에 따라 접근을 제어하는 방식 이며, JavaScript 사용 합니다.
  • Time-based access control – 시간 기반 접근 제어는 정책에 시간 변수를 사용하여 특정 시간만 접근을 할 수 있도록 하는 제어 방식입니다.
  • Service Provider Interface (SPI)를 통한 맞춤형 access control mechanisms (ACMs) 지원 – 사용자가 자신의 환경에 맞게 접근 제어 메커니즘을 구성할 수 있습니다.

Keycloak Authorization Services는 애플리케이션 및 서비스의 인증 기능을 사용하면 아래와 같은 장점이 있습니다.

  • 세분화된 권한 부여 정책 및 다양한 접근 제어 메커니즘을 사용한 리소스 보호
  • 중앙 집중식 리소스, 권한 및 정책 관리
  • REST 기반 인증 서비스 세트를 기반으로 하는 REST 보안
  • 권한 부여 워크플로우 및 사용자 관리 접근
  • 프로젝트 간 코드 복제 및 재배치를 방지하고 보안 요구사항의 변화에 신속하게 적응할 수 있습니다.

※ 해당 포스트는 Keycloak이 설치되어 있는 가정하에 인증 서비스 중심으로 설명합니다. Keycloak 설치 및 구성에 대한 자습서를 보시고 설치를 진행해주세요.

목차

1. Keycloak Authorization services
1-1. Keycloak 인증 절차
2. Keycloak 리소스 서버 관리
3. Keycloak 리소스 및 범위 관리
4. Keycloak 정책 관리
4-1. 사용자 기반 정책(User-based policy)
4-2. 역할 기반 정책(Role-based policy)
4-3. JavaScript 기반 정책
4-4. 시간 기반 정책(Time-based policy)
4-5. 통합 정책(Aggregated policy)
4-6. 클라이언트 기반 정책(Client-based policy)
4-7. 그룹 기반 정책(Group-based policy)
4-8. 클라이언트 범위 기반 정책(Client scope-based policy)
4-9. 정규식 기반 정책(Regex-Based Policy)
5. Keycloak
권한 관리
5-1. 리소스 기반 권한
5-2. 범위 기반 권한
6. Keycloak
정책 평가 및 테스트

1. Keycloak Authorization services

Keycloak 인증 서비스는 RESTFul Endpoint로 구성됩니다.

  • Token Endpoint
  • Resource Management Endpoint
  • Permission Management Endpoint

디자인 관점에서 인증 서비스는 권한 패턴 집합을 기반으로 다음 기능을 제공합니다.

  • 정책 관리 지점(PAP)
    • 리소스 서버, 리소스, 범위(scope), 권한 및 정책을 관리하기 위해 Keycloak 관리 콘솔을 기반으로 하는 UI 세트를 제공합니다. 이 중 일부는 Protection API를 사용하여 원격으로 수행할 수 있습니다.
  • 정책 결정 지점(PDP)
    • 인증 요청을 보내고 요청 중인 권한에 따라 정책이 평가되는 배포 가능한 정책 결정 지점을 제공합니다.
  • 정책 시행 지점(PEP)
    • 리소스 서버 측에서 인증 결정을 실제로 시행하기 위해 다양한 환경에 대한 구현을 제공합니다. Keycloak은 몇 가지 기본 정책 시행 지점을 제공합니다.
  • 정책 정보 지점(PIP)
    • Keycloak 인증 서버를 기반으로 하기 때문에 인증 정책을 평가하는 동안 ID 및 런타임 환경에서 속성을 얻을 수 있습니다.

1-1. Keycloak 인증 절차

다음 세 가지 주요 프로세스는 Keycloak을 사용하여 애플리케이션에 대한 세분화된 권한 부여 방법을 이해하는 데 필요한 단계 입니다.

  • Resource Management
  • Permission and Policy Management
  • Policy Enforcement

리소스 관리(Resource Management)

리소스 관리에는 보호 대상을 정의하는 데 필요한 모든 단계가 포함 됩니다.

리소스 서버는 Keycloak 관리 콘솔을 사용하여 관리됩니다. 여기서 등록된 클라이언트 애플리케이션을 리소스 서버로 실행하고 보호할 리소스 및 범위(Scope) 관리를 시작할 수 있습니다.

리소스는 웹 페이지, RESTFull 리소스, 파일 시스템의 파일, EJB등 단일 특정 리소스를 나타내거나 리소스 그룹을 나타낼 수 있습니다.

범위(Scope)는 일반적으로 리소스에 대해 수행할 수 있는 작업을 나타내지만 이에 한정 되지 않고 리소스 내에서 하나 이상의 속성을 나타낼 수도 있습니다.

권한 및 정책 관리(Permission and policy management)

리소스 서버와 보호할 모든 리소스를 정의했으면 권한 및 정책을 설정해야 합니다.

이 프로세스에는 리소스를 제어하는 보안 및 접근 요구 사항을 실제로 정의하는 데 필요한 모든 단계가 포함됩니다.

정책은 어떤 항목(리소스 또는 범위)에 접근 하거나 작업을 수행하기 위해 충족해야 하는 조건을 정의하는 것 입니다. Keycloak은 가장 일반적인 접근 제어 메커니즘을 포함한 몇 가지 기본 정책 유형을 제공합니다. JavaScript를 사용하여 작성된 규칙에 따라 정책을 만들 수도 있습니다.

정책을 정의한 후에 권한을 정의할 수 있습니다. 보호할 항목(리소스 또는 범위)에 권한을 부여하거나 거부하기 위해 충족해야 하는 정책을 지정합니다.

정책 시행(Policy enforcement)

정책 시행에는 리소스 서버에 권한 부여 결정을 실제로 시행하는 단계 입니다. 이는 권한 부여 서버와 통신할 수 있는 리소스 서버에서 정책 시행 지점 또는 PEP를 활성화하고, 권한 부여 데이터를 요청, 서버에서 반환된 결정 및 권한을 기반으로 보호된 리소스에 대한 접근을 제어함으로써 달성됩니다.

2. Keycloak 리소스 서버 관리

리소스 서버에는 보호된 리소스에 대한 세분화된 권한을 부여 하기 위한 플랫폼이 제공되며, 여기에서 다양한 접근 제어 메커니즘을 기반으로 권한을 내릴 수 있습니다.

Keycloak 리소스 서버 관리
  • Settings: 리소스 서버에 대한 일반 설정입니다.
  • Resource: 애플리케이션의 리소스를 관리할 수 있습니다.
  • Authorization Scopes: 범위(Scope)를 관리할 수 있습니다.
  • Policies: 권한 부여 정책을 관리하고 권한을 부여하기 위해 충족해야 하는 조건을 정의할 수 있습니다.
  • Permission: 생성한 정책과 연결하여 보호된 리소스 및 범위에 대한 권한을 관리할 수 있습니다.
  • Evaluate: 권한 부여 요청을 시뮬레이션 하고 정의한 권한 및 권한 부여 정책 평가 결과를 볼 수 있습니다.
  • Export Settings: 권한 설정 셋팅을 JSON파일로 내보낼 수 있습니다.

리소스 서버 설정 페이지에서 정책 시행 모드를 구성하고, 원격 리소스 관리를 허용하고, 인증 구성 설정을 내보낼 수 있습니다.

  • 정책 시행 모드(Policy Enforcement Mode)
    • Enforcing – 기본 모드이며 지정된 리소스와 연결된 정책이 없는 경우에도 기본적으로 요청이 거부됩니다.
    • Permissive – 지정된 리소스와 연결된 정책이 없는 경우에도 요청이 허용됩니다.
    • Disabled – 모든 정책을 비활성화하고 모든 리소스에 대한 접근을 허용합니다.
  • 의사결정 전략(Decision Strategy)
    • 이 구성은 권한의 결과를 기반으로 리소스 또는 범위를 부여해야 하는지 여부를 결정하는 방법을 정하는 것 입니다. Affirmative는 리소스 및 해당 범위에 대한 접근 권한을 부여하려면 적어도 하나의 권한이 긍정적인 결정이 되어야 함을 의미합니다. Unanimous는 최종 결정이 긍정적이기 위해서는 모든 권한이 긍정적으로 결정 되어야 함을 의미합니다.
  • 원격 리소스 관리(Remote Resource Management)
    • 리소스 서버에서 리소스를 원격으로 관리할 수 있는지 여부를 지정합니다. false인 경우 관리 콘솔에서만 리소스를 관리할 수 있습니다.

3. Keycloak 리소스 및 범위 관리

Keycloak 리소스 및 범위 관리
  • Name: 특정 리소스를 설명하는 문자열 정의
  • Type: 하나 이상의 리소스 집합 유형을 고유하게 식별하는 문자열 정의
  • URIS: 리소스의 위치/주소를 제공하는 URI입니다. HTTP 리소스의 URI는 일반적으로 상대 경로입니다.
  • Scopes: 리소스와 연결할 하나 이상의 범위입니다.
  • Resource attributes: 리소스에는 연관된 속성이 있을 수 있습니다. 이러한 속성은 리소스에 대한 추가 정보를 제공하고 리소스와 연결된 권한을 평가할 때 정책에 추가 정보를 제공하는데 사용 합니다. 각 속성은 값이 하나 이상의 문자열 집합일 수 있는 키 및 값 입니다. 각 값을 쉼표로 구분하여 속성에 대해 여러 값을 정의할 수 있습니다.

4. Keycloak 정책 관리

정책은 개체에 대한 접근 권한을 부여하기 전에 충족해야 하는 조건을 정의합니다.

4-1. 사용자 기반 정책(User-based policy)

1명 이상의 사용자 집합이 개체에 접근 하도록 허용되는 권한 조건을 정의할 수 있습니다.

Keycloak 사용자 기반 정책
  • Name: 정책을 식별하는 문자열 정의
  • Description: 정책에 대한 세부 정보 설명 정의
  • Users: 정책에 의해 접 권한이 부여된 사용자를 지정합니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-2. 역할 기반 정책(Role-based policy)

하나 이상의 역할 집합이 개체에 접근하도록 허용되는 권한에 대한 조건을 정의할 수 있습니다.

기본적으로 이 정책에 추가된 역할은 필수 항목으로 지정되지 않으며 접근 요청하는 사용자에게 이러한 역할이 부여된 경우 정책에서 접근 권한을 부여합니다.

역할 정책은 개체에 대한 액세스 권한을 부여하기 위해 특정 역할을 수행해야 하는 RBAC(Restricted Role-Based Access Control)가 필요할 때 유용합니다.

Keycloak 역할 기반 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Realm Roles: 이 정책에서 허용하는 영역 역할을 지정 합니다.
  • Client Roles: 이 정책에서 허용하는 클라이언트 역할을 지정 합니다. 이 필드를 활성화하려면 먼저 Client를 선택해야 합니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-3. JavaScript 기반 정책

이 유형의 정책을 사용하여 JavaScript를 사용하여 권한에 대한 조건을 정의할 수 있습니다. Keycloak에서 지원하는 규칙 기반 정책 유형 중 하나로 평가 API를 기반으로 모든 정책을 작성할 수 있는 유연성을 제공합니다 .

Keycloak Javascript 기반 정책

4-4. 시간 기반 정책(Time-based policy)

이 유형의 정책을 사용하면 권한에 대한 시간 조건을 정의할 수 있습니다.

Keycloak 시간 기반 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Not Before:현재 날짜/시간이 이 값 이상인 경우에만 권한이 부여됩니다.
  • Not On or After: 현재 날짜/시간이 이 값보다 이전이거나 같은 경우에만 권한이 부여됩니다.
  • Day of Month: 접근 권한을 부여해야 하는 날짜를 정의합니다. 날짜 범위를 지정할 수도 있습니다. 이 경우 해당 월의 현재 날짜가 지정된 두 값 사이이거나 같은 경우에만 권한이 부여됩니다.
  • Month: 접근 권한을 부여해야 하는 월을 정의합니다. 월 범위를 지정할 수도 있습니다.
  • Year: 접근 권한을 부여해야 하는 년도를 정의합니다. 연도 범위를 지정할 수도 있습니다.
  • Hour: 접근 권한을 부여해야 하는 시간을 정의합니다. 시간 범위를 지정할 수도 있습니다.
  • Minute: 접근 권한을 부여해야 하는 분을 정의합니다. 분 범위를 지정할 수도 있습니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-5. 통합 정책(Aggregated policy)

Keycloak을 사용하면 통합 정책이라고 하는 개념인 정책을 구축할 수 있습니다. 통합 정책을 사용하여 기존 정책을 재사용해 더 복잡한 정책을 구축할 수 있습니다.

Keycloak 통합 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Apply policy: 집계된 정책과 연결할 하나 이상의 정책 집합을 정의합니다. 정책을 연결하려면 기존 정책을 선택하거나 만들려는 정책 유형을 선택하여 새 정책을 만들 수 있습니다.
  • Decision strategy: 권한에 대한 결정 전략입니다.
    • Unanimous: 전략이 제공되지 않은 경우 기본 전략입니다. 이 경우 모든 정책이 긍정적인 결정으로 평가해야 최종 결정도 긍정적일 수 있습니다.
    • Affirmative: 이 경우 최종 결정도 긍정적이기 위해서는 적어도 하나의 정책이 긍정적 결정으로 평가되어야 합니다.
    • Consensus: 이 경우 긍정적인 결정의 수가 부정적인 결정의 수보다 커야 합니다. 긍정 결정과 부정 결정의 수가 같으면 최종 결정은 부정이 됩니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-6. 클라이언트 기반 정책(Client-based policy)

이 유형의 정책을 사용하여 하나 이상의 클라이언트 집합이 개체에 액세스하도록 허용되는 권한에 대한 조건을 정의할 수 있습니다.

Keycloak 클라이언트 기반 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Clients: 이 정책으로 그룹 기반 정책 접근 권한을 부여한 클라이언트를 지정합니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-7. 그룹 기반 정책(Group-based policy)

이 유형의 정책을 사용하여 하나 이상의 그룹 집합이 개체에 접근하도록 허용되는 권한에 대한 조건을 정의할 수 있습니다.

Keycloak 그룹 기반 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Groups Claim: 그룹 이름 및/또는 경로를 보유하는 토큰의 클레임 이름을 지정합니다. 일반적으로 권한 부여 요청은 일부 사용자를 대신하는 클라이언트에 이전에 발급된 ID 토큰 또는 접근 토큰을 기반으로 처리됩니다.
  • Groups: 권한을 평가할 때 이 정책에 의해 시행되어야 하는 그룹을 선택할 수 있습니다. 그룹을 추가한 후 Extend to Children 확인란을 선택하여 그룹의 하위에 대한 접근을 확장할 수 있습니다. 표시하지 않으면 선택한 그룹에만 액세스 제한이 적용됩니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-8. 클라이언트 범위 기반 정책(Client scope-based policy)

이 유형의 정책을 사용하여 하나 이상의 클라이언트 범위 집합이 개체에 접하도록 허용되는 권한에 대한 조건을 정의할 수 있습니다.

Keycloak 클라이언트 범위 기반 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Client Scopes: 이 정책에서 허용하는 클라이언트 범위를 지정합니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

4-9. 정규식 기반 정책(Regex-Based Policy)

이 유형의 정책을 사용하여 권한에 대한 정규식 조건을 정의할 수 있습니다.

Keycloak 정규식 기반 정책
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Target claim: 토큰의 대상 클레임 이름을 지정합니다.
  • Regex Pattern: 정규식 패턴을 지정합니다.
  • Logic: 다른 조건이 평가된 후에 적용할 정책의 논리입니다.

5. Keycloak 권한 관리

권한은 보호되는 개체와 접근 권한 부여 여부를 결정하기 위해 평가해야 하는 정책을 연결합니다.

5-1. 리소스 기반 권한

리소스 기반 권한은 하나 이상의 권한 부여 정책 집합을 사용하여 보호할 하나 이상의 리소스 집합을 정의합니다.

리소스 기반 권한
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Apply to Resource Type: 지정된 유형의 모든 리소스에 권한이 적용되는지 여부를 지정합니다.
  • Resources: 보호할 하나 이상의 리소스 집합을 정의합니다.
  • Apply Policy: 권한과 연결할 하나 이상의 정책 집합을 정의합니다. 정책을 연결하려면 기존 정책을 선택하거나 생성하려는 정책 유형을 선택하여 새 정책을 생성할 수 있습니다.
  • Decision Strategy: 이 권한에 대한 결정 전략 입니다.

5-2. 범위 기반 권한

범위 기반 권한은 하나 이상의 권한 부여 정책 집합을 사용하여 보호할 하나 이상의 범위 집합을 정의합니다. 리소스 기반 사용 권한과 달리 이 사용 권한 유형을 사용하여 리소스뿐만 아니라 리소스 관련 범위에 대한 사용 권한을 생성할 수 있으므로 리소스를 제어하는 사용 권한과 해당 사용 권한에 대해 수행할 수 있는 작업을 보다 세분화할 수 있습니다.

범위 기반 권한
  • Name: 정책을 설명하는 문자열 정의
  • Description: 이 정책에 대한 세부 정보 설명 정의
  • Resource: 선택한 리소스와 연결된 범위로 범위를 제한합니다. 아무 것도 선택하지 않으면 모든 범위를 사용할 수 있습니다.
  • Scopes: 보호할 하나 이상의 범위 집합을 정의합니다.
  • Apply Policy: 권한과 연결할 하나 이상의 정책 집합을 정의합니다. 정책을 연결하려면 기존 정책을 선택하거나 생성하려는 정책 유형을 선택하여 새 정책을 생성할 수 있습니다.
  • Decision Strategy: 이 권한에 대한 결정 전략 입니다.

6. Keycloak 정책 평가 및 테스트

정책을 설계할 때 권한 부여 요청을 시뮬레이션하여 정책이 평가되는 방식을 테스트할 수 있습니다.

Evaluate 리소스 서버를 편집할 때 탭을 클릭하여 정책 평가 도구에 액세스할 수 있습니다 . 여기에서 실제 승인 요청을 시뮬레이션하고 정책의 효과를 테스트하기 위해 다양한 입력을 지정할 수 있습니다.

정책 평가 및 테스트
  • Providing identity information: ID 필터를 사용하여 권한을 요청하는 사용자를 지정할 수 있습니다.
  • Providing contextual information: 컨텍스트 필터는 정책이 동일한 속성을 얻을 수 있도록 평가 컨텍스트에 대한 추가 속성을 정의하는 데 사용할 수 있습니다.
  • Providing the permissions: 권한 필터는 권한 부여 요청을 작성하는 데 사용할 수 있습니다. 하나 이상의 리소스 및 범위 집합에 대한 사용 권한을 요청할 수 있습니다. 보호된 모든 리소스 및 범위를 기준으로 권한 부여 요청을 시뮬레이션하려면 리소스 또는 범위를 지정하지 않고 추가를 클릭합니다.

Keycloak에 대한 최신 포스트 및 새로운 소식을 빠르게 받고 싶으시면 아래 뉴스레터를 구독해주세요.