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

Generic OAuth2 제공자

GitHub

소개

소개 섹션

Capgo Social Login 플러그인은 OAuth2 및 OpenID Connect 엔진을 내장하고 있습니다. 표준 기반의 인증 제공자와 연결할 수 있습니다. 예를 들어:

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

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

What you need

제목 'What you need' 섹션

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

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

authorizationBaseUrl and accessTokenEndpoint explicit한 엔드포인트가 항상 발견된 값보다 우선합니다. issuerUrl 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',
});

로그인 상태 및 로그아웃

Refresh tokens
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);

제공자별 예시

__CAPGO_KEEP_0__ 예시

GitHub 예시

GitHub를 사용하여 간단한 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',
    },
  },
});


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 데이터(사용자 프로필 등)를 필요로 할 때 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직접 가져온 Raw 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 registrations자연어 또는 모바일 앱 등록을 생성하세요.

  2. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

  3. __CAPGO_KEEP_2__

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

__CAPGO_KEEP_8__

__CAPGO_KEEP_9__

  1. __CAPGO_KEEP_10__ __CAPGO_KEEP_11__ 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,
    },
  },
});

만약 discovery가 사용할 수 없다면 인증 및 토큰 엔드포인트를 수동으로 구성하세요.

플랫폼별 참고사항

플랫폼별 참고사항

iOS

iOS
  • 이 플러그인은 ASWebAuthenticationSession.
  • 설정 iosPrefersEphemeralSession: true 개인 브라우저 세션을 사용하고 싶다면 공유 쿠키가 없는 세션을 설정하세요.

안드로이드

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

웹

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

보안 최적화 방법

보안 최적화 방법 섹션

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

  2. 권한 부여 code 흐름 responseType: 'code' 권한 부여 흐름이 명시적 흐름보다 안전합니다.

  3. 서버에서 토큰 검증 발급자, 대상자, 만료일, 서명 검증

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

  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 스킴을 등록한 후 기기에서 테스트하기 전에 확인하십시오.

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

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

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

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

켜십시오.

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

관련 문서 섹션

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

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

일반 OAuth2 제공자를 사용하는 경우 일반 OAuth2 제공자 인증 및 계정 흐름을 계획하고 연결하려면 Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login @capgo/capacitor-social-login Capgo 구현 세부 사항에 대한 @capgo/capacitor-social-login 에 대해 @capgo/capacitor-passkey Capgo 구현 세부 사항에 대한 @capgo/capacitor-passkey 에 대해 @capgo/capacitor-native-biometric Capgo 구현 세부 사항에 대한 @capgo/capacitor-native-biometric, 두 단계 인증 두 단계 인증 구현 세부 사항에 대해