OAuth 2.0 프로토콜로 소셜 로그인을 설정하세요
OAuth 2.0 프로토콜을 위한 공식 Logto 커넥터입니다.
이 가이드는 Logto 커넥터에 대한 기본적인 이해를 전제로 합니다. 익숙하지 않은 분들은 커넥터 가이드를 참조하여 시작하세요.
시작하기
OAuth 커넥터는 OAuth 2.0 프로토콜을 지원하는 임의의 소셜 아이덴티티 제공자 (IdP)와 Logto의 연결을 가능하게 합니다. OAuth 커넥터를 사용하면 애플리케이션에서 다음을 할 수 있습니다:
- 소셜 로그인 버튼 추가
- 사용자 계정을 소셜 아이덴티티에 연결
- 소셜 제공자로부터 사용자 프로필 정보 동기화
- Logto Secret Vault에 안전하게 토큰을 저장하여 자동화 작업(예: Google Docs 편집, 앱에서 Calendar 이벤트 관리 등)을 위한 서드파티 API 접근
이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 OAuth 2.0 커넥터를 생성하세요:
- Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요.
- 소셜 커넥터 추가를 클릭하고, OAuth 2.0을 선택한 후 다음을 클릭하고 단계별 튜토리얼을 따라 통합을 완료하세요.
OAuth 커넥터는 Logto에서 특별한 종류의 커넥터로, 여러 개의 OAuth 프로토콜 기반 커넥터를 추가할 수 있습니다.
OAuth 앱 생성하기
이 페이지를 열었다면 이미 연결하고자 하는 소셜 아이덴티티 제공자 (IdP)를 알고 있다고 생각합니다. 가장 먼저 해야 할 일은 해당 아이덴티티 제공자가 OAuth 프로토콜을 지원하는지 확인하는 것입니다. 이는 유효한 커넥터를 구성하기 위한 전제 조건입니다. 그런 다음, 아이덴티티 제공자의 안내에 따라 OAuth 인가를 위한 관련 앱을 등록 및 생성하세요.
커넥터 구성하기
보안상의 이유로 "Authorization Code" 그랜트 타입만 지원하며, 이는 Logto의 시나리오에 완벽하게 적합합니다.
clientId와 clientSecret은 OAuth 앱의 상세 페이지에서 확인할 수 있습니다.
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: scope 파라미터는 클라이언트 애플리케이션이 접근을 요청하는 리소스 및 권한의 집합을 지정하는 데 사용됩니다. scope 파라미터는 일반적으로 특정 권한을 나타내는 값들의 공백으로 구분된 목록으로 정의됩니다. 예를 들어, "read write"라는 scope 값은 클라이언트 애플리케이션이 사용자의 데이터에 대한 읽기 및 쓰기 권한을 요청함을 나타낼 수 있습니다.
authorizationEndpoint, tokenEndpoint, userInfoEndpoint는 소셜 벤더의 문서에서 확인할 수 있습니다.
authenticationEndpoint: 이 엔드포인트는 인증 프로세스를 시작하는 데 사용됩니다. 인증 프로세스는 일반적으로 사용자가 로그인하고, 클라이언트 애플리케이션이 자신의 리소스에 접근할 수 있도록 인가를 부여하는 과정을 포함합니다.
tokenEndpoint: 이 엔드포인트는 클라이언트 애플리케이션이 요청한 리소스에 접근할 수 있는 액세스 토큰을 얻는 데 사용됩니다. 클라이언트 애플리케이션은 일반적으로 그랜트 타입과 인가 코드를 포함한 요청을 토큰 엔드포인트로 전송하여 액세스 토큰을 받습니다.
userInfoEndpoint: 이 엔드포인트는 클라이언트 애플리케이션이 사용자에 대한 추가 정보(예: 전체 이름, 이메일 주소, 프로필 사진 등)를 얻는 데 사용됩니다. user info 엔드포인트는 일반적으로 클라이언트 애플리케이션이 토큰 엔드포인트에서 액세스 토큰을 얻은 후 접근합니다.
Logto는 또한 사용자가 소셜 벤더의 표준화되지 않은 프로필에서 매핑을 커스터마이즈할 수 있도록 profileMap 필드를 제공합니다. 키는 Logto의 표준 사용자 프로필 필드명이고, 값은 소셜 프로필의 필드명이어야 합니다. 현재 단계에서는 Logto가 소셜 프로필에서 'id', 'name', 'avatar', 'email', 'phone'만 신경 쓰며, 'id'만 필수이고 나머지는 선택 필드입니다.
responseType과 grantType은 authorization code grant type에서만 고정 값이 될 수 있으므로, 선택 사항으로 두고 기본값이 자동으로 채워집니다.
예를 들어, Google 사용자 프로필 응답을 참고하면, 해당 profileMap은 다음과 같아야 합니다:
{
"id": "sub",
"avatar": "picture"
}
사용자 정의 파라미터를 넣을 수 있도록 선택적 customConfig 키를 제공합니다.
각 소셜 아이덴티티 제공자는 OAuth 표준 프로토콜에 대해 자체 변형을 가질 수 있습니다. 만약 원하는 소셜 아이덴티티 제공자가 OAuth 표준 프로토콜을 엄격히 준수한다면, customConfig는 신경 쓰지 않아도 됩니다.
구성 타입
| 이름 | 타입 | 필수 여부 |
|---|---|---|
| authorizationEndpoint | string | true |
| userInfoEndpoint | string | true |
| clientId | string | true |
| clientSecret | string | true |
| tokenEndpointResponseType | enum | false |
| responseType | string | false |
| grantType | string | false |
| tokenEndpoint | string | false |
| scope | string | false |
| customConfig | Record<string, string> | false |
| profileMap | ProfileMap | false |
| ProfileMap 필드 | 타입 | 필수 여부 | 기본값 |
|---|---|---|---|
| id | string | false | id |
| name | string | false | name |
| avatar | string | false | avatar |
| string | false | ||
| phone | string | false | phone |
일반 설정
아이덴티티 제공자와의 연결을 막지는 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다.
소셜 버튼 이름 및 로고
로그인 페이지에 소셜 버튼을 표시하고 싶다면, 소셜 아이덴티티 제공자의 이름과 로고(다크 모드 및 라이트 모드)를 설정할 수 있습니다. 이를 통해 사용자가 소셜 로그인 옵션을 쉽게 인식할 수 있습니다.
아이덴티티 제공자 이름
각 소셜 커넥터는 사용자 아이덴티티를 구분하기 위한 고유한 아이덴티티 제공자 (IdP) 이름을 가집니다. 일반 커넥터는 고정된 IdP 이름을 사용하지만, 커스텀 커넥터는 고유한 값을 필요로 합니다. 자세한 내용은 IdP 이름에서 확인하세요.
프로필 정보 동기화
OAuth 커넥터에서는 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요:
- 회원가입 시에만 동기화: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다.
- 로그인 시마다 항상 동기화: 사용자가 로그인할 때마다 프로필 정보가 업데이트됩니다.
타사 API 접근을 위한 토큰 저장 (선택 사항)
아이덴티티 제공자의 API에 접근하여 사용자 인가로 작업을 수행하려면(소셜 로그인 또는 계정 연동을 통해), Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다.
- 위의 안내에 따라 scope 필드에 필요한 스코프를 추가하세요.
- Logto OAuth 커넥터에서 지속적인 API 접근을 위한 토큰 저장을 활성화하세요. Logto는 액세스 토큰을 Secret Vault에 안전하게 저장합니다.
- 표준 OAuth/OIDC 아이덴티티 제공자의 경우, 리프레시 토큰을 얻으려면
offline_access스코프를 반드시 포함해야 하며, 이를 통해 반복적인 사용자 동의 요청을 방지할 수 있습니다.
클라이언트 시크릿을 안전하게 보관하고, 절대 클라이언트 사이드 코드에 노출하지 마세요. 유출 시, 즉시 아이덴티티 제공자의 앱 설정에서 새로 발급받으세요.
OAuth 커넥터 활용하기
OAuth 커넥터를 생성하고 아이덴티티 제공자와 연결했다면, 이를 엔드유저 플로우에 통합할 수 있습니다. 필요에 맞는 옵션을 선택하세요:
소셜 로그인 버튼 활성화
- Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요.
- 소셜 로그인 섹션에서 OAuth 커넥터를 추가하여 사용자가 아이덴티티 제공자로 인증 (Authentication)할 수 있도록 하세요.
소셜 로그인 경험에 대해 더 알아보세요.
소셜 계정 연결 또는 연결 해제
Account API를 사용하여 앱 내에 커스텀 계정 센터를 구축하고, 로그인한 사용자가 소셜 계정을 연결하거나 연결 해제할 수 있도록 하세요. Account API 튜토리얼을 참고하세요.
소셜 로그인을 활성화하지 않고, 계정 연동 및 API 접근만을 위해 OAuth 커넥터를 활성화하는 것도 가능합니다.
아이덴티티 제공자 API 접근 및 작업 수행
애플리케이션은 Secret Vault에서 저장된 액세스 토큰을 가져와 아이덴티티 제공자의 API를 호출하고 백엔드 작업을 자동화할 수 있습니다. 구체적인 기능은 아이덴티티 제공자와 요청한 스코프에 따라 다릅니다. API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요.
사용자의 소셜 아이덴티티 관리
사용자가 소셜 계정을 연결한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다:
- Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다.
- 소셜 연결 항목에서 아이덴티티 제공자 항목을 찾아 관리를 클릭하세요.
- 이 페이지에서 관리자는 사용자의 소셜 연결을 관리하고, 소셜 계정에서 부여 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 상태를 점검할 수 있습니다.
일부 아이덴티티 제공자의 액세스 토큰 응답에는 특정 스코프 정보가 포함되어 있지 않아, Logto가 사용자가 부여한 권한 목록을 직접 표시할 수 없습니다. 그러나 사용자가 인가 과정에서 요청된 스코프에 동의했다면, 애플리케이션은 OAuth API 접근 시 해당 권한을 갖게 됩니다.