Skip to content
Capgo - Capacitor 앱에 대한 실시간 업데이트 Capgo

일반 OAuth2 제공자

소개

인터뷰 소개

Capgo의 사회 로그인 플러그인은 내장 OAuth2 및 OpenID Connect 엔진을 포함합니다. 다음 표준 기반 식별 제공자와 연결할 수 있습니다:

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

설정은 여러 제공자 등록을 허용하여 로그인 시 하나를 선택할 수 있습니다. oauth2 필요한 것 providerId.

인터뷰 필요

Section titled “What you need”]

구성을 하기 전에 다음을 준비하세요:

  • OAuth 클라이언트 ID
  • 앱 스키마 또는 웹 콜백 URL과 일치하는 리다이렉트 URL
  • 인증화면 URL
  • A token endpoint for authorization code flow, or an issuerUrl 앱이 필요로 하는 범위, 예를 들어
  • 다중 제공자 구성 openid profile email

제목: 다중 제공자 구성

앱 시작 시 한번만 사용하여 필요한 모든 제공자를 등록하세요:

클립보드에 복사 SocialLogin.initialize() __CAPGO_KEEP_0__

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 및 별칭

OIDC discovery 및 별칭 섹션

제공자가 OpenID Connect discovery 문서를 공개할 경우, 가장 단순한 설정입니다. issuerUrl OIDC discovery 문서를 공개하는 제공자가 없다면,

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 별칭으로 사용할 수 있습니다. logoutUrl
  • scopes 별칭으로 사용할 수 있습니다. scope

또한 사용할 수 있습니다:

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

Auth Connect 호환 프리셋

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

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

  • auth0
  • azure
  • cognito
  • okta
  • onelogin

제공자가 사용자 정의 엔드포인트가 필요하면, 프리셋에서 오버라이드하거나 프리셋을 무시하고 제공자를 직접 설정하여 oauth2.

설정 옵션

설정 옵션 섹션 제목
옵션타입필수설명
appId / clientId문자열예OAuth2 클라이언트 식별자
issuerUrl문자열아니요OIDC 디스커버리 베이스 URL
authorizationBaseUrl / authorizationEndpoint대상 언어: ${targetLanguage}Yes*인증 엔드포인트 URL
accessTokenEndpoint / tokenEndpointstringNo*토큰 엔드포인트 URL
redirectUrlstringYes콜백 URL
scope / scopesstring / string[]No요청된 범위
pkceEnabledbooleanNo기본값입니다. true
responseType'code' or 'token'No기본값입니다. 'code'
resourceUrlstringNo사용자 정보 또는 리소스 엔드포인트
logoutUrl / endSessionEndpointstringNo로그아웃 또는 세션 종료 URL
postLogoutRedirectUrlstring아니요로그아웃 후 리다이렉트 URL
additionalParametersRecord<string, string>아니요추가 인증 요청 매개 변수
additionalTokenParametersRecord<string, string>아니요추가 토큰 요청 매개 변수
additionalResourceHeadersRecord<string, string>아니요추가 헤더 resourceUrl
additionalLogoutParametersRecord<string, string>아니요추가 로그아웃 매개 변수
loginHintstring아니요iOS에서 임시 브라우저 세션을 선호하는 단축키 additionalParameters.login_hint
prompt문자열아니요iOS에서 임시 브라우저 세션을 선호하는 단축키 additionalParameters.prompt
iosPrefersEphemeralSession불리언아니요iOS에서 임시 브라우저 세션을 선호하는
logsEnabled불리언verbose한 디버그 로깅을 활성화및

authorizationBaseUrl verbose한 디버그 로깅을 활성화 accessTokenEndpoint are only optional when issuerUrl 는 발견된 값보다 항상 명시적인 엔드포인트가 우선합니다.

OAuth2 로그인 사용

OAuth2 로그인 사용

로그인

로그인
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() 자신이 자동 갱신 토큰을 전달하고 최신 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를 사용하여 사용자 프로필과 같은 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 예시

클립보드 복사
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);

청중이 제공하는 서비스를 사용할 때는 발견을 사용하세요.

클립보드 복사

청중이 제공하는 서비스를 사용할 때는 발견을 사용하세요. /.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);

__CAPGO_KEEP_0__

OAuth2 응답 형태

성공적인 OAuth2 로그인은 다음과 같은 결과를 반환합니다.

Field설명
providerId사용자 지정 제공자 키
accessToken액세스 토큰의 페이로드 또는 null
idTokenOIDC ID 토큰이 제공자가 반환한 경우
refreshTokenrefresh 토큰이 요청된 범위가 허용된 경우
resourceDataraw JSON resourceUrl
scope허용된 범위
tokenType일반적으로 bearer
expiresIn토큰 유효 시간 (초)

제공자 설정 참고 자료

제공자 설정 참고 자료

GitHub

GitHub

  1. OAuth 앱을 생성하세요 열기 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

Azure AD / Microsoft Entra ID 섹션

  1. 앱 등록 Azure Portal로 이동하여 App registrationsnative 또는 mobile 앱 등록을 생성하세요.

  2. 리다이렉트 URI 추가 앱 콜백 URL과 일치하는 모바일 또는 데스크톱 리다이렉트 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',
        },
      },
    });

Auth0

Auth0 섹션

  1. 자연스러운 네이티브 앱을 생성하세요 Auth0 대시보드 자연스러운 앱을 생성하세요 허용된 callback URL을 설정하세요

  2. 앱이 사용하는 exact redirect URL을 입력하세요 Add the exact redirect URL used by your Capacitor app.

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

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

  1. __CAPGO_KEEP_2__ __CAPGO_KEEP_3__

  2. __CAPGO_KEEP_4__ __CAPGO_KEEP_5__

  3. __CAPGO_KEEP_6__

    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_8__

__CAPGO_KEEP_9__

__CAPGO_KEEP_10__ 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

iOS 제목
  • 플러그인은 ASWebAuthenticationSession.
  • 설정 iosPrefersEphemeralSession: true 만약 개인 브라우저 세션을 원한다면, 공유 쿠키가 없는 세션을 사용하십시오.

Android

Android 제목
  • OAuth 리다이렉트는 앱 스키마 및 호스트를 통해 돌아옵니다.
  • Android의 제공자 콜백 URL이 정확히 Android의 깊이 링크 설정과 일치하도록 확인하십시오.
  • 플러그인은 OAuth 활동을 이미 처리합니다. 앱이 다른 리다이렉트 패턴이 필요한 경우에만 사용자 정의 인텐트 필터를 추가하세요.

웹

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

보안 최적화

보안 최적화

  1. PKCE를 사용하세요. 공공 클라이언트의 경우 __CAPGO_KEEP_0__ 인증 흐름을 선호하세요. pkceEnabled: true for public clients.

  2. code responseType: 'code' 은 명시적 흐름보다 안전합니다.

  3. 백엔드에서 토큰을 유효성 검사하세요 발급자, 청구인, 만료일 및 서명 등을 서버 측에서 해석하고 검증하세요.

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

  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 객체 키 아래에 oauth2.

리다이렉트 URL 일치하지 않음

앱과 제공자 대시보드에서 리다이렉트 URL을 문자별로 비교하세요.
  • 끝에 슬래시가 있는지, 스키마가 일치하는지, 호스트가 다른지 확인하세요.
  • 모바일 앱 URL 스키마를 등록한 후 기기에서 테스트하세요.
  • 리프레시 토큰이 반환되지 않음

리다이렉트 URL 일치하지 않음

리프레시 토큰이 반환되지 않음

대부분의 제공자는 refresh 토큰을 요청하는 범위와 같이 scope를 요청할 때 refresh 토큰만 반환합니다. 또는 명시적으로 동의를 강제합니다. 제공자별 정책을 검토하세요. offline_access __CAPGO_KEEP_0__

토큰 교환 디버깅

토큰 교환 디버깅

Enable logsEnabled: true __CAPGO_KEEP_0__

Social Login 시작

일반 OAuth2 제공자

__CAPGO_KEEP_0__

만약에 당신이 사용 중이라면 일반 OAuth2 제공자 인증 및 계정 흐름을 계획하고 연결하려면 Capacitor @capgo/capacitor-social-login Capacitor @capgo/capacitor-social-login Capacitor @capgo/capacitor-social-login Capacitor @capgo/capacitor-passkey Capacitor @capgo/capacitor-native-biometric Capacitor @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric for the implementation detail in @capgo/capacitor-native-biometric, and 두 단계 인증 두 단계 인증 구현 세부 정보.