범용 OAuth2 프로바이더

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

소개

Capgo Social Login 플러그인에는 OAuth2 및 OpenID Connect 엔진이 내장되어 있습니다. 이를 통해 다음과 같은 표준 기반의 ID 제공업체(Identity Provider)를 연결할 수 있습니다:

GitHub
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
커스텀 OAuth2 또는 OIDC 서버

이 oauth2 설정은 설계 단계부터 멀티 프로바이더를 지원합니다. 여러 프로바이더를 동시에 등록한 뒤, 로그인 시점에 다음을 통해 하나를 선택할 수 있습니다: providerId.

준비 사항

프로바이더를 설정하기 전에 다음 항목을 준비하세요:

OAuth client ID
앱 스킴(scheme) 또는 웹 콜백 URL과 일치하는 redirect URL
authorization endpoint
인증 code 흐름을 위한 token endpoint 또는 issuerUrl OIDC discovery를 위한 endpoint
앱에 필요한 scope (예:) openid profile email

멀티 프로바이더 설정

사용 SocialLogin.initialize() 앱 시작 시 한 번 실행하여 필요한 모든 프로바이더를 등록하세요:

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
    auth0: {
      issuerUrl: 'https://your-tenant.auth0.com',
      appId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

OIDC discovery 및 별칭

제공업체에서 OpenID Connect discovery 문서를 제공한다면, issuerUrl 가장 간단한 설정 방법입니다:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

이 플러그인은 일반적인 OAuth 및 OIDC aliases도 지원합니다:

clientId 의 alias로 appId
authorizationEndpoint 의 alias로 authorizationBaseUrl
tokenEndpoint 의 alias로 accessTokenEndpoint
endSessionEndpoint 의 alias로 logoutUrl
scopes 의 alias로 scope

다음 기능도 사용 가능:

additionalParameters 인증 요청 오버라이드용
additionalTokenParameters 토큰 교환 오버라이드용
additionalResourceHeaders 커스텀 리소스 엔드포인트 헤더용
additionalLogoutParameters 및 postLogoutRedirectUrl 로그아웃 플로우용
loginHint, prompt, 그리고 iosPrefersEphemeralSession

Auth Connect 호환 프리셋

Ionic Auth Connect에서 마이그레이션하며 기존 provider 이름을 유지하려면 다음을 사용하세요: SocialLoginAuthConnect.

import { SocialLoginAuthConnect } from '@capgo/capacitor-social-login';

await SocialLoginAuthConnect.initialize({
  authConnect: {
    auth0: {
      domain: 'https://your-tenant.auth0.com',
      clientId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      audience: 'https://your-api.example.com',
    },
    azure: {
      tenantId: 'common',
      clientId: 'your-azure-client-id',
      redirectUrl: 'myapp://oauth/azure',
    },
    okta: {
      issuer: 'https://dev-12345.okta.com/oauth2/default',
      clientId: 'your-okta-client-id',
      redirectUrl: 'myapp://oauth/okta',
    },
  },
});

지원되는 프리셋 provider ID:

auth0
azure
cognito
okta
onelogin

제공업체에 커스텀 엔드포인트가 필요한 경우, 프리셋에서 이를 재정의하거나 프리셋을 건너뛰고 다음에서 제공업체를 직접 구성하세요: oauth2.

설정 옵션

옵션	유형	필수	설명
`appId` / `clientId`	string	지원	OAuth2 클라이언트 식별자
`issuerUrl`	string	아니요	OIDC discovery 기본 URL
`authorizationBaseUrl` / `authorizationEndpoint`	string	예*	Authorization 엔드포인트 URL
`accessTokenEndpoint` / `tokenEndpoint`	string	아니요*	Token 엔드포인트 URL
`redirectUrl`	string	지원	콜백 URL
`scope` / `scopes`	OAuth2를 이용한 소셜 로그인 구현하기	아니요	요청할 scope
`pkceEnabled`	boolean	아니요	기본값 `true`
`responseType`	`'code'` 또는 `'token'`	아니요	기본값 `'code'`
`resourceUrl`	string	아니요	사용자 정보 또는 리소스 엔드포인트
`logoutUrl` / `endSessionEndpoint`	string	아니요	로그아웃 또는 세션 종료 URL
`postLogoutRedirectUrl`	string	아니요	로그아웃 후 리다이렉트 URL
`additionalParameters`	`Record<string, string>`	아니요	추가 인증 요청 파라미터
`additionalTokenParameters`	`Record<string, string>`	아니요	추가 토큰 요청 파라미터
`additionalResourceHeaders`	`Record<string, string>`	아니요	추가 헤더 `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	아니요	추가 로그아웃 파라미터
`loginHint`	string	아니요	바로가기 `additionalParameters.login_hint`
`prompt`	string	아니요	바로가기 `additionalParameters.prompt`
`iosPrefersEphemeralSession`	boolean	아니요	iOS에서 일회성 브라우저 세션 사용
`logsEnabled`	boolean	아니요	상세 디버그 로그 활성화

authorizationBaseUrl 및 accessTokenEndpoint 의 경우에만 선택 사항입니다. issuerUrl 를 통해 discovery하기에 충분합니다. 명시적인 엔드포인트는 항상 discovery된 값보다 우선합니다.

const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
    loginHint: 'user@example.com',
  },
});

웹 리다이렉트 흐름

사용 flow: 'redirect' 팝업 대신 전체 페이지 리다이렉트를 사용하려면:

await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

콜백을 받는 페이지에서 로그인 결과를 파싱하세요:

const result = await SocialLogin.handleRedirectCallback();
if (result?.provider === 'oauth2') {
  console.log(result.result.providerId);
}

const status = await SocialLogin.isLoggedIn({
  provider: 'oauth2',
  providerId: 'github',
});

await SocialLogin.logout({
  provider: 'oauth2',
  providerId: 'github',
});

Refresh token

await SocialLogin.refresh({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

const refreshed = await SocialLogin.refreshToken({
  provider: 'oauth2',
  providerId: 'github',
  refreshToken: 'existing-refresh-token',
});

refresh() 플러그인에 저장된 refresh token을 사용합니다. refreshToken() refresh token을 직접 전달하여 새로운 OAuth2 응답을 받을 수 있습니다.

현재 access token 가져오기

const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});

console.log(code.accessToken);

Provider별 예시

GitHub 예시

간단한 OAuth 앱 흐름과 기본 프로필 데이터가 필요한 경우 GitHub를 사용하세요:

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
  },
});

const githubResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

console.log(githubResult.result.accessToken?.token);
console.log(githubResult.result.resourceData);

Azure AD / Microsoft Entra ID 예시

사용자 프로필과 같은 Microsoft Graph 데이터가 필요한 경우 Azure를 사용하세요:

await SocialLogin.initialize({
  oauth2: {
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
  },
});

const azureResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'azure',
  },
});

console.log(azureResult.result.idToken);
console.log(azureResult.result.resourceData);

Auth0 예제

OIDC와 함께 커스텀 API audience가 필요한 경우 Auth0가 적합합니다:

await SocialLogin.initialize({
  oauth2: {
    auth0: {
      appId: 'your-auth0-client-id',
      authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
      accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

const auth0Result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

웹에서 redirect flow를 사용하는 경우, 콜백 페이지에서 결과를 다시 읽어오세요:

const auth0Result = await SocialLogin.handleRedirectCallback();
if (auth0Result?.provider === 'oauth2') {
  console.log(auth0Result.result.idToken);
}

Okta 예제

await SocialLogin.initialize({
  oauth2: {
    okta: {
      appId: 'your-okta-client-id',
      authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
      accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
      redirectUrl: 'myapp://oauth/okta',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
    },
  },
});

const oktaResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'okta',
  },
});

console.log(oktaResult.result.resourceData);

Keycloak 예제

제공업체에서 discovery를 게시하는 경우 사용하세요 /.well-known/openid-configuration:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

const keycloakResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'keycloak',
  },
});

console.log(keycloakResult.result.idToken);

OAuth2 응답 구조

OAuth2 로그인 성공 시 반환되는 값:

필드	설명
`providerId`	로그인에 사용된 provider key 설정값
`accessToken`	Access token 페이로드 또는 `null`
`idToken`	provider가 반환한 경우 OIDC ID token
`refreshToken`	요청한 scope가 허용된 경우 Refresh token
`resourceData`	다음에서 가져온 Raw JSON: `resourceUrl`
`scope`	승인된 scope
`tokenType`	보통 `bearer`
`expiresIn`	토큰 수명(초)

Provider 설정 참조

GitHub

OAuth 앱 생성 열기 GitHub 개발자 설정 그리고 새 OAuth App을 생성하세요.
Callback URL 설정 앱의 redirect URL을 사용하세요. 예: myapp://oauth/github.

플러그인 설정하기

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
  },
});

Azure AD / Microsoft Entra ID

앱 등록하기 Azure Portal로 이동하여 다음을 여세요: App registrations, 그 다음 native 또는 mobile 앱 등록을 생성합니다.
리다이렉트 URI 추가 앱의 callback URL과 일치하는 mobile 또는 desktop 리다이렉트 URI를 추가하세요.

플러그인 설정하기

await SocialLogin.initialize({
  oauth2: {
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
  },
});

Auth0

네이티브 애플리케이션 생성 다음을 엽니다: Auth0 대시보드 및 Native app을 생성합니다.
허용된 콜백 URL 설정 Capacitor 앱에서 사용하는 정확한 리다이렉트 URL을 추가하세요.

플러그인 설정

await SocialLogin.initialize({
  oauth2: {
    auth0: {
      appId: 'your-auth0-client-id',
      authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
      accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
      logoutUrl: 'https://your-tenant.auth0.com/v2/logout',
    },
  },
});

Okta

OIDC 네이티브 앱 생성하기 Okta Admin Console에서 OIDC Native Application을 생성하세요.
리다이렉트 URI 추가 앱에서 사용하는 콜백 URL을 정확하게 등록하세요.

플러그인 설정

await SocialLogin.initialize({
  oauth2: {
    okta: {
      appId: 'your-okta-client-id',
      authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
      accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
      redirectUrl: 'myapp://oauth/okta',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
    },
  },
});

Keycloak 및 커스텀 OIDC 제공업체

제공업체가 OpenID Connect discovery를 지원한다면, issuerUrl:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

Discovery를 사용할 수 없는 경우, authorization 및 token 엔드포인트를 수동으로 설정하세요.

플랫폼별 참고 사항

iOS

이 플러그인은 다음을 사용합니다: ASWebAuthenticationSession.
설정 iosPrefersEphemeralSession: true 쿠키를 공유하지 않는 프라이빗 브라우저 세션이 필요한 경우 사용하세요.

Android

OAuth 리디렉션은 앱의 scheme과 host를 통해 반환됩니다.
Provider callback URL이 Android deep link 설정과 정확히 일치하는지 확인하세요.
플러그인이 OAuth activity를 이미 처리합니다. 앱에 다른 redirect 패턴이 필요한 경우에만 custom intent filter를 추가하세요.

웹

Popup flow가 기본 방식이며, SPA(Single-Page App)에서 잘 작동합니다.
Provider가 팝업을 차단하거나 인증 규칙상 top-level navigation이 필요한 경우 Redirect flow가 더 적합합니다.
일부 Provider는 CORS로 인해 브라우저에서의 직접적인 token exchange를 차단합니다. 이 경우 backend exchange를 사용하거나 public client를 허용하는 Provider 설정을 사용하세요.

보안 모범 사례

PKCE 사용 유지하세요 pkceEnabled: true public client의 경우.
code 인증 flow 권장 responseType: 'code' implicit flow보다 안전합니다.
백엔드에서 토큰 검증 서버 측에서 issuer, audience, expiration, signature를 디코딩하고 검증하세요.
refresh token을 안전하게 저장 네이티브 앱의 경우, 이 플러그인을 다음 제품과 함께 사용하세요: @capgo/capacitor-persistent-account.
모든 구간에 HTTPS 사용 운영 환경의 auth 및 logout 엔드포인트는 항상 HTTPS를 사용해야 합니다.

문제 해결

`providerId is required`

모든 OAuth2 방식에는 설정된 provider key가 필요합니다:

await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'github' },
});

`OAuth2 provider "xxx" not configured`

호출하세요 SocialLogin.initialize() 로그인 전에 확인하고, providerId 다음의 object key와 일치하는지 확인하세요: oauth2.

Redirect URL 불일치

앱에 설정된 redirect URL과 provider dashboard의 URL을 글자 하나하나 대조해 보세요.
끝에 붙는 슬래시(/), scheme 불일치, 호스트 차이를 주의 깊게 확인하세요.
기기에서 테스트하기 전에 모바일 앱의 URL scheme이 등록되었는지 확인하세요.

Refresh token이 반환되지 않았습니다

대부분의 프로바이더는 다음과 같은 scope를 요청하거나 offline_access 사용자 동의를 명시적으로 강제할 때만 refresh token을 반환합니다. 각 프로바이더의 정책을 확인하세요.

Token exchange 디버깅

활성화 logsEnabled: true 프로바이더 설정에서 생성된 URL과 token exchange 상세 내용을 확인하세요.

Generic OAuth2 Providers에서 계속하기

사용 중이라면 일반 OAuth2 프로바이더 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-social-login 사용하기 @capgo/capacitor-social-login 사용 시 네이티브 기능을 위해, @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증의 구현 세부 사항에 대해서는