OpenID Connect
필수 종속성: io.ktor:ktor-server-auth-oidc
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✖️
OpenID Connect(OIDC)는 OAuth 2.0 기반의 신원 계층(identity layer)입니다. OAuth 2.0이 위임된 권한 부여(authorization) 프레임워크를 제공하는 반면, OIDC는 클라이언트가 최종 사용자의 신원을 확인할 수 있도록 하여 인증(authentication) 기능을 추가합니다. OIDC는 ID 토큰을 통해 신원 정보를 제공합니다.
Oidc 플러그인은 다음과 같은 일반적인 시나리오를 지원합니다:
- API 보호. 보호된 라우트에 대한 접근을 허용하기 전에 OpenID Connect 제공자가 발급한 토큰의 유효성을 검사합니다. 자세한 내용은 OpenID Connect 리소스 서버를 참고하세요.
- 사용자 로그인. 인증을 위해 사용자를 OpenID Connect 제공자로 리다이렉트하고 로그인 후 콜백을 처리합니다. 자세한 내용은 OpenID Connect 브라우저 로그인을 참고하세요.
두 시나리오 모두 제공자의 발급자(issuer) URL에서 시작됩니다. 플러그인은 제공자의 discovery 문서를 읽고 엔드포인트, 서명 키 및 지원되는 알고리즘을 파악합니다.
OpenID Connect 플러그인은 실험적(experimental) 기능이며, JVM에서만 사용할 수 있고 @OptIn(ExperimentalKtorApi::class)가 필요합니다. 이 플러그인은 Kotlin context parameter가 필요한 타입 안전한 인증 API타입 안전한(type-safe) 인증 스킴 API는 프린시펄(principal) 타입을 라우트에 바인딩하므로, 타입 캐스팅이나 null 검사 없이 null이 아닌 프린시펄을 읽을 수 있습니다.를 사용합니다.
종속성 추가
Oidc 플러그인을 사용하려면 빌드 스크립트에 ktor-server-auth-oidc 아티팩트를 추가하세요:
implementation(ktorLibs.server.auth.oidc)implementation ktorLibs.server.auth.oidc<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-oidc-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>이 아티팩트는 JVM에서만 사용할 수 있습니다.
신원 제공자 등록
Oidc 플러그인을 설치하고 각 발급자에 대한 신원 제공자(identity provider)를 등록합니다:
suspend fun Application.module() {
val oidc = install(Oidc)
val google = oidc.identityProvider("google") {
issuer = "https://accounts.google.com"
bearer {
audience = setOf("my-api")
}
}
}identityProvider() 함수는 결과를 반환하기 전에 discovery 문서를 가져오므로, suspend 애플리케이션 모듈과 같은 일시 중단 함수(suspending function) 내에서 호출해야 합니다.
제공자 이름은 생성된 라우트 경로와 인증 체계 이름에 사용됩니다. 소문자, 숫자, 하이픈으로 구분된 세그먼트로 구성되어야 합니다. 예를 들어, google 및 my-idp는 유효한 이름이지만, Google 및 my_idp는 유효하지 않습니다.
각 제공자 이름과 발급자는 고유해야 합니다. 동일한 이름이나 발급자를 두 번 이상 등록하면 IllegalArgumentException이 발생합니다.
identityProvider() 함수는 라우트를 보호하는 데 사용되는 OidcProvider를 반환합니다. 구성에 따라 제공자는 authenticateWith()와 함께 사용할 수 있는 인증 체계를 최대 3개까지 노출합니다:
| 구성 방법 | 체계 | 보호 대상 |
|---|---|---|
bearer { } | provider.jwtBearer | JWT 액세스 토큰을 수신하는 API |
bearer { introspection { } } | provider.introspectionBearer | 불투명(opaque) 액세스 토큰을 수신하는 API |
oauth { } | provider.session | 브라우저 로그인 뒤에 위치한 라우트 |
구성되지 않은 체계를 읽으려고 하면 IllegalStateException이 발생합니다. 예외 메시지에는 해당 체계를 활성화하는 데 필요한 구성 블록이 명시됩니다.
자세한 내용은 OpenID Connect 리소스 서버 및 OpenID Connect 브라우저 로그인을 참고하세요.
Discovery 작동 방식
플러그인은 <issuer>/.well-known/openid-configuration을 검색한 다음, 여기에서 제공자 엔드포인트와 서명 키를 읽어옵니다. 따라서 권한 부여 엔드포인트, 토큰 엔드포인트 또는 JWKS URL을 수동으로 구성할 필요가 없습니다.
discovery 문서의 issuer 값은 끝에 붙는 슬래시를 포함하여 구성된 issuer와 정확히 일치해야 합니다. 이 비교는 보안 검사이므로 플러그인은 두 값을 정규화하지 않습니다.
초기 요청 이후 플러그인은 기본값으로 15분마다 설정된 discoveryRefreshInterval 간격으로 문서를 다시 읽습니다. 이를 통해 재시작 없이도 키 순환(key rotation)이 애플리케이션에 적용될 수 있습니다:
val oidc = install(Oidc) {
discoveryRefreshInterval = 15.minutes
initialDiscoveryAttempts = 3
initialDiscoveryRetryDelay = 5.seconds
}주기적인 discovery 갱신을 비활성화하려면 discoveryRefreshInterval을 Duration.ZERO로 설정하세요.
Discovery 실패 처리
Discovery 실패는 애플리케이션 시작 중과 애플리케이션 실행 중에 다르게 처리됩니다.
시작 시
초기 discovery 요청이 실패하면 identityProvider()에서 OidcDiscoveryException이 발생합니다. 이 예외는 모듈 함수 밖으로 전달되며 애플리케이션이 시작되지 않습니다.
기본적으로 플러그인은 한 번의 discovery 시도를 수행합니다. 시작 중에 제공자를 일시적으로 사용할 수 없는 상황이 발생할 수 있다면 시도 횟수를 늘리세요:
val oidc = install(Oidc) {
initialDiscoveryAttempts = 5
initialDiscoveryRetryDelay = 3.seconds
}재시도는 네트워크 및 HTTP 오류에 적용됩니다. 발급자 불일치나 필수 엔드포인트가 누락된 discovery 문서와 같은 구성 오류에는 적용되지 않습니다. 이러한 오류는 즉시 IllegalArgumentException과 함께 실패합니다.
실행 중
주기적인 갱신이 실패하면 플러그인은 가장 최근에 가져온 discovery 문서를 계속 사용합니다. 그리고 기본값이 1분으로 설정된 discoveryRefreshFailureDelay 이후에 다시 시도하며 성공할 때까지 재시도를 계속합니다.
갱신 실패는 기본적으로 로깅되지 않습니다. 이를 모니터링하려면 OidcMetadataRefreshFailed 이벤트를 구독하세요:
monitor.subscribe(OidcMetadataRefreshFailed) { failure ->
log.warn(
"OIDC refresh failed for {} ({} in a row)",
failure.provider.name,
failure.consecutiveFailures,
failure.cause
)
}정적 메타데이터 구성
제공자 엔드포인트를 미리 알고 있거나 테스트를 위한 정적 구성이 필요한 경우 metadata 속성을 사용하세요:
val provider = oidc.identityProvider("static") {
issuer = issuerUrl
metadata = OpenIdProviderMetadata(
issuer = issuerUrl,
authorizationEndpoint = "$issuerUrl/authorize",
tokenEndpoint = "$issuerUrl/token",
jwksUri = "$issuerUrl/jwks",
)
}metadata를 설정하면 초기 discovery 요청을 건너뛰고 해당 제공자에 대한 주기적 discovery 갱신이 비활성화됩니다. 이 경우 키 순환 이후를 포함하여 메타데이터를 최신 상태로 유지하는 책임은 애플리케이션에 있습니다.
정적 문서의 발급자는 여전히 구성된 issuer와 일치해야 합니다. JWKS 엔드포인트는 여전히 HTTP를 통해 액세스됩니다. 테스트 중에 이러한 요청을 방지하려면 외부 제공자 없이 테스트를 참고하세요.
토큰 유형
각 인증 체계는 특정 프린시펄(principal) 타입을 생성하므로, 라우트는 자신이 무엇을 보유하고 있는지 항상 알 수 있습니다:
| 체계 | 프린시펄 | 출처 |
|---|---|---|
provider.session | OidcToken.Id | 브라우저 로그인 |
provider.jwtBearer | OidcToken.Access | 로컬에서 검증된 JWT 액세스 토큰 |
provider.introspectionBearer | OidcToken.Introspected | 제공자가 확인한 액세스 토큰 |
OidcToken.Id 및 OidcToken.Access는 원시 JWT 클레임을 위한 claims와 subject, name, email과 같은 정규화된 사용자 필드를 위한 userInfo를 노출합니다. 반면 OidcToken.Introspected는 introspection을 노출합니다.
토큰을 애플리케이션 프린시펄에 매핑
라우트는 OIDC 토큰보다는 애플리케이션 전용 프린시펄을 사용하는 경우가 많습니다. .mapPrincipal() 함수를 사용하여 애플리케이션 타입을 생성하는 새로운 인증 체계를 만드세요:
data class AppUser(val id: String, val email: String?)
val apiAuth = google.jwtBearer.mapPrincipal { token ->
val id = token.claims.subject ?: return@mapPrincipal null
AppUser(id, token.userInfo?.email)
}
routing {
authenticateWith(apiAuth) {
get("/me") {
call.respond(call.principal.id)
}
}
}null을 반환하면 요청이 거부됩니다. 이 동작을 사용하여 해당하는 애플리케이션 계정이 더 이상 존재하지 않을 때 유효한 토큰을 거부할 수 있습니다.
프린시펄 매핑은 OAuth 콜백 중이 아니라 체계가 라우트를 인증할 때 실행됩니다. 예를 들어 로그인한 사용자가 나중에 데이터베이스에서 제거된 경우, 유효한 애플리케이션 세션을 유지하지 않고 다음 요청 시 사용자가 거부됩니다.
구성 파일에서 구성하기
클라이언트 시크릿(secret)은 소스 코드 대신 구성 파일에 저장하세요. 예를 들어, application.yaml 파일에 다음과 같이 작성합니다:
ktor:
oidc:
google:
issuer: "https://accounts.google.com"
clientId: "$GOOGLE_CLIENT_ID"
clientSecret: "$GOOGLE_CLIENT_SECRET"
scopes: ["openid", "profile", "email"]$GOOGLE_CLIENT_ID 및 $GOOGLE_CLIENT_SECRET은 환경 변수를 참조합니다.
구성 파일 작업에 대한 자세한 내용은 파일 구성을 참고하세요.
그런 다음 구성을 OidcEnvConfig로 읽어올 수 있습니다:
val env = environment.config
.property("ktor.oidc.google")
.getAs<OidcEnvConfig>()
val google = oidc.identityProvider("google") {
issuer = env.issuer
oauth {
clientId = env.clientId
clientSecret = env.clientSecret
scopes = env.scopes
}
}플러그인이 이 구성을 자동으로 로드하지는 않습니다. OidcEnvConfig는 값을 읽기 위한 편의 타입입니다. 값이 어디에서 오고 어떻게 적용되는지는 애플리케이션에서 결정합니다.
토큰 검증 구성
jwt {} 블록을 사용하여 토큰 검증 방식을 구성합니다. 기본 설정이 안전하므로 필요한 경우에만 변경하세요:
oidc.identityProvider("google") {
issuer = "https://accounts.google.com"
jwt {
clockSkew = 30.seconds
allowedAlgorithms = setOf(
SignatureAlgorithm.RSA_SHA_256
)
jwkCache(maxEntries = 10, duration = 1.hours)
jwkRateLimit(bucketSize = 10)
}
}clockSkew는exp및nbf에 적용되는 허용 오차를 지정합니다. 기본값은 60초입니다.allowedAlgorithms는 허용되는 서명 알고리즘을 제한합니다. 이 옵션이 설정되지 않은 경우, ID 토큰은 discovery 문서에 공지된 알고리즘으로 대체(fallback)됩니다. RSA 및 EC 알고리즘만 지정할 수 있습니다.jwkCache및jwkRateLimit는 JWKS 엔드포인트를 쿼리하는 빈도를 제어합니다. 속도 제한은 분당 10개 요청으로 기본 활성화되어 있습니다. 제한을 초과하면 토큰을 거부하는 대신OidcSigningKeyUnavailableException과 함께 요청이 실패합니다. 예상되는 최대 캐시 미스 트래픽을 수용할 수 있도록 제한을 구성하세요. 자세한 내용은 서버 측 검증 실패 처리를 참고하세요.
none 알고리즘과 모든 HMAC 알고리즘(HS256, HS384, HS512)은 구성과 관계없이 항상 거부됩니다. 공유 시크릿(shared secret)은 제3자가 발급한 토큰을 검증하기에 안전한 방법이 아닙니다.
jwkProviderFactory는 jwkCache 또는 jwkRateLimit와 함께 사용할 수 없습니다. 커스텀 JWK 제공자 팩토리를 제공하는 경우, 캐싱에 대한 책임은 애플리케이션에 있습니다.
외부 제공자 없이 테스트
OpenIdTestKeys는 인메모리 키 쌍을 생성하고 해당 키로 서명된 토큰을 발급합니다. 정적 메타데이터와 결합하면 네트워크 호출 없이도 실제 발급자, audience, 알고리즘 및 서명 검사를 실행하는 완전한 OIDC 설정을 구성할 수 있습니다:
@Test
fun `rejects a token for another audience`() = testApplication {
val issuerUrl = "https://test-issuer"
val keys = OpenIdTestKeys.rsa(
issuer = issuerUrl,
audience = "my-api"
)
application {
val oidc = install(Oidc)
val provider = oidc.identityProvider("test") {
issuer = issuerUrl
metadata = OpenIdProviderMetadata(
issuer = issuerUrl,
authorizationEndpoint = "$issuerUrl/authorize",
tokenEndpoint = "$issuerUrl/token",
jwksUri = "$issuerUrl/jwks",
)
jwt(keys)
bearer { audience = setOf("my-api") }
}
routing {
authenticateWith(provider.jwtBearer) {
get("/protected") {
call.respondText(call.principal.value)
}
}
}
}
val token = keys.accessToken {
subject = "user-1"
audience = "some-other-api"
}
val response = client.get("/protected") {
bearerAuth(token)
}
assertEquals(HttpStatusCode.Unauthorized, response.status)
}jwt(keys) 함수는 검증기가 인메모리 공개 키를 사용하도록 구성하고 허용된 알고리즘을 제한하므로 JWKS 요청이 발생하지 않습니다.
액세스 토큰을 생성할 때는 keys.accessToken { }을 사용하고, ID 토큰에는 keys.idToken(subject) { }를 사용하세요. 둘 다 issuer, audience, expiresAt 및 커스텀 claim() 값을 지원합니다.
EC 서명을 테스트하려면 rsa() 함수 대신 OpenIdTestKeys.ec() 함수를 사용하세요.
프로덕션 배포 전 보안 설정 검토
플러그인은 다음과 같은 기본 보안 설정을 적용합니다:
- PKCE는 모든 로그인에 활성화되며
S256을 사용합니다. - 권한 부여 상태는 유효 기간이 10분인 AES-256-GCM 암호화 쿠키에 저장됩니다.
- 세션 쿠키는
HttpOnly및SameSite=Lax로 설정되며, 개발 모드 외부에서는Secure가 적용됩니다. - 플러그인에 의해 생성된 라우트에 대해 CSRF 보호가 활성화됩니다.
- 모든 ID 토큰에서
nonce와at_hash가 검사됩니다.
프로덕션에 배포하기 전에 다음 설정을 검토하세요:
| 설정 | 기본값 | 변경해야 하는 이유 |
|---|---|---|
oauth { stateEncryptionKey } | 프로세스마다 새로운 무작위 키 | 재시작 시 진행 중이던 로그인이 중단되고 여러 인스턴스 간에 실패함 |
sessions { storage } | SessionStorageMemory() | 재시작 시 세션이 손실되며 인스턴스 간에 공유되지 않음 |
bearer { audience } | — | OAuth clientId가 포함되어서는 안 됨. 클라이언트 ID를 audience로 재사용하지 마세요 참고 |
initialDiscoveryAttempts | 1 | 제공자의 단 한 번의 느린 응답으로도 애플리케이션 시작이 실패할 수 있음 |
jwt { clockSkew } | 60.seconds | 시계가 정밀하게 동기화되어 있다면 값을 낮춤 |
discoveryRefreshInterval | 15.minutes | 제공자가 키를 자주 순환하는 경우 간격을 단축함 |
codeChallengeMethod | S256 | PKCE 활성화 유지 |
sessions { csrfProtection } | originMatchesHost() | CSRF 보호 활성화 유지 |
플러그인은 처음 세 가지 설정이 기본값으로 사용될 때 시작 시 경고를 기록합니다. 프로덕션 환경에서는 이러한 경고를 오류로 처리하는 것을 고려하세요.
구현된 사양
이 플러그인은 기능에 사용되는 권한 부여 코드 흐름(authorization code flow) 및 관련 사양을 구현합니다:
- OpenID Connect Core 1.0 —
nonce,azp,at_hash를 포함한 ID 토큰 유효성 검사 - OpenID Connect Discovery 1.0 — Discovery 작동 방식
- RP-Initiated Logout 1.0 — 사용자 로그아웃
- RFC 6749 §4.1 — 권한 부여 코드 흐름
- RFC 6750 — 베어러 토큰 및
WWW-Authenticate챌린지 - RFC 7636 — PKCE
- RFC 7662 — 토큰 내부 검사(token introspection)
- RFC 8707 — 리소스 지시자(resource indicators)
- RFC 9207 —
iss권한 부여 응답 매개변수 - RFC 9728 — 보호된 리소스 메타데이터
제한 사항
- 플러그인은 JVM에서만 사용할 수 있습니다.
- API는 실험적(experimental) 단계이며 변경될 수 있습니다.
- 권한 부여 코드 흐름만 지원됩니다. 암시적 흐름(implicit flow)과 하이브리드 흐름(hybrid flow)은 지원되지 않습니다.
- PKCE는
S256으로 고정되어 있습니다. 커스텀 챌린지 방식은 거부됩니다. - 암호화된(JWE) UserInfo 응답은 지원되지 않습니다.
- ID 토큰을 반환하지 않는 로그인 콜백은 지원되지 않습니다. OIDC를 구현하지 않은 제공자에 대해 액세스 토큰 전용 로그인을 사용하려면
oauth제공자를 사용하세요. - 내부 검사 엔드포인트(introspection endpoint)는 discovery에서 읽어오지 않습니다. 명시적으로 구성해야 합니다.
