일반 OAuth2 제공자

소개

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

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

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

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

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

• 인증화면 URL
• 인증을 위한 토큰 엔드포인트 또는 OIDC 디스커버리
• 앱이 필요로 하는 범위, 예를 들어
• A token endpoint for authorization code flow, or an issuerUrl configuration is multi-provider by design. You can register several providers at once and then select one at login time with
• What you need openid profile email

Before you configure a provider, collect:

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

별칭으로

• clientId 별칭으로 appId
• authorizationEndpoint __CAPGO_KEEP_0__ authorizationBaseUrl
• tokenEndpoint alias로 사용하는 이름 accessTokenEndpoint
• endSessionEndpoint alias로 사용하는 이름 logoutUrl
• scopes alias로 사용하는 이름 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	문자열	예	OAuth2 클라이언트 식별자
issuerUrl	string	No	OIDC 디스커버리 베이스 URL
authorizationBaseUrl / authorizationEndpoint	string	Yes*	인증 엔드포인트 URL
accessTokenEndpoint / tokenEndpoint	string	No*	토큰 엔드포인트 URL
redirectUrl	string	Yes*	콜백 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__	No	로그아웃 또는 세션 종료 URL
postLogoutRedirectUrl	__CAPGO_KEEP_0__	No	로그아웃 후 리다이렉트 URL
additionalParameters	Record<string, string>	No	추가 인증 요청 매개 변수
additionalTokenParameters	Record<string, string>	No	추가 토큰 요청 매개 변수
additionalResourceHeaders	Record<string, string>	No	추가 헤더를 위한 resourceUrl
additionalLogoutParameters	Record<string, string>	아니요	추가 로그아웃 파라미터
loginHint	문자열	아니요	빠른 additionalParameters.login_hint
prompt	문자열	아니요	빠른 additionalParameters.prompt
iosPrefersEphemeralSession	불	아니요	iOS에서 임시 브라우저 세션을 선호합니다
logsEnabled	boolean	No	verbose 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__

웹에서 전체 페이지 리다이렉트를 대신하는 팝업 대신 사용하십시오. 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

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

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

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() __CAPGO_KEEP_0__를 저장한 플러그인이 보관한 리프레시 토큰을 사용합니다. 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 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는 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	__CAPGO_KEEP_0__
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__

GitHub

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

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

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

   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

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

2. 리다이렉트 URI를 추가하세요. 모바일 또는 데스크톱 리다이렉트 URI를 추가하세요.

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

   주의

   대체 common 앱이 단일 테넌트일 경우에는 tenant ID와 함께 사용하세요.

Auth0

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

2. 허용된 콜백 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

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

2. 리다이렉트 URI를 추가하세요. __CAPGO_KEEP_0__ 앱이 사용하는 정확한 콜백 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 제공자

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가 사용할 수 없다면, 인증 및 토큰 엔드포인트를 수동으로 구성하세요.

플랫폼별 참고사항

iOS

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

안드로이드

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

웹

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

보안 최적화

1. PKCE 사용 __CAPGO_KEEP_0__을 위해 pkceEnabled: true 공개 클라이언트에 대해.

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

3. 토큰을 백엔드에서 검증하세요 발급자, 청구인, 만료 및 서명 확인을 위해 서버에서 디코딩하고 검증하세요.

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

5. HTTPS를 사용하세요 생산 인증 엔드포인트 및 로그아웃 엔드포인트는 항상 HTTPS를 사용해야 합니다.

[Troubleshooting]

providerId is required

OAuth2 provider 키가 설정된 경우에만 사용할 수 있습니다.

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

OAuth2 provider "xxx" not configured

[Call] SocialLogin.initialize() 로그인 전에 providerId providerId와 oauth2.

[Redirect URL mismatch]

• [Compare the configured redirect URL in your app and provider dashboard character by character.]
• 끝 슬래시, 스키마 불일치 및 호스트가 다른 경우 감시하십시오.
• 모바일 앱 URL 스키마가 등록되어 있는지 확인하여 디바이스에서 테스트하기 전에.

refresh 토큰이 반환되지 않음

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

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

관련 문서 logsEnabled: true 제목: "관련 문서"

provider config에서 "__CAPGO_KEEP_0__"를 활성화하여 생성된 URL 및 토큰 교환 세부 정보를 검사하십시오.

• 소셜 로그인 시작하기
• 아이오닉 인증 연결 마이그레이션

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

일반 OAuth2 제공자에서 계속하기 섹션 일반 OAuth2 제공자 인증 및 계정 흐름을 계획하고 연결하려면 Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login Using @capgo/capacitor-passkey @capgo/capacitor-social-login implementation 세부 정보에 대한 @capgo/capacitor-passkey @capgo/capacitor-native-biometric implementation 세부 정보에 대한 @capgo/capacitor-native-biometric, 그리고 두 단계 인증 implementation 세부 정보에 대한 두 단계 인증.