2026년 Capacitor 앱에 인증 추가하는 방법

To add authentication to a Capacitor app, pick an identity source (your own backend, a hosted service like Firebase or Supabase, an OIDC provider like Auth0, Okta or Entra ID, or a self-hosted library like Better Auth), use native plugins for anything that opens a provider login page, verify tokens on a server, and store the resulting session in the Keychain or Keystore. Biometrics and passkeys then make the next sign-in fast.

This guide maps every common option to the right Capacitor plugin and flow, with code for the parts that are the same in every app: the login call, token verification, session storage and biometric unlock. It is up to date for Capacitor 8 in October 2026. Each provider has its own step-by-step guide linked below.

모든 Capacitor 앱은 인증 흐름의 끝에 도달합니다.

어떤 제공자도 선택하더라도 모양은 동일합니다:

1. 사용자를 식별합니다: native social sheet, 시스템 브라우저 내의 제공자 로그인 페이지, passkey 프롬프트, 또는 이메일과 비밀번호를 제출하는 양식.
2. 증명서를 받습니다:ID 토큰, 인증서 code, 또는 인증 서버에서 세션 토큰.
3. 서버에서 확인합니다:서명, 발급자, 수신자, 만료일을 확인하고 사용자를 생성하거나 찾습니다.
4. 세션을 발급합니다:자신의 토큰 또는 제공자의 토큰, 갱신 전략과 함께.
5. 안전하게 저장합니다: 장치에 저장하고 API 호출에 첨부합니다.
6. 빠르게 잠금 해제합니다. 다음에는 생체 인증을 사용하고 로그아웃 및 계정 삭제를 처리합니다.

1과 2 단계는 제공자에 따라 달라집니다. 3부터 6까지의 단계는 모든 옵션에서 완전히 호스팅 BaaS를 제외한 경우 사용자의 책임입니다. 완전히 호스팅 BaaS의 경우 SDK가 대부분을 처리합니다.

웹뷰 로그인 페이지가 왜 깨지나요?

Capacitor 앱은 WKWebView(iOS) 또는 Android WebView에서 웹 code를 로컬 오리진(capacitor://localhost 또는 https://localhost). 로딩하는 제공자의 로그인 페이지는 세 가지 문제를 일으킵니다:

• Google이 반환 disallowed_useragent 그리고 페이지를 보여주지 않습니다.
• 앱이 페이지가 실제 제공자인지 증명할 수 없기 때문에, 이는 네이티브 앱이 시스템 브라우저를 사용해야 하는 RFC 8252의 이유입니다.
• 전체 페이지 리다이렉트는 앱을 분할하고 상태를 잃습니다.

따라서 모든 흐름은 네이티브 SDK (Apple, Google, Facebook) 또는 시스템 브라우저 세션 (iOS에서는 Chrome Custom Tabs, Android에서는)으로 사용합니다. 이 세션은 커스텀 스키마를 통해 앱으로 돌아옵니다.ASWebAuthenticationSession or

여러 옵션을 한 눈에

네이티브 소셜 로그인 (애플, 구글, 페이스북)

세 대의 주요 소비자 제공자와 일반 OAuth2 엔진을 모두 커버하는 하나의 플러그인이 있습니다:

bun add @capgo/capacitor-social-login
bunx cap sync

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  apple: { clientId: 'com.example.app' },
  google: {
    webClientId: 'WEB_CLIENT_ID.apps.googleusercontent.com',
    iOSClientId: 'IOS_CLIENT_ID.apps.googleusercontent.com',
  },
});

const { result } = await SocialLogin.login({ provider: 'google', options: {} });
// send result.idToken to your server

사용하지 않는 제공자를 끄면 capacitor.config.ts (plugins.SocialLogin.providers)으로 앱에 포함되지 않도록 SDK가 컴파일되지 않습니다. 또한 페이스북을 사용하지 않는 경우 페이스북 SDK의 광고 ID 권한이 제거됩니다.

각 제공자는 네이티브 설정이 필요합니다: 애플은 Xcode에서 기능을 추가하고 Android에 서비스 ID를 필요로 합니다. 구글은 SHA-1 지문과 역순 클라이언트 ID URL 스키마가 필요합니다. 애플 그리고 구글 가이드는 모든 단계를 거치고 일반적인 오류를 다룹니다.

엔터프라이즈 SSO와 OAuth 2.0 및 OpenID Connect

Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin 또는 자체 OIDC 서버를 사용하려면 플러그인의 oauth2 제공자입니다. PKCE를 사용하여 인증 code 흐름을 실행합니다. ASWebAuthenticationSession iOS에서 실행되고 Android에서 Custom Tabs에서 실행됩니다. 제공자가 androidUseCustomTabs: true:

await SocialLogin.initialize({
  oauth2: {
    corp: {
      issuerUrl: 'https://sso.example.com/realms/mobile', // OIDC discovery
      clientId: 'mobile-app',
      redirectUrl: 'com.example.app://oauth/corp',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      androidUseCustomTabs: true,
    },
  },
});

const { result } = await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'corp' },
});

여러 개의 제공자를 동일한 맵에 등록하고 하나를 선택하여 providerIdmulti-tenant B2B 앱에서 고객이 각자 자신의 IdP를 가져올 수 있도록 합니다. 플러그인은 또한SocialLogin.refreshrefresh ( id_token_hint), 로그아웃SocialLoginAuthConnect, 및 Ionic Auth Connect 호환 가능 wrapper ( Auth0, Auth0, 인증 ID. 프로토콜 배경에 대한 자세한 내용은 OAuth2를 Capacitor 앱에 구현하는 5 단계.

호스팅 백엔드: Firebase와 Supabase

Firebase 또는 Supabase에 데이터가 이미 저장되어 있다면, Firebase 또는 Supabase의 인증을 사용하여 보안 규칙과 행 단위 보안이 추가로 필요한 것 없이 작동합니다.

• Supabase: Social Login 플러그인을 사용하여 ID 토큰을 얻고 호출하세요. supabase.auth.signInWithIdToken({ provider: 'google', token }): Supabase가 이를 확인하고 세션을 반환합니다. 전체 설정: Supabase와 Capacitor Social Login.
• Firebase: EITHER 사용하거나, Social Login을 사용하여 ID 토큰을 얻고 JS __CAPGO_KEEP_0__에서 Firebase 인증 자격 증명을 생성하세요. 자세한 내용은 @capgo/capacitor-firebase-authentication, which wraps the native Firebase Auth SDKs, or get an ID token with Social Login and create a Firebase credential from it in the JS SDK. See the Firebase Google 로그인 문서.

Self-hosted: 자체 인증

Better Auth는 사용자가 자신의 데이터베이스에 저장되는 오픈 소스 타입 스크립트 인증 라이브러리입니다. WKWebView에서 사용할 수 있지만, 앱의 출처를 신뢰하고 토큰을 전달하는 경우 Capacitor에서 작동합니다. 소셜 로그인은 네이티브 플러그인과 ID 토큰 전달을 통해 작동합니다. 단계별로 설명합니다: Capacitor 앱에서 Better Auth를 사용하는 방법.

Passkeys

Passkeys는 iCloud Keychain 또는 Google Password Manager에 저장된 키 pairs를 사용하여 비밀번호를 대체합니다. 앱이 웹사이트 도메인과 연관되어야 하며 WebAuthn 서버가 필요합니다.apple-app-site-association iOS에서 assetlinks.json Android에서

@capgo/capacitor-passkey WebAuthn code을 표준으로 유지하고, 의존하는 파티를 구성하고, capacitor.config.ts시작 시 한 번 호출하고, navigator.credentials.create() 그리고 .get() Passkeys는 네이티브 Passkey API로 전달됩니다:

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();

// existing WebAuthn code keeps working
const assertion = await navigator.credentials.get({
  publicKey: requestOptionsFromServer,
});

라이브러리인 Better Auth와 호스팅된 제공자인 Auth0와 Okta는 WebAuthn 서버로 작동할 수 있습니다. See the passkey 플러그인 페이지.

이메일과 비밀번호를 사용하여 자체 백엔드

플러그인이 필요하지 않습니다. 그것은 단지 fetch. 서버에서 작업: Argon2id 또는 bcrypt로 해시, 로그인 시도 횟수 제한, 인증 및 리셋 이메일 전송, 계정 삭제 지원. Universal Links 및 App Links를 사용하여 앱에서 리셋 및 인증 링크를 열어 링크가 휴대폰의 올바른 위치에 표시되도록 합니다. 제공자가 모든 것을 소유하는 이유가 없다면 라이브러리인 Better Auth 또는 호스팅 서비스를 사용하면 위험을 줄일 수 있습니다.

서버에서 토큰을 확인하세요, 항상

클라이언트 측 확인은 무시될 수 있습니다. 제공자의 키 사용자 (플러스 제공자 이름), 이메일이 아닌. 이메일로 계정을 연결할 때는 제공자가 그것을 검증한 경우에만 (

import { createRemoteJWKSet, jwtVerify } from 'jose';

type IssuerConfig = {
  jwks: ReturnType<typeof createRemoteJWKSet>;
  issuer: string | string[];
  audience: string[];
};

const issuers: Record<'google' | 'apple', IssuerConfig> = {
  google: {
    jwks: createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs')),
    issuer: ['https://accounts.google.com', 'accounts.google.com'],
    audience: ['WEB_CLIENT_ID.apps.googleusercontent.com', 'IOS_CLIENT_ID.apps.googleusercontent.com'],
  },
  apple: {
    jwks: createRemoteJWKSet(new URL('https://appleid.apple.com/auth/keys')),
    issuer: 'https://appleid.apple.com',
    audience: ['com.example.app', 'com.example.app.signin'],
  },
};

export async function verifyIdToken(provider: 'google' | 'apple', idToken: string) {
  const cfg = issuers[provider];
  const { payload } = await jwtVerify(idToken, cfg.jwks, {
    issuer: cfg.issuer,
    audience: cfg.audience,
  });
  return payload; // use payload.sub as the stable provider user ID
}

Meta의 Limited Login 토큰은 그 CLAIM을 포함하지 않습니다. sub 세션을 안전하게 저장하세요email_verified: trueMeta의 Limited Login 토큰은 그 CLAIM을 포함하지 않습니다.

인증 토큰을 서버에서 항상 확인하세요

localStorage 그리고 Capacitor 설정은 평범한 파일입니다. 장기적인 토큰은 Keychain (iOS) 또는 Keystore 암호화 저장소 (Android) 에 넣어야 합니다. @capgo/capacitor-native-biometric 간단한 setData, getData 및 deleteData 그것에 대한

bun add @capgo/capacitor-native-biometric
bunx cap sync

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

export const sessionStore = {
  async save(token: string) {
    await NativeBiometric.setData({ key: 'session.token', value: token });
  },
  async load(): Promise<string | null> {
    try {
      const { value } = await NativeBiometric.getData({ key: 'session.token' });
      return value;
    } catch {
      return null;
    }
  },
  async clear() {
    await NativeBiometric.deleteData({ key: 'session.token' }).catch(() => {});
  },
};

해당 토큰의 만료 기간이 짧은 액세스 토큰을

refresh 토큰 또는 서버 세션과 함께 갱신하십시오.

우리

import { AccessControl, NativeBiometric } from '@capgo/capacitor-native-biometric';

// after a real login, offer biometric unlock
await NativeBiometric.setData({
  key: 'session.refresh',
  value: refreshToken,
  accessControl: AccessControl.BIOMETRY_ANY,
});

// next app start
const { value } = await NativeBiometric.getSecureData({
  key: 'session.refresh',
  reason: 'Unlock your account',
});
// exchange `value` with your server for a fresh access token

With accessControl 더 자세한 내용은 생체 인증을 위한 Capacitor 앱에 추가하는 방법.

Face ID와 지문만 해당 전화의 소유자가 잠금을 풀 수 있는 것을 증명합니다. 사용하여 저장된 세션에 대한 액세스를 제어하십시오:

로그인에 영향을 미치는 앱 스토어 및 플레이 규칙

• Apple 4.8 로그인 서비스: 세션에 대한 개인 정보 보호를 중점으로 둔 대안이 필요합니다. Sign in with Apple은 이를 충족합니다.
• Apple 5.1.1(v): 계정 생성은 앱 내 계정 삭제 및 Sign in with Apple 토큰의 취소가 필요합니다. See 계정 삭제 준수.
• Google Play 계정 삭제: 앱에 계정이 있는 앱은 앱 내 및 Play Console에서 선언된 웹 링크를 통해 삭제를 제공해야 합니다.
• 리뷰어 접근 권한: 리뷰어에게 작동하는 데모 계정을 제공하세요. 로그인만 SSO일 경우 테스트 테넌트 사용자도 제공하세요.
• Xcode 26: App Store Connect는 Xcode 26과 iOS 26 SDK으로 만든 빌드가 2026년 4월부터 필요하므로 새로운 인증 기능을 추가하는 릴리스를 제출하기 전에 업데이트하세요.

안전하게 인증 변경을 배포하세요

인증 버그는 모든 사용자가 막히므로 빠르게 고쳐야 합니다. 네이티브 변경(권한, URL 스킴, 인텐트 필터)은 스토어 빌드를 필요로 합니다. TypeScript로 작성된 모든 항목(제공자 구성, 범위, 오류 처리 및 UI)은 __CAPGO_KEEP_0__ 라이브 업데이트와 함께 푸시할 수 있습니다. Capgo 실시간 업데이트 __CAPGO_KEEP_0__ 빌드 Capgo 빌드 다음 단계

다음 단계

리뷰어 접근 권한

• 애플로 로그인
• 구글로 로그인
• Auth0
• Okta
• Microsoft Entra ID
• 세キュ어한 인증
• 소셜 로그인 플러그인 문서