일반 OAuth2 제공자

GitHub

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 지시를 복사합니다.

소개

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

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

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

필요한 것

OAuth 클라이언트 ID

앱 스키마 또는 웹 콜백 URL과 일치하는 리다이렉트 URL
인증화면 URL
인증 __CAPGO_KEEP_0__ 흐름을 위한 토큰 발급 URL 또는 OIDC 디스커버리 URL
A token endpoint for authorization code flow, or an issuerUrl 다중 제공자 설정
다중 제공자 설정 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 발견 및 별칭

제목이 issuerUrl OIDC 발견 문서를 노출하는 경우 제공자가 가장 단순한 설정입니다.

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 별칭도 지원합니다.

clientId 별칭으로 사용 appId
authorizationEndpoint 별칭으로 사용 authorizationBaseUrl
tokenEndpoint 별칭으로 사용 accessTokenEndpoint
endSessionEndpoint alias로 사용하는 이름 logoutUrl
scopes alias로 사용하는 이름 scope

또한 사용할 수 있는 옵션:

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

Auth Connect 호환 가능한 프리셋

Ionic Auth Connect에서 마이그레이션 중이고 동일한 제공자 이름을 유지하고 싶다면 사용 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

제공자가 커스텀 엔드포인트가 필요하다면, preset을 오버라이드하거나 preset을 우회하고 직접 제공자에 대한 구성으로 이동해야 합니다. oauth2.

구성 옵션

옵션	타입	필수	설명
`appId` / `clientId`	문자열	네	OAuth2 클라이언트 식별자
`issuerUrl`	string	No	OIDC 발굴 기본 URL
`authorizationBaseUrl` / `authorizationEndpoint`	string	Yes*	인증 엔드포인트 URL
`accessTokenEndpoint` / `tokenEndpoint`	string	No*	토큰 엔드포인트 URL
`redirectUrl`	string	Yes	콜백 URL
`scope` / `scopes`	string / string[]	없음	요청된 범위
`pkceEnabled`	boolean	없음	기본값으로 `true`
`responseType`	`'code'` 또는 `'token'`	없음	기본값으로 `'code'`
`resourceUrl`	string	없음	사용자 정보 또는 리소스 엔드포인트
`logoutUrl` / `endSessionEndpoint`	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__	로그아웃 URL
`postLogoutRedirectUrl`	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__	로그아웃 후 리다이렉트 URL
`additionalParameters`	`Record<string, string>`	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
`additionalTokenParameters`	`Record<string, string>`	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
`additionalResourceHeaders`	`Record<string, string>`	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__ `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	No	로그아웃 파라미터 추가
`loginHint`	문자열	No	Shortcut for `additionalParameters.login_hint`
`prompt`	문자열	No	Shortcut for `additionalParameters.prompt`
`iosPrefersEphemeralSession`	불리언	No	iOS에서 임시 브라우저 세션을 선호합니다
`logsEnabled`	불리언	No	verbose debug 로깅을 활성화합니다.

authorizationBaseUrl 그리고 accessTokenEndpoint 는 발견에만 선택적입니다. issuerUrl 는 발견된 값보다 항상 명시적인 엔드포인트가 우선합니다.

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

웹에서 리다이렉트 흐름

사용 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);
}

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

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

리프레시 토큰

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

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

refresh() Capgo 플러그인이 저장한 리프레시 토큰을 사용합니다. refreshToken() __CAPGO_KEEP_0__를 직접 전달하여 최신 OAuth2 응답을 반환합니다.

현재 접근 토큰을 가져옵니다.

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

console.log(code.accessToken);

제공자별 예제

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를 사용하면 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는 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 예시

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

제공자가 공개한 경우 제공자에게 사용할 수 있는 발견 /.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 로그인은 다음을 반환합니다.

Field	설정된 제공자 키를 사용하여 로그인
`providerId`	액세스 토큰 페이로드 또는
`accessToken`	OIDC ID 토큰이 제공자가 반환한 경우 `null`
`idToken`	만약 요청된 범위가 허용되면
`refreshToken`	리프레시 토큰
`resourceData`	Raw JSON fetched from `resourceUrl`
`scope`	__CAPGO_KEEP_0__
`tokenType`	일반적으로 `bearer`
`expiresIn`	__CAPGO_KEEP_0__ 초

Provider 설정 참고

GitHub

OAuth 앱을 생성하세요. 열기 GitHub 개발자 설정 그리고 새로운 OAuth 앱을 생성하세요.
콜백 URL을 설정하세요 앱 리다이렉트 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자연스럽게 또는 모바일 앱 등록을 생성하세요.
리다이렉트 URI를 추가하세요 앱 콜백 URL과 일치하는 모바일 또는 데스크톱 리다이렉트 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 대시보드 네이티브 앱을 생성하세요. 허용된 콜백 URL
허용된 콜백 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 관리 콘솔에서 OIDC 네이티브 애플리케이션을 생성하세요.
리다이렉트 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,
    },
  },
});

발견이 사용할 수 없다면, 인증 및 토큰 엔드포인트를 수동으로 구성하세요.

플랫폼별 참고사항

iOS

플러그인은 ASWebAuthenticationSession.
설정 iosPrefersEphemeralSession: true 사용자가 개인 브라우저 세션을 사용하고 공유 쿠키가 없으면

Android

OAuth redirect는 앱 스키마와 호스트를 통해 돌아옵니다.
Android의 깊이 연결 설정과 정확히 일치하는 제공자 callback URL을 확인하세요.
OAuth 활동은 플러그인이 이미 처리합니다. 앱이 다른 리다이렉트 패턴이 필요한 경우에만 사용자 정의 intent 필터를 추가하세요.

Web

Popup flow는 싱글 페이지 앱에 적합한 기본 흐름입니다.
제공자가 팝업을 차단하거나 인증 규칙이 상위 수준 탐색이 필요한 경우 Redirect flow를 사용하세요.
일부 제공자가 직접 브라우저 토큰 교환에 CORS를 차단하는 경우 백엔드 교환 또는 공공 클라이언트가 허용되는 제공자 설정을 사용하세요.

보안 최적화

PKCE 사용 보안을 위해 공개 클라이언트를 위해 유지하세요. pkceEnabled: true 권한 부여 __CAPGO_KEEP_0__ 흐름보다 안전한
Prefer authorization code flow responseType: 'code' 발급자, 대상, 만료, 및 서명 확인을 서버에서 디코딩하고 검증하세요.
리프레시 토큰을 안전하게 저장하세요. 자연어 앱의 경우 이 플러그인을
@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-persistent-account HTTPS를 사용하세요. @capgo/capacitor-persistent-account.
문제 해결 Prefer authorization __CAPGO_KEEP_0__ flow

is safer than implicit flow.

`providerId is required`

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

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

`OAuth2 provider "xxx" not configured`

Call SocialLogin.initialize() 로그인하기 전에 확인하세요. providerId matches the object key under oauth2.

Redirect URL이 일치하지 않습니다

앱과 제공자 대시보드에서 구성된 리다이렉트 URL을 문자별로 비교하세요.
끝에 슬래시가 있는지, 스킴이 일치하는지, 호스트가 다른지 확인하세요.
__CAPGO_KEEP_0__을(를) 모바일 앱 URL 스킴이 등록되기 전에 장치에서 테스트하기 전에 확인하세요.

__CAPGO_KEEP_0__ refresh token이 반환되지 않음

__CAPGO_KEEP_1__ refresh token은 대부분의 제공자가 scope와 같은 요청을 할 때만 반환합니다. 예를 들어, 또는 explicit consent를 강제로 동의할 때입니다. 제공자별 정책을 검토하세요. offline_access __CAPGO_KEEP_0__ token exchange를 디버깅하는 방법

__CAPGO_KEEP_0__ 제목: token exchange를 디버깅하는 방법

__CAPGO_KEEP_2__ logsEnabled: true __CAPGO_KEEP_0__ 제목: __CAPGO_KEEP_2__

Generic OAuth2 Providers에서 계속 진행

__CAPGO_KEEP_0__을 사용하시는 경우 Generic OAuth2 Providers 인증 및 계정 흐름을 계획하고 연결하려면 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-생체인증 for the implementation detail in @capgo/capacitor-native-생체인증, and 두 단계 인증 for the implementation detail in 두 단계 인증.

일반 OAuth2 제공자

소개

필요한 것

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

OIDC 발견 및 별칭

Auth Connect 호환 가능한 프리셋

구성 옵션

OAuth2 로그인을 사용합니다.

로그인

웹에서 리다이렉트 흐름

로그인 상태 및 로그아웃

리프레시 토큰

현재 접근 토큰을 가져옵니다.

제공자별 예제

GitHub 예제

Azure AD / Microsoft Entra ID 예제

Auth0 예시

Okta 예시

Keycloak 예시

OAuth2 응답 형태

Provider 설정 참고

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak 및 사용자 지정 OIDC 제공자

플랫폼별 참고사항

iOS

Android

Web

보안 최적화

is safer than implicit flow.

providerId is required

OAuth2 provider "xxx" not configured

Redirect URL이 일치하지 않습니다

__CAPGO_KEEP_0__ refresh token이 반환되지 않음

__CAPGO_KEEP_0__ 제목: token exchange를 디버깅하는 방법

__CAPGO_KEEP_3__ 시작하기

Generic OAuth2 Providers에서 계속 진행

`providerId is required`

`OAuth2 provider "xxx" not configured`