OpenID Connect (OIDC) 소셜 로그인을 설정하세요
OpenID Connect (OIDC) 프로토콜을 위한 공식 Logto 커넥터입니다.
이 가이드는 Logto 커넥터에 대한 기본적인 이해를 전제로 합니다. 익숙하지 않은 분들은 커넥터 가이드를 참조하여 시작하세요.
시작하기
OIDC 커넥터를 사용하면 Logto가 OIDC 프로토콜을 지원하는 임의의 소셜 아이덴티티 제공자와 연결할 수 있습니다. OIDC 커넥터를 사용하여 애플리케이션에서 다음을 할 수 있습니다:
- 소셜 로그인 버튼 추가
- 사용자 계정을 소셜 아이덴티티에 연결
- 소셜 제공자로부터 사용자 프로필 정보 동기화
- Logto Secret Vault에 안전하게 토큰을 저장하여 자동화 작업(예: Google Docs 편집, 앱에서 Calendar 이벤트 관리 등)을 위한 서드파티 API에 접근
이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 OIDC 커넥터를 생성하세요:
- Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요.
- 소셜 커넥터 추가를 클릭하고, OIDC를 선택한 후 다음을 클릭하고 단계별 튜토리얼을 따라 통합을 완료하세요.
OIDC 커넥터는 Logto에서 특별한 종류의 커넥터로, 여러 개의 OIDC 프로토콜 기반 커넥터를 추가할 수 있습니다.
OIDC 앱 생성하기
이 페이지를 열었을 때, 이미 연결하고자 하는 소셜 아이덴티티 제공자 (IdP)를 알고 있다고 가정합니다. 가장 먼저 해야 할 일은 해당 아이덴티티 제공자가 OIDC 프로토콜을 지원하는지 확인하는 것입니다. 이는 유효한 커넥터를 구성하기 위한 전제 조건입니다. 그런 다음, 아이덴티티 제공자의 안내에 따라 OIDC 인가를 위한 관련 앱을 등록 및 생성하세요.
커넥터 구성하기
보안상의 이유로 "Authorization Code" 그랜트 타입만 지원하며, 이는 Logto의 시나리오에 완벽하게 부합합니다.
clientId와 clientSecret은 OIDC 앱의 상세 페이지에서 확인할 수 있습니다.
clientId: 클라이언트 ID는 인가 서버에 등록할 때 클라이언트 애플리케이션을 식별하는 고유 식별자입니다. 이 ID는 인가 서버가 클라이언트 애플리케이션의 아이덴티티를 확인하고, 인가된 액세스 토큰을 해당 클라이언트 애플리케이션과 연관시키는 데 사용됩니다.
clientSecret: 클라이언트 시크릿은 인가 서버가 등록 시 클라이언트 애플리케이션에 발급하는 비밀 키입니다. 클라이언트 애플리케이션은 이 시크릿 키를 사용하여 인가 서버에 액세스 토큰을 요청할 때 자신을 인증합니다. 클라이언트 시크릿은 기밀 정보로 간주되며 항상 안전하게 보관해야 합니다.
tokenEndpointAuthMethod: 토큰 엔드포인트 인증 방식은 클라이언트 애플리케이션이 액세스 토큰을 요청할 때 인가 서버에 자신을 인증하는 데 사용됩니다. 지원되는 방식을 확인하려면 OAuth 2.0 서비스 제공자의 OpenID Connect 디스커버리 엔드포인트에서 token_endpoint_auth_methods_supported 필드를 참조하거나, 해당 OAuth 2.0 서비스 제공자의 관련 문서를 확인하세요.
clientSecretJwtSigningAlgorithm (선택 사항): tokenEndpointAuthMethod가 client_secret_jwt인 경우에만 필요합니다. 클라이언트 시크릿 JWT 서명 알고리즘은 토큰 요청 중 클라이언트 애플리케이션이 인가 서버에 전송하는 JWT를 서명하는 데 사용됩니다.
scope: 스코프 파라미터는 클라이언트 애플리케이션이 접근을 요청하는 리소스와 권한의 집합을 지정하는 데 사용됩니다. 스코프 파라미터는 일반적으로 특정 권한을 나타내는 값들을 공백으로 구분한 목록으로 정의됩니다. 예를 들어, "read write"라는 스코프 값은 클라이언트 애플리케이션이 사용자의 데이터에 대한 읽기 및 쓰기 접근을 요청함을 나타낼 수 있습니다.
authorizationEndpoint, tokenEndpoint, jwksUri, issuer는 OpenID 제공자의 구성 정보로, 소셜 벤더의 문서에서 확인할 수 있습니다.
authenticationEndpoint: 이 엔드포인트는 인증 (Authentication) 프로세스를 시작하는 데 사용됩니다. 인증 과정은 일반적으로 사용자가 로그인하고, 클라이언트 애플리케이션이 리소스에 접근할 수 있도록 인가를 부여하는 과정을 포함합니다.
tokenEndpoint: 이 엔드포인트는 클라이언트 애플리케이션이 요청한 리소스에 접근할 수 있는 ID 토큰을 얻는 데 사용됩니다. 클라이언트 애플리케이션은 일반적으로 그랜트 타입과 인가 코드를 포함한 요청을 토큰 엔드포인트에 보내 ID 토큰을 받습니다.
jwksUri: 이 URL 엔드포인트는 소셜 아이덴티티 제공자 (IdP)의 JSON Web Key Set (JWKS)을 얻을 수 있는 위치입니다. JWKS는 IdP가 인증 (Authentication) 과정에서 발급하는 JSON Web Token (JWT)을 서명하고 검증하는 데 사용하는 암호화 키 집합입니다. jwksUri는 신뢰 당사자 (RP)가 IdP가 JWT를 서명하는 데 사용하는 공개 키를 얻는 데 사용되며, 이를 통해 RP는 IdP로부터 받은 JWT의 진위와 무결성을 검증할 수 있습니다.
issuer: 이는 RP가 IdP로부터 받은 JWT를 검증하는 데 사용하는 IdP의 고유 식별자입니다. JWT에는 iss 클레임 (Claim)으로 포함되어 있습니다 (ID 토큰은 항상 JWT입니다). issuer 값은 IdP의 인가 서버 URL과 일치해야 하며, RP가 신뢰하는 URI여야 합니다. RP가 JWT를 수신하면, iss 클레임을 확인하여 신뢰할 수 있는 IdP가 발급했는지, JWT가 RP에서 사용하기 위한 것인지 확인합니다.
jwksUri와 issuer는 RP가 인증 (Authentication) 과정에서 최종 사용자의 아이덴티티를 검증할 수 있는 안전한 메커니즘을 제공합니다. RP는 jwksUri에서 얻은 공개 키를 사용하여 IdP가 발급한 JWT의 진위와 무결성을 검증할 수 있습니다. issuer 값은 RP가 신뢰하는 IdP가 발급한 JWT만 허용하고, JWT가 RP에서 사용하기 위한 것임을 보장합니다.
항상 인증 요청이 필요하므로, 모든 선택적 구성을 래핑하는 authRequestOptionalConfig가 제공됩니다. 자세한 내용은 OIDC 인증 요청에서 확인할 수 있습니다. 또한 이 구성에 nonce가 없는 것을 볼 수 있습니다. nonce는 각 요청마다 달라야 하므로, nonce 생성은 코드 구현에 포함되어 있습니다. 걱정하지 않으셔도 됩니다! 앞서 언급한 jwksUri와 issuer도 idTokenVerificationConfig에 포함되어 있습니다.
표준 OIDC 프로토콜이 암시적(implicit) 및 하이브리드(hybrid) 플로우를 모두 지원하는데, 왜 Logto 커넥터는 인가 플로우만 지원하는지 궁금할 수 있습니다. 암시적 및 하이브리드 플로우는 인가 플로우보다 보안성이 떨어지는 것으로 판단되었습니다. Logto는 보안을 중시하기 때문에, 사용자에게 최고의 보안 수준을 제공하기 위해 약간의 불편함이 있더라도 인가 플로우만 지원합니다.
responseType과 grantType은 "Authorization Code" 플로우에서만 고정 값이 될 수 있으므로, 선택 사항으로 두고 기본값이 자동으로 채워집니다.
모든 플로우 타입에 대해, 맞춤형 파라미터를 넣을 수 있도록 선택적 customConfig 키를 제공합니다.
각 소셜 아이덴티티 제공자는 OIDC 표준 프로토콜에 대해 자체 변형을 가질 수 있습니다. 만약 원하는 소셜 아이덴티티 제공자가 OIDC 표준 프로토콜을 엄격히 준수한다면, customConfig는 신경 쓰지 않으셔도 됩니다.
구성 타입
| 이름 | 타입 | 필수 여부 |
|---|---|---|
| scope | string | True |
| clientId | string | True |
| clientSecret | string | True |
| authorizationEndpoint | string | True |
| tokenEndpoint | string | True |
| idTokenVerificationConfig | IdTokenVerificationConfig | True |
| authRequestOptionalConfig | AuthRequestOptionalConfig | False |
| customConfig | Record<string, string> | False |
| AuthRequestOptionalConfig 속성 | 타입 | 필수 여부 |
|---|---|---|
| responseType | string | False |
| tokenEndpoint | string | False |
| responseMode | string | False |
| display | string | False |
| prompt | string | False |
| maxAge | string | False |
| uiLocales | string | False |
| idTokenHint | string | False |
| loginHint | string | False |
| acrValues | string | False |
| IdTokenVerificationConfig 속성 | 타입 | 필수 여부 |
|---|---|---|
| jwksUri | string | True |
| issuer | string | string[] | False |
| audience | string | string[] | False |
| algorithms | string[] | False |
| clockTolerance | string | number | False |
| crit | Record<string, string | boolean> | False |
| currentDate | Date | False |
| maxTokenAge | string | number | False |
| subject | string | False |
| typ | string | False |
IdTokenVerificationConfig에 대한 자세한 내용은 여기에서 확인하세요.
일반 설정
다음은 아이덴티티 제공자와의 연결을 막지는 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다.
소셜 버튼 이름 및 로고
로그인 페이지에 소셜 버튼을 표시하고 싶다면, 소셜 아이덴티티 제공자의 이름과 로고(다크 모드 및 라이트 모드)를 설정할 수 있습니다. 이를 통해 사용자가 소셜 로그인 옵션을 쉽게 인식할 수 있습니다.
아이덴티티 제공자 이름
각 소셜 커넥터는 사용자 아이덴티티를 구분하기 위해 고유한 아이덴티티 제공자 (IdP) 이름을 가집니다. 일반 커넥터는 고정된 IdP 이름을 사용하지만, 커스텀 커넥터는 고유한 값을 필요로 합니다. 자세한 내용은 IdP 이름에서 확인하세요.
프로필 정보 동기화
OIDC 커넥터에서는 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요:
- 회원가입 시 한 번만 동기화: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다.
- 로그인 시마다 항상 동기화: 사용자가 로그인할 때마다 프로필 정보를 업데이트합니다.
타사 API 접근을 위한 토큰 저장 (선택 사항)
아이덴티티 제공자의 API에 접근하여 사용자 인가로 작업(소셜 로그인 또는 계정 연결을 통해)을 수행하려면, Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다.
- 위의 안내에 따라 scope 필드에 필요한 스코프를 추가하세요.
- Logto OIDC 커넥터에서 지속적인 API 접근을 위한 토큰 저장을 활성화하세요. Logto는 액세스 토큰을 Secret Vault에 안전하게 저장합니다.
- 표준 OAuth/OIDC 아이덴티티 제공자의 경우, 리프레시 토큰을 얻으려면
offline_access스코프를 반드시 포함해야 하며, 이를 통해 반복적인 사용자 동의 요청을 방지할 수 있습니다.
클라이언트 시크릿을 안전하게 보관하고, 절대 클라이언트 측 코드에 노출하지 마세요. 유출 시, 즉시 아이덴티티 제공자의 앱 설정에서 새로 발급받으세요.
OIDC 커넥터 활용하기
OIDC 커넥터를 생성하고 아이덴티티 제공자와 연결한 후, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요:
소셜 로그인 버튼 활성화
- Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요.
- 소셜 로그인 섹션에서 OIDC 커넥터를 추가하여 사용자가 아이덴티티 제공자로 인증 (Authentication)할 수 있도록 하세요.
소셜 로그인 경험에 대해 더 알아보세요.
소셜 계정 연결 또는 연결 해제
Account API를 사용하여 앱 내에 맞춤형 계정 센터를 구축하고, 로그인한 사용자가 소셜 계정을 연결하거나 연결 해제할 수 있도록 하세요. Account API 튜토리얼을 따라하세요
소셜 로그인을 활성화하지 않고, 계정 연결 및 API 접근만을 위해 OIDC 커넥터를 활성화하는 것도 가능합니다.
아이덴티티 제공자 API 접근 및 작업 수행
애플리케이션은 Secret Vault에서 저장된 액세스 토큰을 가져와 아이덴티티 제공자의 API를 호출하고 백엔드 작업을 자동화할 수 있습니다. 구체적인 기능은 아이덴티티 제공자와 요청한 스코프에 따라 다릅니다. API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요.
사용자의 소셜 아이덴티티 관리
사용자가 소셜 계정을 연결한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다:
- Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다.
- 소셜 연결 섹션에서 아이덴티티 제공자 항목을 찾아 관리를 클릭하세요.
- 이 페이지에서 관리자는 사용자의 소셜 연결을 관리하고, 소셜 계정에서 부여 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 상태를 확인할 수 있습니다.
일부 아이덴티티 제공자의 액세스 토큰 응답에는 특정 스코프 정보가 포함되어 있지 않으므로, Logto가 사용자가 부여한 권한 목록을 직접 표시할 수 없습니다. 그러나 사용자가 인가 과정에서 요청된 스코프에 동의한 경우, 애플리케이션은 OIDC API에 접근할 때 해당 권한을 갖게 됩니다.