본문으로 건너뛰기
Capgo - Capacitor 앱에 대한 실시간 업데이트 Capgo

일반 OAuth2 제공자

GitHub

소개

제목이 '소개'인 섹션

Capgo 소셜 로그인 플러그인은 내장된 OAuth2 및 OpenID Connect 엔진을 포함합니다. 어떤 표준 기반의 식별 제공자와도 연결할 수 있습니다. 예를 들어:

  • GitHub
  • Azure AD / Microsoft Entra ID
  • Auth0
  • Okta
  • Keycloak
  • 사용자 정의 OAuth2 또는 OIDC 서버

설정은 여러 제공자에 의해 디자인되었습니다. 한 번에 여러 제공자를 등록하고 로그인 시에 하나를 선택할 수 있습니다. oauth2 필요한 것 providerId.

제공자 설정을 하기 전에 다음을 준비하세요:

OAuth 클라이언트 ID

앱 스키마 또는 웹 콜백 URL과 일치하는 리다이렉트 URL

  • 인증화면
  • 인증 흐름을 위한 토큰 엔드포인트 또는 OIDC 디스커버리
  • 앱이 필요로 하는 범위, 예를 들어
  • A token endpoint for authorization code flow, or an issuerUrl __CAPGO_KEEP_0__
  • __CAPGO_KEEP_0__ openid profile email

__CAPGO_KEEP_0__

Multi-provider configuration 설정

사용 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 및 Aliases

OIDC discovery 및 Aliases 설정

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 라는 Aliases로 appId
  • authorizationEndpoint 라는 Aliases로 authorizationBaseUrl
  • tokenEndpoint Capgo의 별칭으로 accessTokenEndpoint
  • endSessionEndpoint Capgo의 별칭으로 logoutUrl
  • scopes Capgo의 별칭으로 scope

또한 사용할 수 있는 옵션:

  • additionalParameters 인증 요청 오버라이드용
  • additionalTokenParameters 토큰 교환 오버라이드용
  • additionalResourceHeaders 사용자 정의 리소스 엔드포인트 헤더용
  • additionalLogoutParameters 그리고 postLogoutRedirectUrl 로그아웃 흐름용
  • loginHint, prompt, 그리고 iosPrefersEphemeralSession

인증 연결 호환 프리셋

인증 연결 호환 프리셋 섹션

If you are migrating from Ionic Auth Connect and want to keep the same provider names, use 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',
    },
  },
});

지원하는 preset 제공자 ID:

  • auth0
  • azure
  • cognito
  • okta
  • onelogin

If a provider needs custom endpoints, either override them in the preset or bypass presets and configure the provider directly in oauth2.

설정 옵션

설정 옵션
옵션타입필수설명
appId / clientId문자열예__CAPGO_KEEP_0__
issuerUrl문자열아니오__CAPGO_KEEP_1__
authorizationBaseUrl / authorizationEndpoint문자열예*__CAPGO_KEEP_2__
accessTokenEndpoint / tokenEndpoint문자열아니오*__CAPGO_KEEP_3__
redirectUrl문자열예콜백 URL
scope / scopes__CAPGO_KEEP_0__ / __CAPGO_KEEP_0__[]아니오요청된 범위
pkceEnabled__CAPGO_KEEP_0__아니오기본값 true
responseType'code' 또는 'token'아니오기본값 'code'
resourceUrl__CAPGO_KEEP_0__아니오사용자 정보 또는 리소스 엔드포인트
logoutUrl / endSessionEndpoint__CAPGO_KEEP_0____CAPGO_KEEP_0__로그아웃 또는 세션 종료 URL
postLogoutRedirectUrl__CAPGO_KEEP_0____CAPGO_KEEP_0__로그아웃 후 리다이렉트 URL
additionalParametersRecord<string, string>__CAPGO_KEEP_0____CAPGO_KEEP_0__
additionalTokenParametersRecord<string, string>추가 인증 요청 매개 변수__CAPGO_KEEP_0__
additionalResourceHeadersRecord<string, string>__CAPGO_KEEP_0__추가 헤더를 위한 resourceUrl
additionalLogoutParametersRecord<string, string>아니오추가 로그아웃 파라미터
loginHint문자열아니오단축키를 위한 additionalParameters.login_hint
prompt문자열아니오단축키를 위한 additionalParameters.prompt
iosPrefersEphemeralSession부울아니오iOS에서 임시 브라우저 세션을 선호합니다
logsEnabledbooleanNoverbose debug 로깅을 활성화합니다.

authorizationBaseUrl 밖에 accessTokenEndpoint 는 발견에 충분합니다. 명시적 엔드포인트는 항상 발견된 값보다 우선합니다. issuerUrl OAuth2 로그인을 사용합니다.

OAuth2 로그인을 사용하는 방법

로그인

로그인

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

__CAPGO_KEEP_0__

Redirect flow on web

Use flow: 'redirect' if you want a full-page redirect instead of a popup:

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

On the page that receives the callback, parse the login result:

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

Login status and logout

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


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

Section titled “Login status and logout”

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


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

refresh() refresh token을 저장한 플러그인이 저장한 refresh token을 사용합니다. refreshToken() refresh token을 직접 전달하고 새 OAuth2 응답을 반환합니다.

현재 접근 토큰 가져오기

현재 접근 토큰 가져오기
const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});


console.log(code.accessToken);

제공자별 예제

제공자별 예제

GitHub 예제

GitHub 예제

GitHub를 사용하여 간단한 OAuth 앱 흐름과 기본 프로필 데이터를 얻으려면:

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 예제

Azure AD / Microsoft Entra ID 예시 섹션

Azure AD / Microsoft Entra ID를 사용하면 Microsoft Graph 데이터를 사용할 수 있습니다. 예를 들어 사용자 프로필을 사용할 수 있습니다.

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 예시

Auth0 예시 섹션

Auth0는 OIDC와 사용자 지정 API 대상이 필요한 경우 적합합니다.

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',
  },
});

웹에서 리다이렉트 플로우를 사용하는 경우 콜백 페이지에서 결과를 다시 읽어야 합니다.

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

Okta 예시

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 예시

Keycloak 예시 섹션

제공자가 공개할 때는 발견을 사용하세요. /.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 응답 형태 섹션

OAuth2 로그인 성공 시 반환:

필드설명
providerId로그인에 사용되는 구성된 제공자 키
accessToken액세스 토큰 페이로드 또는 null
idTokenOIDC ID 토큰 제공자가 반환한 경우
refreshToken__CAPGO_KEEP_0__
resourceData__CAPGO_KEEP_0__ resourceUrl
scope__CAPGO_KEEP_0__
tokenType__CAPGO_KEEP_0__ bearer
expiresIn__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

GitHub

GitHub

  1. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ GitHub __CAPGO_KEEP_0__을 생성하고 OAuth 앱을 만들세요.

  2. __CAPGO_KEEP_0__ 설정 URL을 설정하세요. __CAPGO_KEEP_0__ 앱 리다이렉트 URL을 사용하세요. 예를 들어 myapp://oauth/github.

  3. __CAPGO_KEEP_0__ 플러그인을 구성하세요.

    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 AD / Microsoft Entra ID 섹션

  1. __CAPGO_KEEP_0__을 등록하세요. Azure Portal로 이동하여 App registrations, native 또는 모바일 앱 등록을 생성하세요.

  2. __CAPGO_KEEP_0__을 추가하세요. 모바일 또는 데스크톱 리다이렉트 URI를 추가하세요. 이 URI는 앱 callback URL과 일치해야 합니다.

  3. 설정 플러그인을 구성하세요.

    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라는 제목의 섹션

  1. 자연어 애플리케이션을 생성하세요. Open the Auth0 대시보드 Native 앱을 생성하세요.

  2. __CAPGO_KEEP_0__ 앱이 사용하는 정확한 callback URL을 설정하세요. Capacitor 앱이 사용하는 정확한 리다이렉트 URL을 추가하세요.

  3. 플러그인을 구성하세요.

    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

Okta 섹션

  1. OIDC 네이티브 앱을 생성하세요. Okta Admin Console에서 OIDC 네이티브 애플리케이션을 생성하세요.

  2. 리다이렉트 URI를 추가하세요. __CAPGO_KEEP_0__ 앱이 사용하는 정확한 callback URL을 등록하세요.

  3. 플러그인을 구성하세요.

    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',
        },
      },
    });

__CAPGO_KEEP_0__ 및 사용자 정의 OIDC 제공자

__CAPGO_KEEP_0__ 및 사용자 정의 OIDC 제공자 섹션

OpenID Connect discovery를 지원하는 제공자가 있다면 __CAPGO_KEEP_0__을 선호하세요. 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,
    },
  },
});

OpenID Connect discovery가 사용할 수 없다면, 인증 및 토큰 엔드포인트를 수동으로 구성하세요.

플랫폼별 참고사항

__CAPGO_KEEP_0__ 플랫폼별 참고사항

iOS

__CAPGO_KEEP_0__
  • 플러그인은 ASWebAuthenticationSession.
  • __CAPGO_KEEP_0__ iosPrefersEphemeralSession: true 만약 개인 브라우저 세션을 사용하고 싶다면 공유 쿠키가 없는 세션을 사용하세요.

안드로이드

‘안드로이드’라는 제목을 가진 섹션
  • OAuth 리다이렉트는 앱 스키마와 호스트를 통해 돌아옵니다.
  • Android의 깊이 링크 설정과 정확히 일치하는 제공자 callback URL을 확인하세요.
  • OAuth 활동은 플러그인이 이미 처리합니다. 앱이 다른 리다이렉트 패턴이 필요한 경우에만 사용자 정의 인텐트 필터를 추가하세요.

웹

‘웹’이라는 제목을 가진 섹션
  • 싱글 페이지 앱에 적합한 기본값으로 팝업 흐름이 작동합니다.
  • 제공자가 팝업을 차단하거나 인증 규칙이 상위 수준의 탐색이 필요할 때 리다이렉트 흐름이 더 좋습니다.
  • 일부 제공자가 CORS로 직접 브라우저 토큰 교환을 차단하는 경우 백엔드 교환 또는 공공 클라이언트가 허용되는 제공자 설정을 사용하세요.

안전한 사용 방법

‘안전한 사용 방법’이라는 제목을 가진 섹션

  1. PKCE 사용 __CAPGO_KEEP_0__를 유지하세요. pkceEnabled: true 공개 클라이언트용입니다.

  2. 인증 code 흐름을 선호하세요. responseType: 'code' 암묵적 흐름보다 안전합니다.

  3. 토큰을 백엔드에서 검증하세요. 발급자, 대상자, 만료일, 서명 등을 서버에서 디코딩하고 검증하세요.

  4. 리프레시 토큰을 안전하게 저장하세요. 네이티브 앱의 경우 이 플러그인을 @capgo/capacitor-persistent-account와 pair하세요..

  5. HTTPS를 사용하세요. 인증 및 로그아웃 엔드포인트는 항상 HTTPS를 사용하세요.

문제 해결

제목: 문제 해결

providerId is required

제목: providerId가 필요합니다

모든 OAuth2 메소드는 구성된 제공자 키가 필요합니다:

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

OAuth2 provider "xxx" not configured

제목: OAuth2 제공자 "xxx"이 구성되지 않았습니다

호출 SocialLogin.initialize() 로그인하기 전에 providerId providerId가 oauth2.

matches the object key under

URL이 일치하지 않습니다
  • 제목: URL이 일치하지 않습니다
  • 끝 슬래시, 스키마 불일치 및 호스트가 다른 경우 감시하십시오.
  • 모바일 앱 URL 스키마가 기기에서 테스트하기 전에 등록되어 있는지 확인하십시오.

refresh 토큰이 반환되지 않음

제목: 'refresh 토큰이 반환되지 않음'

대부분의 제공자들은 scope와 같은 'or'로 명시적으로 동의를 강제할 때 refresh 토큰만 반환합니다. 제공자별 정책을 검토하십시오. offline_access 토큰 교환 디버깅

제목: '토큰 교환 디버깅'

켜기

provider config에서 생성된 URL 및 토큰 교환 세부 정보를 검사하기 위해 사용하십시오. logsEnabled: true 관련 문서

__CAPGO_KEEP_0__

일반 OAuth2 제공자에서 계속하기

일반 OAuth2 제공자에서 계속하기 섹션 제목

일반 OAuth2 제공자에서 계속하기 섹션 제목 일반 OAuth2 제공자에서 계속하기 섹션 제목 일반 OAuth2 제공자에서 계속하기 섹션 제목 Using @capgo/capacitor-social-login for the native capability in Using @capgo/capacitor-social-login, @capgo/capacitor-social-login for the implementation detail in @capgo/capacitor-social-login, @capgo/capacitor-passkey @capgo/capacitor-passkey, @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric, and 두 단계 인증 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-biometric, and