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

일반 OAuth2 제공자

GitHub

소개

소개 섹션

The Capgo Social Login plugin includes a built-in OAuth2 and OpenID Connect engine. You can use it to connect any standards-based identity provider, including:

  • GitHub
  • Azure AD / Microsoft Entra ID
  • Auth0
  • Okta
  • Keycloak
  • Custom OAuth2 or OIDC servers

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

What you need

Section titled “What you need”

구성하려는 제공자에 대해 다음을 준비하세요:

  • OAuth 클라이언트 ID
  • 앱 스키마 또는 웹 콜백 URL과 일치하는 리다이렉트 URL
  • 인증화면 URL
  • 인증 code 흐름을 위한 토큰 발급 URL 또는 OIDC 디스커버리 URL issuerUrl An
  • 앱이 필요로 하는 범위, 예를 들어 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 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__CAPGO_KEEP_0__예OAuth2 클라이언트 식별자
issuerUrl__CAPGO_KEEP_0__아니오OIDC 발견 기초 URL
authorizationBaseUrl / authorizationEndpoint예인증화면 URL__CAPGO_KEEP_0__
accessTokenEndpoint / tokenEndpoint아니오토큰 기초 URL__CAPGO_KEEP_0__
redirectUrlstring예콜백 URL
scope / scopesstring / string[]아니오요청된 범위
pkceEnabledboolean아니오기본값 true
responseType'code' 또는 'token'아니오기본값 'code'
resourceUrl소셜 로그인 플러그인아니요사용자 정보 또는 리소스 엔드포인트
logoutUrl / endSessionEndpointstring아니요로그아웃 또는 세션 종료 URL
postLogoutRedirectUrlstring아니요로그아웃 후 리다이렉트 URL
additionalParametersRecord<string, string>string아니요
additionalTokenParametersRecord<string, string>추가 인증 요청 매개변수추가 토큰 요청 매개 변수
additionalResourceHeadersRecord<string, string>아니요추가 헤더를 위한 resourceUrl
additionalLogoutParametersRecord<string, string>아니요로그아웃 매개 변수
loginHint문자열아니요단축 키 additionalParameters.login_hint
prompt문자열아니요단축 키 additionalParameters.prompt
iosPrefersEphemeralSession부울NoiOS 브라우저 세션을 임시로 사용
logsEnabledbooleanNoverbose한 디버그 로깅을 활성화

authorizationBaseUrl and 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() 이 플러그인이 저장한 새로고침 토큰을 사용합니다. refreshToken() __CAPGO_KEEP_0__을 사용하여 새로고침 토큰을 직접 전달하고 최신 OAuth2 응답을 반환합니다.

현재 접근 토큰 가져오기

Section titled “현재 접근 토큰 가져오기”
const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});


console.log(code.accessToken);

제공자별 예시

Section titled “제공자별 예시”

GitHub 예시

Section titled “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 그래프 데이터(사용자 프로필 등)를 필요로 할 때 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 예시

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

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

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

제공자 설정 참고

제공자 설정 참고 섹션

GitHub

GitHub 섹션

  1. OAuth 앱 만들기 __CAPGO_KEEP_0__ 개발자 설정 GitHub Developer Settings 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를 추가하여 앱 콜백 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. 자연어 애플리케이션 만들기 여러분의 앱을 열어 Auth0 Dashboard Native 앱을 만들기 위해

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

Okta 섹션

  1. OIDC Native 앱 만들기 Okta Admin Console에서 OIDC Native Application을 만들세요.

  2. 리다이렉트 URI 추가 __CAPGO_KEEP_0__ 앱에서 사용하는 정확한 callback 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를 지원하면 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,
    },
  },
});

OpenID Connect discovery가 사용할 수 없으면 인증 및 토큰 엔드포인트를 수동으로 구성합니다.

플랫폼별 참고 사항

플랫폼별 참고 사항

iOS

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

안드로이드

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

웹

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

보안 최적화 방법

보안 최적화 방법 섹션

  1. PKCE 사용 보안 pkceEnabled: true 공개 클라이언트용

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

  3. 서버에서 토큰을 검증하세요 발급자, 대상, 만료, 서명 확인

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

  5. Use HTTPS everywhere Production auth endpoints 및 logout endpoints는 항상 HTTPS를 사용해야 합니다.

문제 해결

문제 해결

providerId is required

providerId가 필요합니다.

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

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

OAuth2 provider "xxx" not configured

OAuth2 제공자 "xxx"가 구성되지 않았습니다.

호출 SocialLogin.initialize() 로그인 전에 확인하고 providerId matches하는 객체 키 아래 oauth2.

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

Redirect URL 불일치
  • 앱과 제공자 대시보드에서 설정된 리다이렉트 URL을 문자별로 비교하십시오.
  • 끝에 슬래시가 있는지, 스킴이 일치하는지, 호스트가 다른지 주의하십시오.
  • 모바일 앱 URL 스킴이 등록되어 있는지 확인한 후 디바이스에서 테스트하십시오.

refresh 토큰이 반환되지 않음

refresh 토큰이 반환되지 않음

refresh 토큰이 반환되는 경우 대부분의 제공자는 scope가 offline_access 또는 명시적으로 동의를 강제할 때입니다. 제공자별 정책을 검토하십시오.

토큰 교환 디버깅

리다이렉트 URL과 토큰 교환 세부 사항을 검토하기 위해 제공자 설정에서

켜십시오. logsEnabled: true 켜십시오.

관련 문서 섹션

일반 OAuth2 제공자에서 계속 진행

일반 OAuth2 제공자에서 계속 진행 섹션

일반 OAuth2 제공자를 사용하는 경우 일반 OAuth2 제공자 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-소셜 로그인으로 인증 및 계정 흐름을 계획하고 Using @capgo/capacitor-소셜 로그인 Using @capgo/capacitor-소셜 로그인 @capgo/capacitor-소셜 로그인 capgo/capacitor-social-login capgo/capacitor-passkey capgo/capacitor-passkey capgo/capacitor-native-biometric capgo/capacitor-native-biometric, and 두 단계 인증 __CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-biometric, and 두 단계 인증에 대한 implementation detail