Generic OAuth2 제공자

GitHub

복사할 수 있는 프롬프트에서 설치 단계와 이 플러그인에 대한 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.

소개

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

GitHub
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
Custom OAuth2 or OIDC 서버

The oauth2 구성은 여러 제공자 등록을 허용하기 위해 다중 제공자 디자인입니다. 여러 제공자 등록 후 로그인 시에 하나 선택할 수 있습니다. providerId.

What you need

구성자 제공자 전후에 다음을 준비하세요:

OAuth 클라이언트 ID
앱 스키마 또는 웹 콜백 URL에 맞는 리다이렉트 URL
인증화면 URL
인증 code 흐름을 위한 토큰 인증 URL 또는 OIDC 디스커버리 issuerUrl for OIDC discovery
앱이 필요로 하는 범위 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 발견 및 별칭

제공자가 OpenID Connect 발견 문서를 노출한다면 가장 단순한 설정입니다: 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,
    },
  },
});

__CAPGO_KEEP_0__

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

또한 사용 가능합니다.

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

인증 연결 호환 프리셋

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

지원하는 프리셋 제공자 ID:

auth0
azure
cognito
okta
onelogin

제공자가 커스텀 엔드포인트가 필요하다면, 프리셋에서 Override하거나, 프리셋을 우회하고 직접 제공자를 oauth2.

설정 옵션

옵션	타입	필수	설명
`appId` / `clientId`	소셜 로그인 플러그인	예	OAuth2 클라이언트 식별자
`issuerUrl`	문자열	아니오	OIDC 발견 기초 URL
`authorizationBaseUrl` / `authorizationEndpoint`	문자열	예*	인증화면 URL
`accessTokenEndpoint` / `tokenEndpoint`	문자열	아니오*	토큰화면 URL
`redirectUrl`	string	예	콜백 URL
`scope` / `scopes`	string / string[]	아니오	요청된 범위
`pkceEnabled`	boolean	아니오	기본값으로 `true`
`responseType`	`'code'` 또는 `'token'`	아니오	기본값으로 `'code'`
`resourceUrl`	소셜 로그인 플러그인	아니요	사용자 정보 또는 리소스 엔드포인트
`logoutUrl` / `endSessionEndpoint`	문자열	아니요	로그아웃 또는 세션 종료 URL
`postLogoutRedirectUrl`	문자열	아니요	로그아웃 후 리다이렉트 URL
`additionalParameters`	`Record<string, string>`	아니요	추가 인증 요청 매개 변수
`additionalTokenParameters`	`Record<string, string>`	아니요	추가 토큰 요청 매개 변수
`additionalResourceHeaders`	`Record<string, string>`	아니요	추가 헤더를 위한 `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	아니요	로그아웃에 대한 추가 매개 변수
`loginHint`	문자열	아니요	단축 버전 `additionalParameters.login_hint`
`prompt`	문자열	아니요	단축 버전 `additionalParameters.prompt`
`iosPrefersEphemeralSession`	부울	없음	iOS에서 임시 브라우저 세션을 선호합니다.
`logsEnabled`	boolean	없음	verbose한 디버그 로깅을 활성화합니다.

authorizationBaseUrl 그리고 accessTokenEndpoint 만약 issuerUrl 충분히 발견되면

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

로그인 상태 및 로그아웃

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

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

refresh() 이 플러그인이 저장한 새로 고침 토큰을 사용합니다. refreshToken() __CAPGO_KEEP_0__을 사용하여 간단한 OAuth 앱 흐름과 기본 프로필 데이터를 얻으려면:

현재 접근 토큰 가져오기

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

console.log(code.accessToken);

__CAPGO_KEEP_0__ 예시

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 그래프 데이터(사용자 프로필 등)를 필요로 할 때 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 대상이 필요한 경우 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',
  },
});

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

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 로그인은 다음과 같이 반환됩니다.

필드	설명
`providerId`	사용자가 로그인한 후에 사용하는 로그인 제공자 키
`accessToken`	액세스 토큰 페이로드 또는 `null`
`idToken`	OIDC ID 토큰이 제공자가 반환한 경우
`refreshToken`	리프레시 토큰이 요청된 범위가 허용한 경우
`resourceData`	직접 가져온 Raw JSON `resourceUrl`
`scope`	허용된 범위
`tokenType`	일반적으로 `bearer`
`expiresIn`	토큰 유효 시간(초)

제공자 설정 참고

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자연어 또는 모바일 앱 등록을 생성하세요
Redirect URI를 추가하세요 모바일 또는 데스크톱 앱 callback URL과 일치하는 Redirect 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 대시보드 자연어 앱을 만들기 위해
허용된 callback 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 자연어 앱을 만들세요.
리다이렉트 URI 추가 앱에서 사용하는 정확한 callback 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가 사용할 수 없다면, 인증 및 토큰 엔드포인트를 수동으로 설정하세요.

플랫폼별 참고사항

iOS

플러그인은 ASWebAuthenticationSession.
설정 iosPrefersEphemeralSession: true 개인 브라우저 세션을 사용하고 쿠키를 공유하지 않는 경우에 대한 설정

안드로이드

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

웹

팝업 흐름은 싱글 페이지 앱에 잘 작동합니다.
리다이렉트 흐름은 제공자가 팝업을 차단하거나 인증 규칙이 상위 수준 탐색이 필요할 때 더 좋습니다.
일부 제공자가 직접 브라우저 토큰 교환에 CORS를 차단하는 경우, 백엔드 교환 또는 공공 클라이언트가 허용되는 제공자 설정을 사용하세요.

보안 최적화 방법

PKCE 사용 보안 pkceEnabled: true 공개 클라이언트용
인증 code 흐름을 사용하세요 responseType: 'code' 암묵적 흐름보다 안전합니다.
토큰을 백엔드에서 검증하세요 발급자, 대상자, 만료일, 서명 등을 서버에서 디코딩하고 검증하세요.
리프레시 토큰을 안전하게 저장하세요 네이티브 앱의 경우 이 플러그인을 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-persistent-account와 pair하세요 @capgo/capacitor-persistent-account.
HTTPS를 사용하세요 생산 환경의 인증 엔드포인트와 로그아웃 엔드포인트는 항상 HTTPS를 사용해야 합니다.

문제 해결

`providerId is required`

OAuth2 메서드의 모든 경우에는 구성된 제공자 키가 필요합니다.

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

`OAuth2 provider "xxx" not configured`

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

객체 키 아래에 맞춥니다. Redirect URL이 일치하지 않습니다.

앱 및 제공자 대시보드에서 구성된 리다이렉트 URL을 문자별로 비교하십시오.
끝에 슬래시가 있는지, 스킴이 일치하는지, 호스트가 다른지 확인하십시오.
모바일 앱 URL 스킴이 등록된 후 기기에서 테스트하기 전에 확인하십시오.

refresh 토큰이 반환되지 않음

refresh 토큰이 반환되는 경우 대부분의 제공자는 scope가 포함된 경우 또는 명시적으로 동의를 강제할 경우에만 반환됩니다. 제공자별 정책을 검토하십시오. offline_access 토큰 교환 디버깅

제공자 구성에서

생성된 URL 및 토큰 교환 세부 정보를 검토하기 위해 logsEnabled: true 켜십시오.

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

일반 OAuth2 제공자를 사용하여 인증 및 계정 흐름을 계획하고 일반 OAuth2 제공자와 연결하여 Using @capgo/capacitor-social-login Using @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, 그리고 두 단계 인증 구현 세부 정보는 두 단계 인증 에서 찾을 수 있습니다.

Generic OAuth2 제공자

소개

What you need

다중 제공자 구성

OIDC 발견 및 별칭

인증 연결 호환 프리셋

설정 옵션

explicit한 엔드포인트는 항상 발견된 값보다 우선합니다.

OAuth2 로그인 사용

웹에서 리다이렉트 흐름

로그인 상태 및 로그아웃

로그인 상태 및 로그아웃

현재 접근 토큰 가져오기

__CAPGO_KEEP_0__ 예시

GitHub 예시

Azure AD / Microsoft Entra ID 예시

Auth0 예시

Okta 예시

Keycloak 예시

OAuth2 응답 형태

제공자 설정 참고

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak 및 사용자 정의 OIDC 제공자

플랫폼별 참고사항

iOS

안드로이드

웹

보안 최적화 방법

문제 해결

providerId is required

OAuth2 provider "xxx" not configured

객체 키 아래에 맞춥니다. Redirect URL이 일치하지 않습니다.

refresh 토큰이 반환되지 않음

제공자 구성에서

관련 문서

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

`providerId is required`

`OAuth2 provider "xxx" not configured`