Identity Platform user 객체는 Google Cloud프로젝트의 앱에 가입한 사용자 계정을 나타냅니다. 앱에는 일반적으로 등록된 사용자가 많으며 Google Cloud프로젝트의 모든 앱이 사용자 데이터베이스 하나를 공유합니다.
사용자 인스턴스는 Identity Platform 인스턴스와 별개이므로 같은 컨텍스트 내에 여러 사용자에 대한 참조가 여러 개 있을 수 있으며 이러한 사용자의 메서드를 어떤 것이나 호출할 수 있습니다.
사용자 속성
Identity Platform 사용자는 프로젝트의 사용자 데이터베이스에 고유 ID, 기본 이메일 주소, 이름, 사진 URL과 같은 고정된 기본 속성 집합을 저장하며 사용자가 이러한 속성을 업데이트(iOS, Android, 웹)할 수 있습니다.
user 객체에 직접 다른 속성을 추가할 수는 없으며 대신 추가 속성을 Google Cloud Firestore와 같은 다른 스토리지 서비스에 저장할 수 있습니다.
사용자가 앱에 처음 가입할 때 사용자의 프로필 데이터에 정보를 채웁니다.
사용자가 이메일 주소와 비밀번호로 가입했다면 기본 이메일 주소 속성만 채웁니다.
사용자가 Google 또는 Facebook 등의 제휴 ID 공급업체를 사용해 가입했다면 업체에서 제공하는 계정 정보를 가져와 사용자의 프로필을 채웁니다.
사용자가 맞춤 인증 시스템으로 가입했다면 원하는 정보를 사용자의 프로필에 명시적으로 추가해야 합니다.
사용자 계정이 생성되면 사용자의 정보를 다시 불러와서 사용자가 다른 기기에서 변경한 내역을 반영할 수 있습니다.
로그인 제공업체
앱에 사용자를 로그인 처리하는 데는 이메일 주소 및 비밀번호, 제휴 ID 공급업체, 맞춤 인증 시스템 등의 방법이 있습니다. 한 명의 사용자에게 2가지 이상의 로그인 방법을 연결할 수 있습니다. 예를 들면 한 명의 사용자가 이메일 주소, 비밀번호, Google 로그인을 사용해서 같은 계정에 로그인할 수 있습니다.
사용자 인스턴스는 해당 사용자에게 연결된 모든 공급업체를 추적합니다. 따라서 공급업체가 전달하는 정보를 이용해 프로필의 빈 속성을 업데이트할 수 있습니다.
사용자 관리(iOS, Android, 웹)를 참조하세요.
현재 사용자
가입하거나 로그인한 사용자는 Auth 인스턴스의 현재 사용자가 됩니다. 이 인스턴스는 사용자의 상태를 유지하여 브라우저에서 페이지를 새로고침하거나 애플리케이션을 재시작해도 사용자의 정보가 사라지지 않게 합니다.
사용자가 로그아웃하면 인증 인스턴스가 user 객체에 대한 참조 유지를 중단하고 사용자 상태를 유지하지 않습니다. 즉, 현재 사용자가 없는 것입니다. 그러나 사용자 인스턴스는 계속 온전히 작동합니다. 이 인스턴스에 대한 참조를 유지하면 사용자의 데이터에 계속 액세스하고 업데이트할 수 있습니다.
사용자 처리 과정
Auth 인스턴스의 현재 상태를 추적할 때 권장하는 방법은 리스너(자바스크립트에서는 '관찰자'라고 함)를 사용하는 것입니다. Auth 리스너는 Auth 객체에 유의미한 사건이 발생할 때마다 알림을 받습니다. 사용자 관리(iOS, Android, 웹)를 참조하세요.
다음과 같은 경우에 Auth 리스너가 알림을 받습니다.
인증 객체가 초기화를 완료하고 사용자가 이미 이전 세션을 통해 로그인해 있거나 ID 공급업체의 로그인 흐름에서 리디렉션되었을 때
사용자가 로그인할 때(현재 사용자가 설정될 때)
사용자가 로그아웃할 때(현재 사용자가 null이 될 때)
현재 사용자의 액세스 토큰이 갱신될 때. 갱신이 일어나는 상황은 다음과 같습니다.
액세스 토큰이 만료되었을 때: 흔한 경우입니다. 갱신 토큰을 사용해 유효한 토큰을 새로 가져옵니다.
사용자가 비밀번호를 변경할 때: Identity Platform이 새 액세스 및 갱신 토큰을 발급하고 기존 토큰을 만료시킵니다. 이때 보안상의 이유로 자동으로 사용자의 토큰이 만료되거나 사용자가 모든 기기에서 로그아웃됩니다.
사용자가 다시 인증할 때: 일부 작업은 사용자의 인증 정보가 최근에 발급된 경우에만 진행될 수 있습니다. 이런 작업으로는 계정 삭제, 기본 이메일 주소 설정, 비밀번호 변경 등이 있습니다. 사용자를 로그아웃 처리하고 다시 로그인 처리할 필요는 없고 사용자에게서 새로운 인증 정보를 받아서 user 객체의 reauthenticate 메서드에 전달하면 됩니다.
사용자 셀프서비스
기본적으로 Identity Platform을 사용하면 사용자가 관리 작업 없이 계정에 가입하고 삭제할 수 있습니다. 이렇게 하면 최종 사용자가 애플리케이션 또는 서비스를 검색하고 최소한의 마찰로 온보딩(또는 오프보딩)할 수 있습니다.
하지만 Admin SDK 또는Google Cloud Console을 사용하여 관리자를 통해 수동으로 또는 프로그래매틱 방식으로 사용자를 생성하려는 경우도 있습니다. 이러한 경우 Identity Platform 설정 페이지에서 사용자 작업을 중지하여 최종 사용자가 계정을 만들고 삭제하지 못하게 할 수 있습니다. 멀티테넌시를 사용하는 경우 테넌트별로 이러한 기능을 사용 중지하도록 HTTP 요청을 수행해야 합니다.
최종 사용자가 시스템 내에서 계정을 만들거나 삭제하려고 시도하면 Identity Platform 서비스가 오류 코드를 반환합니다(웹 API 호출의 경우 auth/admin-restricted-operation, Android 및 iOS의 경우 ERROR_ADMIN_RESTRICTED_OPERATION). 사용자에게 서비스의 적절한 작업을 요청하여 프런트엔드의 오류를 적절하게 처리해야 합니다.
인증 토큰
Identity Platform으로 인증을 진행할 때 다루는 인증 토큰에는 3가지 유형이 있습니다.
Identity Platform ID 토큰
사용자가 앱에 로그인할 때 Identity Platform에서 만드는 토큰입니다. 이 토큰은 서명된 JWT로, Google Cloud프로젝트에서 사용자를 안전하게 식별합니다. 이 토큰은 Google Cloud프로젝트에 고유한 사용자의 ID 문자열을 비롯하여, 사용자의 기본 프로필 정보를 담고 있습니다. ID 토큰의 무결성을 확인할 수 있으므로 이 토큰을 백엔드 서버로 전송하여 현재 로그인한 사용자를 식별할 수 있습니다.
ID 공급업체 토큰
Google과 Facebook 등의 제휴 ID 공급업체에서 생성하는 토큰입니다.
토큰의
형식은 다양하지만 대개는 OAuth 2.0 액세스 토큰입니다. 앱은 이 토큰을 통해 사용자가 ID 공급업체에서 정상적으로 인증을 거쳤음을 확인하고, 토큰을 Identity Platform 서비스가 사용할 수 있는 사용자 인증 정보로 변환합니다.
Identity Platform 커스텀 토큰
사용자가 자체 인증 시스템을 통해 앱에 로그인할 수 있게 해 주는 맞춤 인증 시스템이 만드는 토큰입니다. 맞춤 토큰은 서비스 계정의 비공개 키를 사용해 서명한 JWT입니다.
앱은 제휴 ID 공급업체에서 반환한 토큰을 사용할 때와 유사한 방식으로 이 토큰을 사용합니다.
인증된 이메일 주소
Identity Platform은 다음 두 가지 조건을 충족하는 경우 이메일이 인증된 것으로 간주합니다.
사용자가 Identity Platform 인증 과정을 완료합니다.
신뢰할 수 있는 ID 공급업체(줄여서 IdP)에 의해 이메일이 인증되었습니다.
이메일을 한 번 인증한 다음 사용자가 재인증하지 않고 이메일 주소를 변경할 수 있도록 허용하는 IdP는 신뢰할 수 없습니다. 도메인을 소유하거나 항상 인증이 필요한 IdP는 신뢰할 수 있는 것으로 간주됩니다.
신뢰할 수 있는 제공업체:
Google(@gmail.com 주소의 경우)
Yahoo(@yahoo.com 주소의 경우)
Microsoft(@outlook.com 및 @hotmail.com 주소의 경우)
Apple(계정이 항상 인증되며 다중 인증(MFA)을 사용하므로 항상 신뢰할 수 있음)
신뢰할 수 없는 제공업체:
Facebook
Twitter
GitHub
해당 ID 공급업체에서 발급하지 않은 도메인에 대한 Google, Yahoo, Microsoft
이메일 인증이 없는 이메일/비밀번호
사용자가 동일한 이메일 주소를 사용하여 다른 제공업체로 로그인하면 Identity Platform에서 계정을 자동으로 연결하기도 합니다. 하지만 이 방법은 특정 기준이 충족되는 경우에만 가능합니다. 그 이유를 알아보려면 다음과 같은 경우를 생각해 보세요. 사용자가 @gmail.com 계정으로 Google을 사용하여 로그인하고 악의적인 행위자가 동일한 @gmail.com 주소를 사용하여 계정을 만들지만 Facebook을 통해 로그인합니다. 이 두 계정이 자동으로 연결되면 악의적인 행위자가 사용자 계정에 액세스할 수 있게 됩니다.
다음은 Google에서 자동으로 계정을 연결하는 경우와 사용자 또는 개발자 조치가 필요한 오류가 발생하는 경우를 설명합니다.
사용자가 신뢰할 수 없는 제공업체로 로그인한 후 동일한 이메일을 사용하여 신뢰할 수 없는 다른 제공업체로 로그인합니다(예: Facebook으로 로그인한 후 GitHub로 로그인). 이 경우 계정 연결을 요구하는 오류가 발생합니다.
사용자가 신뢰할 수 있는 제공업체로 로그인한 후 동일한 이메일을 사용하여 신뢰할 수 없는 제공업체로 로그인합니다(예: Google로 로그인한 후 Facebook으로 로그인). 이 경우 계정 연결을 요구하는 오류가 발생합니다.
사용자가 신뢰할 수 없는 공급업체로 로그인한 후 동일한 이메일을 사용하여 신뢰할 수 있는 공급업체로 로그인합니다(예: Facebook으로 로그인한 후 Google로 로그인). 신뢰할 수 있는 제공업체가 신뢰할 수 없는 제공업체를 덮어씁니다. 사용자가 Facebook으로 다시 로그인을 시도하는 경우 계정 연결을 요구하는 오류가 발생합니다.
사용자가 신뢰할 수 있는 제공업체로 로그인한 후 동일한 이메일을 사용하여 신뢰할 수 있는 다른 제공업체로 로그인합니다(예: Apple로 로그인한 후 Google로 로그인). 두 제공업체 모두 오류 없이 연결됩니다.
Admin SDK를 사용하여 이메일을 인증된 것으로 직접 설정할 수 있지만 사용자가 해당 이메일을 실제로 소유하고 있음을 알고 있는 경우에만 이를 설정하는 것이 좋습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eIdentity Platform's user object represents a user account in a Google Cloud project, and each project shares a user database across all its apps.\u003c/p\u003e\n"],["\u003cp\u003eUser objects have fixed properties like a unique ID, email, name, and photo URL, which can be updated by the user, and additional properties can be stored in external services.\u003c/p\u003e\n"],["\u003cp\u003eUsers can sign in using various methods, including email and password, federated identity providers, or a custom auth system, and can associate multiple sign-in methods with a single account.\u003c/p\u003e\n"],["\u003cp\u003eIdentity Platform manages the current user's state, persisting it across page refreshes or app restarts, but this state is cleared upon sign-out, although the user instance remains functional.\u003c/p\u003e\n"],["\u003cp\u003eIdentity Platform distinguishes between trusted and untrusted identity providers for email verification and automatically links user accounts when users sign in with different trusted providers using the same email, while requiring manual linking for untrusted provider combinations.\u003c/p\u003e\n"]]],[],null,["# Identity Platform users in projects\n===================================\n\nThe Identity Platform **user** object represents a user account that has signed\nup for an app in your\nGoogle Cloud\nproject. Apps usually have many registered users, and every app in a\nGoogle Cloud\nproject shares a user database.\n\nUser instances are independent from Identity Platform instances, so you can have\nseveral references to different users within the same context and still call any\nof their methods.\n\nUser properties\n---------------\n\nIdentity Platform users have a fixed set of basic properties---a unique\nID, a primary email address, a name and a photo URL---stored in the\nproject's user database, that can be updated by the user\n([iOS](https://firebase.google.com/docs/auth/ios/manage-users#update_a_users_profile),\n[Android](https://firebase.google.com/docs/auth/android/manage-users#update_a_users_profile),\n[web](https://firebase.google.com/docs/auth/web/manage-users#update_a_users_profile)).\nYou cannot add other properties to the user object directly; instead, you can\nstore the additional properties in any other storage services, like Google Cloud\nFirestore.\n\nThe first time a user signs up to your app, the user's profile data is populated\nusing the available information:\n\n- If the user signed up with an email address and password, only the primary email address property is populated\n- If the user signed up with a federated identity provider, such as Google or Facebook, the account information made available by the provider is used to populate the user's profile\n- If the user signed up with your custom auth system, you must explicitly add the information you want to the user's profile\n\nOnce a user account has been created, you can reload the user's information to\nincorporate any changes the user might have made on another device.\n\nSign-in providers\n-----------------\n\nYou can sign in users to your apps using several methods:\nemail address and password, federated identity providers, and your custom auth\nsystem. You can associate more than one sign-in method with a user: for example,\na user can sign in to the same account using an email address and a password, or\nusing Google Sign-In.\n\nUser instances keep track of every provider linked to the user. This allows you\nto update empty profile's properties using the information given by a provider.\nSee Managing Users\n([iOS](https://firebase.google.com/docs/auth/ios/manage-users#get_a_users_provider-specific_profile_information),\n[Android](https://firebase.google.com/docs/auth/android/manage-users#get_a_users_provider-specific_profile_information),\n[web](https://firebase.google.com/docs/auth/web/manage-users#get_a_users_provider-specific_profile_information)).\n\nThe current user\n----------------\n\nWhen a user signs up or signs in, that user becomes the current user of the\nAuth instance. The instance persists the user's state, so that refreshing the\npage (in a browser) or restarting the application doesn't lose the user's\ninformation.\n\nWhen the user signs out, the Auth instance stops keeping a reference to the user\nobject and no longer persists its state; there is no current user. However, the\nuser instance continues to be completely functional: if you keep a reference to\nit, you can still access and update the user's data.\n\nThe user lifecycle\n------------------\n\nThe recommended way to track the current state of the Auth instance is by using\nlisteners (also called \"observers\" in JavaScript). An Auth listener gets\nnotified any time something relevant happens to the Auth object. See Managing\nUsers\n([iOS](https://firebase.google.com/docs/auth/ios/manage-users#get_the_currently_signed-in_user),\n[Android](https://firebase.google.com/docs/auth/android/manage-users#get_the_currently_signed-in_user),\n[web](https://firebase.google.com/docs/auth/web/manage-users#get_the_currently_signed-in_user)).\n\nAn Auth listener gets notified in the following situations:\n\n- The Auth object finishes initializing and a user was already signed in from a previous session, or has been redirected from an identity provider's sign-in flow\n- A user signs in (the current user is set)\n- A user signs out (the current user becomes null)\n- The current user's access token is refreshed. This case can happen in the following conditions:\n - The access token expires: this is a common situation. The refresh token is used to get a new valid set of tokens.\n - The user changes their password: Identity Platform issues new access and refresh tokens and renders the old tokens expired. This automatically expires the user's token and/or signs out the user on every device, for security reasons.\n - The user re-authenticates: some actions require that the user's credentials are recently issued; such actions include deleting an account, setting a primary email address, and changing a password. Instead of signing out the user and then signing in the user again, get new credentials from the user, and pass the new credentials to the reauthenticate method of the user object.\n\nUser self-service\n-----------------\n\nBy default, Identity Platform enables users to sign-up and delete their accounts\nwithout administrative intervention. In many circumstances, this enables\nend-users to discover your application or service and onboard (or offboard) with\nminimal friction.\n\nThere are situations, however, where you want users to be manually or\nprogrammatically created by an administrator, either using the Admin SDK or\nGoogle Cloud console. In these cases, you can disable user actions from the\nIdentity Platform settings page, which prevents account creation and deletion by\nan end-user. If you use multi-tenancy, you need to make an HTTP request\n[to disable](/identity-platform/docs/reference/rest/v2/projects.tenants/patch)\nthese features on a per-tenant basis.\n\nIf an end-user attempts to create or delete an account within your system, the\nIdentity Platform service will return an error code:\n`auth/admin-restricted-operation` for Web API calls, or `ERROR_ADMIN_RESTRICTED_OPERATION` for Android and iOS. You should gracefully\nhandle the error on your front-end by asking the user to take the appropriate\nactions for your service.\n\nAuth tokens\n-----------\n\nWhen you perform authentication with Identity Platform, there are three\nkinds of auth tokens you might encounter:\n\nVerified email addresses\n------------------------\n\nIdentity Platform considers an email verified if it meets two conditions:\n\n1. The user completes the Identity Platform verification flow\n2. The email is verified by a trusted Identity Provider, or IdP for short.\n\nIdPs that verify email once, but then allow users to change email addresses without requiring re-verification, are not trusted. IdPs that either own the domain or always require verification are considered trusted.\n\nTrusted providers:\n\n- Google (for @gmail.com addresses)\n- Yahoo (for @yahoo.com addresses)\n- Microsoft (for @outlook.com and @hotmail.com addresses)\n- Apple (always verified, because accounts are always verified and multi-factor-authenticated)\n\nUntrusted providers:\n\n- Facebook\n- Twitter\n- GitHub\n- Google, Yahoo, and Microsoft for domains not issued by that Identity Provider\n- Email / Password without email verification\n\nIn some situations, Identity Platform will automatically link accounts when a user signs in with different providers using the same email address. This can only happen when specific criteria are met, however. To understand why, consider the following situation: a user signs in using Google with a @gmail.com account and a malicious actor creates an account using the same @gmail.com address, but signing in via Facebook. If these two accounts were automatically linked, the malicious actor would gain access to the user's account.\n\nThe following cases describe when we automatically link accounts and when we throw an error requiring user or developer action:\n\n- User signs in with an untrusted provider, then signs in with another untrusted provider with the same email (for example, Facebook followed by GitHub). This throws an error requiring account linking.\n- User signs in with a trusted provider, then signs in with untrusted provider with the same email (for example, Google followed by Facebook). This throws an error requiring account linking.\n- User signs in with an untrusted provider, then signs in with a trusted provider with the same email (for example, Facebook followed by Google). The trusted provider overwrites the untrusted provider. If the user attempts to sign in again with Facebook, it will cause an error requiring account linking.\n- User signs in with a trusted provider, then signs in with a different trusted provider with the same email (for example, Apple followed by Google). Both providers will be linked without errors.\n\nYou can manually set an email as verified by using the Admin SDK, but we recommend only doing this if you know the user really does own the email."]]
