OpenID Connect (OIDC)
개요
OIDC (OpenID Connect) Policy는 OIDC 공급자와 통합하여 API에 대한 인증 및 권한 부여를 가능하게 합니다. 이를 통해 인증된 사용자만 API에 접근할 수 있으며, 이는 토큰 기반 접근 방식이나 권한 부여 흐름을 통해 이루어집니다.
구성 세부정보
필수 경로 / 비필수 경로
- Required Path: OIDC 인증은 나열된 경로에 대해서만 적용됩니다.
- Not Required Path: OIDC 인증은 나열된 경로에 대해서는 건너뛰지만, 다른 모든 경로에 대해서는 적용됩니다.
- 경로가 지정되지 않으면 OIDC 인증은 모든 경로에 적용됩니다.
- 경로 옵션 간 전환은 확인이 필요합니다.
권한 부여 유형 구성
OIDC 정책은 인증 흐름을 결정하는 두 가지 Grant Types을 지원합니다:
- Authorization Code Grant: 사용자를 OIDC 공급자로 리디렉션하여 인증을 수행합니다.
- Password Grant: 사용자 자격 증명을 ID 토큰으로 직접 교환합니다.
각 권한 부여 유형은 고유한 구성 세트를 가지고 있습니다:
Authorization Code Grant:이 흐름은 주로 web applications에 사용되며, 사용자가 로그인 페이지를 통해 인증합니다.
| Configuration Field | Description |
|---|---|
| Realm | 인증 영역의 이름입니다. 예: realms_name |
| Client ID | OIDC 공급자가 할당한 고유 식별자입니다. |
| Client Secret | 인증에 필요한 클라이언트 비밀입니다. |
| Discovery | 공급자의 발견 엔드포인트에 대한 URL입니다 (예: https://oidcprovider/.well-known/openid-configuration). |
| 로그아웃 경로 | 사용자를 위한 로그아웃 엔드포인트 (예: /logout). |
| 로그아웃 후 리디렉션 URI | 로그아웃 경로에 대한 리디렉션 URI 매개변수 및 값 |
| 베어러 전용 | 베어러 토큰이 필요한지 정의: 예 (토큰 인증만) 또는 아니오 (토큰 및 로그인 리디렉션 모두 허용). |
| 범위 | 접근 수준을 지정 (기본값: openid). |
| 인트로스펙션 엔드포인트 | 토큰 검증을 위한 URL. |
| 로그인 URL | 사용자 로그인을 위한 API 엔드포인트. |
| 쿠키 도메인 | 인증 쿠키와 관련된 도메인 (예: skapim.com). |
| 우회 헤더 이름 | 특정 요청에 대해 헤더 키를 사용하여 인증을 건너뛸 수 있도록 허용 (예: x-oidc-api-key). |
| 우회 키 | 실제 우회 키 값. |
| 리프레시 토큰 만료 | 토큰 만료 시간 (기본값: 3600초). |
| SameSite | 교차 사이트 요청 처리를 제어하는 쿠키 설정. 옵션: Lax, Strict, 또는 None. |
| 보안 | 보안 쿠키를 활성화 또는 비활성화 (기본값: false). |
| 인증 실패 시 행동 | 인증 실패 시의 동작을 정의. 옵션: 로그인 페이지로 리디렉션 또는 401 반환 (거부). |
| 허용 IP / 거부 IP | 특정 IP가 OIDC 인증을 허용하거나 차단. |
이 흐름은 일반적으로 machine-to-machine authentication 또는 신뢰할 수 있는 클라이언트를 위해 사용됩니다.
| Configuration Field | Description |
|---|---|
| 영역 | 인증 영역의 이름. 예: auth |
| 클라이언트 ID | OIDC 제공자가 할당한 고유 식별자 (예: account). |
| 클라이언트 비밀 | 인증에 필요한 클라이언트 비밀. |
| 디스커버리 | 제공자의 디스커버리 엔드포인트에 대한 URL (예: https://oidcprovider/.well-known/openid-configuration). |
| 로그아웃 경로 | 사용자를 위한 로그아웃 엔드포인트 (예: /Logout). |
| 리디렉션 URI 경로 | 로그인 후 사용자를 리디렉션하는 엔드포인트 (예: /auth/api/login). |
| 범위 | 접근 수준을 지정합니다 (기본값: openid). |
| SameSite | 교차 사이트 요청 처리를 제어하는 쿠키 설정. 옵션: Lax, Strict, 또는 None. |
| 보안 | 보안 옵션을 켜거나 끌 수 있는 토글 |
| 리프레시 토큰 만료 | 토큰 만료 시간 (기본값: 3600초). |
| 로그인 URL | 사용자 로그인을 위한 API 엔드포인트. |
| 세션 이름 | 세션 저장소 이름을 정의합니다 (예: apim_prod_session). |
| 쿠키 도메인 | 인증 쿠키와 관련된 도메인 (예: skapim.com). |
| 우회 헤더 이름 | 특정 요청에 대해 헤더 키를 사용하여 인증을 건너뛸 수 있게 합니다 (예: x-oidc-api-key). |
| 우회 키 | 실제 우회 키 값. |
| 로그인 후 리디렉션 URI | 성공적인 로그인 후 사용자를 리디렉션할 URL. |
| 로그아웃 후 리디렉션 URI | 로그아웃 후 사용자를 리디렉션할 URL. |
참고:
- Authorization Code Grant은 로그인 페이지 리디렉션이 필요하며, Password Grant은 직접 API 요청입니다.
- Bearer Only Mode:
- 예로 설정하면, 토큰 기반 인증만 허용됩니다.
- 아니오로 설정하면, 로그인 리디렉션과 토큰 인증 모두 지원됩니다.
Redis 데이터베이스 선택
세션 데이터는 다양한 유형의 Redis 데이터베이스에 저장될 수 있습니다. 선택된 Redis type는 설정해야 할 구성을 결정합니다.
APIM Redis (Default)- 세션 저장을 위해 내장된 APIM Redis를 사용합니다.
- 추가 구성이 필요하지 않습니다.
- 외부 Redis 인스턴스에 연결할 수 있습니다.
| Configuration Field | Description |
|---|---|
| Redis Host | Redis 서버의 주소 (예: 127.0.0.1). |
| Redis Port | Redis 서버의 포트 번호 (예: 6379). |
| Redis Password | 인증을 위한 비밀번호입니다. |
| Redis Database | 사용할 데이터베이스 인덱스를 지정합니다 (예: 1). |
| Redis Pool Size | Redis 연결 풀에서 최대 연결 수 (기본값: 1000). |
| Redis Pool Backlog | 사용 가능한 연결을 기다리는 최대 요청 수 (기본값: 30). |
- 세션 저장을 위해 분산 Redis 설정을 사용합니다.
| Configuration Field | Description |
|---|---|
| Redis Cluster Nodes | 클러스터 노드 주소 (예: redis-cluster.apim:6379). |
| Redis Cluster Password | 인증을 위한 비밀번호입니다. |
| Redis Cluster Name | 클러스터 이름을 지정합니다 (예: kong_redis_cluster). |
| Redis Connect Timeout | Redis 연결을 설정하기 위한 타임아웃 (기본값: 1000ms). |
| Redis Read Timeout | Redis에서 데이터를 읽기 위한 타임아웃 (기본값: 1000ms). |
| Redis Send Timeout | Redis에 데이터를 전송하기 위한 타임아웃 (기본값: 1000ms). |
| Redis Pool Size | Redis 연결 풀에서 최대 연결 수 (기본값: 1000). |
| Redis Pool Backlog | 최대 대기 중인 연결 수 (기본값: 30). |
| Redis Keepalive Timeout | Redis 연결이 닫히기 전 최대 유휴 시간 (기본값: 55000ms). |
OIDC 인증 동작에 대한 추가 노트
OIDC (OpenID Connect)는 클라이언트 애플리케이션이 외부 OIDC 공급자를 통해 사용자를 인증할 수 있도록 합니다.
로그아웃 경로 및 리디렉션 URI 동작
로그아웃 후 로그아웃 경로 및 리디렉션 URI를 구성할 때, 동작은 API 게이트웨이의 구조에 따라 달라집니다:
- 게이트웨이 URL이 https://your.domain.com이고 API의 기본 경로가 /basePath인 경우를 가정해 보겠습니다.
- OIDC 정책에서 로그아웃 경로를 /logout으로 설정하면 전체 로그아웃 URL은 다음과 같습니다: https://your.domain.com/basePath/logout
- 이 URL이 호출되면 로그아웃은 OIDC 공급자에 의해 내부적으로 처리됩니다.
- 로그아웃 후 브라우저는 요청에서 명시적으로 정의해야 하는 로그아웃 후 리디렉션 URI(즉, redirect_uri 값)로 리디렉션됩니다.
노트
전체 로그아웃 URL과 redirect_uri가 제대로 설정되지 않으면 로그아웃 프로세스가 예상대로 리디렉션되지 않을 수 있습니다.
지원되는 두 가지 인증 방법
OIDC는 인증을 수행하는 두 가지 방법을 허용합니다:
- 브라우저 리디렉션 로그인 화면: 브라우저가 사용자 인증을 위해 OIDC 로그인 페이지로 리디렉션됩니다.
- 요청의 ID 토큰: 클라이언트가 사용자를 리디렉션하지 않고 HTTP를 통해 ID 토큰을 직접 전송합니다.
이 방법들의 동작은 bearerOnly 설정에 따라 달라집니다:
| bearerOnly 값 | 동작 |
|---|---|
| no | (1) 및 (2) 방법 모두 허용됩니다. |
| yes | (2) 방법만 허용됩니다. 시스템은 로그인 페이지로 리디렉션하지 않습니다. |
토큰 검증 및 헤더 형식
- 방법 (2)를 사용하여 ID 토큰을 검증하려면 Introspection Endpoint를 구성해야 합니다 — 토큰 유효성을 검사하는 엔드포인트입니다.
- ID 토큰으로 API를 호출할 때는 다음 형식을 사용하여 요청 헤더에 토큰을 포함시킵니다:
Authorization: bearer your_ID_token
