한국어
OpenID Connect 설정 탐구: 주요 필드와 그 사용법
OpenID Connect 설정의 주요 필드와 실용적인 활용에 대해 탐구합니다.
Yijun
Developer
Developer
OpenID Connect 설정의 주요 필드와 실용적인 활용에 대해 탐구합니다.
오늘날의 디지털 세계에서는 인증이 웹사이트와 애플리케이션의 보안을 확보하는 데 중심적인 요소가 되었습니다. OAuth 2.0 프로토콜 위에 구축된 인증 계층인 OpenID Connect(OIDC)는 신원을 인증하는 표준화되고 간단한 방법을 제공합니다.
그러나 OIDC를 제대로 통합하는 것은 특히 초보자에게는 어려울 수 있습니다. 좋은 출발점은 대개 {authServerUrl}/.well-known/openid-configuration URL에 위치한 OIDC 설정 파일로, OIDC 서비스를 구현하는 데 필요한 모든 세부 정보를 포함하고 있습니다.
이 가이드는 이 설정 내 주요 필드를 명확히 하여 개발자들이 그 중요성과 실용적인 적용을 이해하고, 자신의 프로젝트에 OIDC를 더 잘 통합할 수 있도록 도와줍니다.
OIDC 설정은 다음과 같은 JSON 파일과 비슷합니다:
다음으로, 몇 가지 주요 필드를 더 깊이 파헤쳐 보겠습니다.
OIDC 서비스를 통합할 때, 첫 번째 단계는 일반적으로 애플리케이션 내에서 사용자 로그인 요청을 처리하는 것입니다. 이 과정에는 사용자를 인증을 위해 로그인 페이지로 안내하는 인증 서버의 authorization_endpoint로 리디렉션하는 것이 포함됩니다. 이 엔드포인트는 인증 요청이 전송되는 서버 주소로, 사용자를 로그인 페이지로 안내하여 인증을 수행하게 합니다.
authorization_endpoint에 요청을 보낼 때, 인증마다 추가적으로 구성해야 할 쿼리 매개변수들이 있습니다:
response_type: 반환되는 인증 유형을 지정합니다. 일반적으로 "code"(인증 코드 흐름), "token"(암묵적 흐름) 및 "id_token token" 또는 "code id_token"(하이브리드 흐름) 등이 포함되며, 이는 OIDC 설정의 response_types_supported 필드에서 찾아볼 수 있습니다.client_id: 애플리케이션이 등록될 때 인증 서버에 의해 할당된 고유 식별자입니다. 이 ID는 인증 요청을 시작하는 클라이언트 애플리케이션을 인증 서버가 인식하는 데 사용됩니다.scope: 요청된 접근 범위를 정의하여 접근 가능한 리소스 또는 사용자 정보를 명시합니다. 일반적인 스코프에는 "openid"(필수), "profile", "email" 등이 포함됩니다. 지원되는 스코프는 OIDC 설정의 scopes_supported 필드에서 확인할 수 있으며, 서로 다른 스코프는 공백으로 구분해야 합니다.redirect_uri: 로그인이나 인증 후에 인증 서버가 애플리케이션이 제공한 URI로 사용자를 다시 리디렉션합니다. 이 URI는 애플리케이션이 등록된 URI와 정확히 일치해야 합니다.state: 크로스 사이트 요청 위조(CSRF) 공격을 방지하기 위해 사용되는 임의로 생성된 문자열입니다. 요청 시의 상태와 콜백 간에 일관성을 유지하여 보안을 확보해야 합니다.이러한 매개변수들은 개발자가 OIDC 인증 요청의 동작을 정확하게 제어하여 보안성을 확보하고, 애플리케이션의 요구에 부합하도록 할 수 있게 해 줍니다.
authorization_endpoint로의 요청을 완료하고 인증을 통과하면, 사용자는 지정된 redirect_uri로 리디렉션되며, 여기에는 매우 중요한 쿼리 매개변수인 code가 포함됩니다. 이 인증 코드는 사용자가 인증하고 애플리케이션이 인증 서버에서 그들의 정보를 액세스하도록 승인한 결과 인증 서버에서 제공됩니다.
token_endpoint는 앞서 언급한 인증 코드를 액세스 및 리프레시 토큰으로 교환하기 위해 인증 서버가 사용하는 서버 엔드포인트입니다. OAuth 2.0 인증 코드 흐름에서 이 단계는 얻은 인증 코드를 실제 액세스 토큰으로 전환하는 중요한 단계로, 애플리케이션에서 사용자의 보호된 리소스에 액세스할 수 있도록 합니다.
여기서 인증 코드를 액세스 토큰으로 교환하는 방법을 구현한 예를 볼 수 있습니다(이 예는 client_secret_post 인증 방법을 사용합니다. 지원되는 다른 인증 방법은
token_endpoint_auth_methods_supported이 코드에서는 먼저 POST 메소드를 사용하여 token_endpoint로 요청을 보냅니다. 컨텐츠 유형은 대부분의 인증 서버에서 요구하는 application/x-www-form-urlencoded로 설정됩니다. 요청 본문에는 다음과 같은 매개변수가 포함됩니다:
code: 인증 서버에서 얻은 인증 코드로, 사용자가 인증을 완료한 후 redirectUri를 통해 반환됩니다.redirect_uri: 인증 코드를 얻기 위해 사용된 동일한 리디렉션 URI로, 요청의 합법성을 검증하는 데 사용됩니다.client_id: 애플리케이션의 클라이언트 식별자로, 요청을 실행하는 애플리케이션을 식별하는 데 사용됩니다.client_secret: 애플리케이션의 클라이언트 비밀번호로, 애플리케이션의 신원을 확인하는 데 사용됩니다.grant_type: 인증 유형을 지정하며, 여기서는 "authorization_code"를 사용하여 인증 코드를 통해 액세스 토큰을 얻습니다.이 함수는 비동기적으로 실행되며, 애플리케이션에서 사용자 데이터를 요청하거나 다른 작업을 수행하는 데 사용할 수 있는 액세스 토큰을 포함하는 JSON 객체를 반환합니다.
userinfo_endpoint는 인증 서버에서 인증된 사용자에 대한 자세한 정보를 얻기 위해 사용하는 서버 엔드포인트입니다. 사용자가 token_endpoint를 통해 액세스 토큰을 성공적으로 획득한 후, 애플리케이션은 이 엔드포인트에 요청을 보내 사용자 프로필 정보(예: 사용자 이름 또는 이메일 주소)를 액세스할 수 있습니다. 구체적으로 액세스되는 정보는 인증 요청에서 사용자가 지정한 scope에 따라 달라집니다.
이 함수에서는 먼저 GET 메소드를 사용하여 userinfo_endpoint를 호출하며, 요청 헤더에 Authorization 필드로 token_type과 accessToken을 포함시킵니다. 이는 OAuth 2.0 명세서에 따른 표준 작업으로, 사용자 정보를 안전하게 가져오는 데 사용됩니다. 추가적으로, 액세스 토큰을 통해 액세스되는 사용자 정보의 범위는 전적으로 사용자가 인증을 시작할 때 채택한 scope 매개변수 값에 따라 다릅니다. 예를 들어, email 스코프를 사용하면 응답에 사용자의 이메일 주소가 포함되어야 합니다.
issuer는 인증 서버의 URL을 식별하며, jwks_uri는 JSON Web Key Set (JWKS)에 대한 URI를 제공합니다. JWKS는 JWT 서명을 검증하는 데 사용되는 공용 키 집합입니다. JWT의 issuer 및 서명을 검증하는 것은 보안 토큰을 확보하는 기본 단계이지만, 실제 시나리오에서는 대개 토큰의 유효 기간, 대상, 인증 범위 및 기타 중요한 필드를 확인하는 과정도 포함됩니다.
다음 코드는 JWT를 검증하기 위해 issuer 및 jwks_uri를 함께 사용하는 방법을 주로 보여줍니다:
claims_supported와 scopes_supported 필드는 인증 서버에서 지원하는 사용자 속성(클레임)과 접근 범위(스코프)를 선언합니다. 이들은 클라이언트가 인증 요청을 효과적으로 구성하고 응답을 분석할 수 있도록 도와줍니다.
인증 요청을 작성할 때, 클라이언트는 애플리케이션의 필요에 따라 필요한 scope를 지정할 수 있습니다. scope는 클라이언트가 접근을 요청하는 리소스와 작업을 정의하며, 예를 들어 openid, email, profile 등이 있습니다.
여기서 중요한 점은 각 인증 요청에서 접근 가능한 구체적인 클레임은 인증 요청 시작 시 지정된 scope 값에 따라 다르다는 것입니다. 예를 들어, 이메일 스코프를 사용하면 사용자의 이메일 주소에 접근할 수 있으며, 전화 스코프를 사용하면 사용자의 전화 번호에 접근할 수 있습니다. 따라서 클라이언트는 인증 요청을 작성할 때 애플리케이션의 필요에 맞춰 관련된 스코프를 신중히 선택하여 필요로 하는 사용자 속성을 확보할 수 있도록 해야 합니다:
token_endpoint_auth_methods_supportedtoken_endpoint_auth_methods_supported토큰 엔드포인트를 통해 인증할 때, 일반적인 인증 방법에는 client_secret_post, client_secret_basic 및 client_secret_jwt가 포함됩니다.
client_secret_post: 클라이언트는 클라이언트 식별자와 클라이언트 비밀번호를 사용하여 양식 인코딩된 본문을 구성하며, 이는 요청 본문의 일부로 전송됩니다. 이미 위의 token_endpoint 섹션에서 이 방법의 예를 보았습니다.
client_secret_basic: 클라이언트는 클라이언트 식별자와 클라이언트 비밀번호를 사용하여 기본 인증 헤더를 구성하며, 이는 요청 헤더에 추가됩니다.
client_secret_jwt: 클라이언트는 클라이언트 주장을 위해 JWT(JSON 웹 토큰)를 사용하여 인증합니다. 이 JWT에는 클라이언트 식별자와 일부 추가 메타데이터가 포함되며, 클라이언트 비밀번호로 서명됩니다. 요청을 받으면 인증 서버는 JWT의 서명을 검증하여 클라이언트의 신원을 확인합니다.실질적인 애플리케이션에서는 클라이언트가 인증 서버에서 지원하는 방법에 따라 적절한 인증 방법을 선택하고, 인증 정보를 요청에 정확히 추가하여 인증 코드를 액세스 토큰으로 안전하게 교환해야 합니다.
이제 우리는 OIDC 설정의 주요 필드를 탐구하며, 그 목적과 응용에 중점을 두었습니다. 이러한 세부 사항을 이해함으로써 OpenID Connect에 대한 이해도를 높이고, 이를 프로젝트에 더 효과적으로 통합하고 활용할 수 있게 됩니다. 이 지식을 바탕으로, OIDC의 잠재력을 최대한 활용하여 더 안전하고 효율적인 사용자 인증 솔루션을 구현할 수 있습니다.
OIDC 위에 구축된 인증 서비스인 Logto는 다양한 언어로 된 포괄적인 SDK 세트와 수많은 통합 튜토리얼을 제공하여, OAuth / OIDC 로그인을 애플리케이션에 몇 분 만에 원활하게 통합할 수 있도록 해줍니다. 신뢰할 수 있고 사용하기 쉬운 OIDC 서비스를 찾고 있다면 오늘 Logto를 시도해 보세요!