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

일반 OAuth2 제공자

소개

제목이 '소개'인 섹션

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

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

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

What you need

구성하려는 제공자에 앞서 다음을 준비하세요.

OAuth 클라이언트 ID

  • 앱 스키마 또는 웹 콜백 URL과 일치하는 리다이렉트 URL
  • 인증화면 URL
  • 인증 __CAPGO_KEEP_0__ 흐름을 위한 토큰 발급 URL
  • A token endpoint for authorization code flow, or an issuerUrl OIDC 발굴
  • 앱이 필요로 하는 범위, 예를 들어 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 발굴 및 별칭

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

플러그인은 일반 OAuth 및 OIDC 별칭도 지원합니다:

  • clientId 별칭으로 사용 appId
  • authorizationEndpoint 별칭으로 사용 authorizationBaseUrl
  • tokenEndpoint 별칭으로 사용 accessTokenEndpoint
  • endSessionEndpoint 별칭으로 사용 logoutUrl
  • scopes 또한 사용할 수 있습니다: scope

인증 요청 오버라이드

  • additionalParameters 토큰 교환 오버라이드
  • additionalTokenParameters 사용자 정의 리소스 엔드포인트 헤더
  • additionalResourceHeaders 및
  • additionalLogoutParameters 로그아웃 흐름 postLogoutRedirectUrl __CAPGO_KEEP_0__
  • 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__CAPGO_KEEP_0__예OAuth2 클라이언트 식별자
issuerUrl__CAPGO_KEEP_0__아니오OIDC 발견 기초 URL
authorizationBaseUrl / authorizationEndpoint__CAPGO_KEEP_0__인증 엔드포인트 URL__CAPGO_KEEP_0__
accessTokenEndpoint / tokenEndpoint아니오*OIDC 발견 기초 URL토큰 엔드포인트 URL
redirectUrl__CAPGO_KEEP_0__네콜백 URL
scope / scopes__CAPGO_KEEP_0__ / __CAPGO_KEEP_0__[]아니오요청된 범위
pkceEnabledboolean아니오기본값 true
responseType'code' 또는 'token'아니오기본값으로 'code'
resourceUrl__CAPGO_KEEP_0__아니요사용자 정보 또는 리소스 엔드포인트
logoutUrl / endSessionEndpoint__CAPGO_KEEP_0__아니요로그아웃 또는 세션 종료 URL
postLogoutRedirectUrl__CAPGO_KEEP_0__아니요로그아웃 후 리다이렉트 URL
additionalParametersRecord<string, string>아니요추가 인증 요청 매개변수
additionalTokenParametersRecord<string, string>아니요__CAPGO_KEEP_0__
additionalResourceHeadersRecord<string, string>아니요__CAPGO_KEEP_0__ resourceUrl
additionalLogoutParametersRecord<string, string>아니요__CAPGO_KEEP_0__
loginHint문자열아니요__CAPGO_KEEP_0__ additionalParameters.login_hint
prompt__CAPGO_KEEP_0__아니요__CAPGO_KEEP_0__ additionalParameters.prompt
iosPrefersEphemeralSessionboolean아니요iOS에서 임시 브라우저 세션을 선호합니다.
logsEnabledboolean아니요verbose한 디버그 로깅을 활성화합니다.

authorizationBaseUrl 그리고 accessTokenEndpoint 만약에 발견된 값이 있으면, 명시적으로 지정된 엔드포인트가 항상 우선합니다. 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() __CAPGO_KEEP_0__ 플러그인이 저장한 리프레시 토큰을 사용합니다. 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 audience가 필요할 때 적합합니다:

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 로그인 결과

Field설명
providerId__CAPGO_KEEP_0__
accessToken로그인에 사용되는 구성된 제공자 키 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__

__CAPGO_KEEP_0__

GitHub

GitHub

  1. OAuth 앱 만들기 열기 GitHub 개발자 설정 Azure Portal로 이동하여 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 registrations모바일 또는 데스크톱 앱 등록을 생성하세요.

  2. 리다이렉트 URI 추가 리다이렉트 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 Dashboard Native 앱을 만들기 위해

  2. 허용된 callback URL 설정 Capacitor 앱이 사용하는 exact redirect 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 Native 앱을 만들기 위해 Okta Admin Console에서 OIDC Native Application을 만들고

  2. redirect URI를 추가합니다. 앱이 사용하는 정확한 콜백 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',
        },
      },
    });

Keycloak 및 사용자 정의 OIDC 제공자

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

Section titled “iOS”

Section titled “Platform-specific notes”
  • The plugin uses ASWebAuthenticationSession.
  • __CAPGO_KEEP_0__ iosPrefersEphemeralSession: true __CAPGO_KEEP_1__

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__
  • __CAPGO_KEEP_4__
  • __CAPGO_KEEP_5__
  • __CAPGO_KEEP_6__

__CAPGO_KEEP_7__

__CAPGO_KEEP_8__
  • __CAPGO_KEEP_9__
  • __CAPGO_KEEP_10__
  • 일부 제공자에서는 직접 브라우저 토큰 교환에 대한 CORS를 차단합니다. 이 경우 백엔드 교환 또는 공공 클라이언트를 허용하는 제공자 설정을 사용하세요.

보안 최적화

보안 최적화

  1. PKCE를 사용하세요 공개 클라이언트에 대해 pkceEnabled: true 인증 __CAPGO_KEEP_0__ 흐름보다 암묵적 흐름이 더 안전합니다.

  2. Prefer authorization code flow responseType: 'code' 발급자, 대상, 만료, 서명 등을 서버측에서 디코딩하고 검증하세요.

  3. 리프레시 토큰을 안전하게 저장하세요 네이티브 앱의 경우 이 플러그인을 pair하세요

  4. Section titled “Security best practices” Use PKCE @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() matches the object key under providerId matches the object key under oauth2.

URL 리다이렉션 불일치

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

refresh 토큰이 반환되지 않음

Section titled “refresh 토큰이 반환되지 않음”

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

Section titled “토큰 교환 디버깅”

디버깅

Section titled “디버깅” logsEnabled: true 제공자 구성에서 생성된 URL 및 토큰 교환 세부 정보를 검사하기 위해.

제목이 '관련 문서'인 섹션