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

일반 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"

구성에 제공자 등록하기 전에 다음을 준비하세요:

  • OAuth 클라이언트 ID
  • 앱 스키마 또는 웹 콜백 URL에 맞는 리다이렉트 URL
  • 인증화면 URL
  • 인증 code 흐름을 위한 토큰 인증 URL 또는 OIDC 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 발견 및 별명

제공자가 OpenID Connect 발견 문서를 노출한다면 가장 간단한 설정입니다:

플러그인은 일반적인 OAuth 및 OIDC 별명을 지원합니다: 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,
    },
  },
});

OIDC 발견 및 별명

  • clientId 제공자가 OpenID Connect 발견 문서를 노출한다면 가장 간단한 설정입니다: 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문자열네OAuth2 클라이언트 식별자
issuerUrl문자열아니오OIDC 발견 기초 URL
authorizationBaseUrl / authorizationEndpoint문자열네*인증 엔드포인트 URL
accessTokenEndpoint / tokenEndpoint문자열아니오*토큰 엔드포인트 URL
redirectUrl문자열네콜백 URL
scope / scopes문자열 / 문자열[]아니오요청된 범위
pkceEnabled불아니오기본값으로 true
responseType'code' 또는 'token'아니오기본값으로 'code'
resourceUrl문자열아니요사용자 정보 또는 리소스 엔드포인트
logoutUrl / endSessionEndpoint문자열아니요로그아웃 또는 세션 종료 URL
postLogoutRedirectUrl문자열아니요로그아웃 후 리다이렉트 URL
additionalParametersRecord<string, string>아니요추가 인증 요청 매개변수
additionalTokenParametersRecord<string, string>아니요추가 토큰 요청 매개변수
additionalResourceHeadersRecord<string, string>아니요추가 헤더 resourceUrl
additionalLogoutParametersRecord<string, string>아니요추가 로그아웃 파라미터
loginHint문자열아니요단축어 additionalParameters.login_hint
prompt문자열아니요단축어 additionalParameters.prompt
iosPrefersEphemeralSession불리언아니요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() 플러그인은 저장된 리프레시 토큰을 사용합니다. 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);

Microsoft Azure / Microsoft Entra ID 예시

Microsoft Azure / 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 토큰이 제공자가 반환한 경우
refreshTokenRefresh 토큰이 요청된 범위가 허용한 경우
resourceData직접 가져온 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. 리다이렉트 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. 자연어 애플리케이션을 생성하세요. 열기 __CAPGO_KEEP_0__ 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 발견을 지원하는 경우 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,
    },
  },
});

발견이 사용할 수 없는 경우 인증 및 토큰 엔드포인트를 수동으로 구성합니다.

플랫폼별 참고 사항

플랫폼별 참고 사항 섹션

iOS

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

안드로이드

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

웹

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

보안 최적화

Security best practices

  1. PKCE 사용 보관 pkceEnabled: true 공개 클라이언트에 대해

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

  3. 토큰을 백엔드에서 검증하세요 서버에서 발급자, 수신자, 만료, 서명 확인하세요.

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

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

문제 해결

문제 해결

providerId is required

providerId는 필요합니다.

클립보드 복사

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

OAuth2 provider "xxx" not configured

호출

로그인 전에 확인하고 SocialLogin.initialize() matches하는 객체 키 아래 providerId URL 리다이렉션 불일치 oauth2.

URL 리다이렉션 불일치

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

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

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

대부분의 제공자는 스코프와 같이 요청할 때 리프레시 토큰을 반환합니다. 제공자별 정책을 검토하십시오. offline_access 토큰 교환 디버깅

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

제공자 설정에서 'Enable'을 활성화하여 생성된 URL과 토큰 교환 세부 정보를 검토하십시오.

관련 문서 logsEnabled: true Enable

관련 문서

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

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

일반 OAuth2 제공자를 사용하여 인증 및 계정 흐름을 계획하고 일반 OAuth2 제공자와 연결합니다. @capgo/capacitor-social-login Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login @capgo/capacitor-패스키 @capgo/capacitor-passkey @capgo/capacitor-native-생체인증 @capgo/capacitor-native-biometric 두 단계 인증 두 단계 인증