اصالت‌سنجی با Firebase بااستفاده از «حساب‌های مبتنی بر گذرواژه» در Android

می‌توانید از Firebase Authentication استفاده کنید تا به کاربران اجازه دهید بااستفاده از نشانی‌های ایمیل و گذرواژه‌هایشان در Firebase اصالت‌سنجی کنند و حساب‌های مبتنی بر گذرواژه برنامه‌تان را مدیریت کنند.

برای کمک هوشواره‌ای، پیام‌واره زیر را در عامل کدنویسی هوش مصنوعی (مانند Gemini در Android Studio،‏ Antigravity،‏ Claude Code،‏ Codex، و Cursor) کپی کنید. می‌توانید پیام‌واره را سفارشی‌سازی کنید و با نماینده‌تان تکرار کنید. برای اطلاعات دقیق نصب، به مهارت‌های عامل Firebase مراجعه کنید. 

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up and use Firebase Authentication with email and password authentication in my app.

قبل از شروع

  1. اگر قبلاً این کار را نکرده‌اید، ‫Firebase را به پروژه Android خود اضافه کنید.

  2. اگر هنوز برنامه‌تان را به پروژه Firebase متصل نکرده‌اید، این کار را از کنسول Firebase انجام دهید.
  3. «ایمیل/گذرواژه» را به‌عنوان ارائه‌دهنده ورود به سیستم برای پروژه Firebase خود فعال کنید:
    1. در کنسول Firebase، به امنیت > اصالت‌سنجی بروید.
    2. در برگه روش ورود به سیستم، ارائه‌دهنده ورود به سیستم ایمیل/گذرواژه را فعال کنید.
    3. روی ذخیره کردن کلیک کنید.

  4. در فایل Gradle واحد (سطح برنامه) (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle)، وابستگی کتابخانه Firebase Authentication را برای Android اضافه کنید. توصیه می‌کنیم از Firebase Android BoM برای کنترل نسخه‌بندی کتابخانه استفاده کنید. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:35.0.0"))

    // Add the dependency for the Firebase Authentication library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-auth")
}

    بااستفاده از Firebase Android BoM، برنامه شما همیشه از نسخه‌های سازگار کتابخانه‌های Firebase Android استفاده خواهد کرد.

    (جایگزین)  افزودن وابستگی‌های کتابخانه Firebase بدون استفاده از BoM

    اگر انتخاب کنید که از Firebase BoM استفاده نکنید، باید نسخه هر کتابخانه Firebase را در خط وابستگی آن مشخص کنید.

    توجه داشته باشید که اگر از چند کتابخانه Firebase در برنامه‌تان استفاده می‌کنید، قویاً توصیه می‌کنیم از BoM برای مدیریت نسخه‌های کتابخانه استفاده کنید، که تضمین می‌کند همه نسخه‌ها سازگار باشند. 

    dependencies {
    // Add the dependency for the Firebase Authentication library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-auth:25.0.0")
}

ایجاد حساب مبتنی بر گذرواژه

برای ایجاد حساب کاربری جدید با گذرواژه، مراحل زیر را در فعالیت ورود به سیستم برنامه‌تان تکمیل کنید:

  1. در روش onCreate فعالیت ثبت‌نام، نمونه هم‌رسانی‌شده شیء FirebaseAuth را دریافت کنید:

    Kotlin

    private lateinit var auth: FirebaseAuth
// ...
// Initialize Firebase Auth
auth = Firebase.auth

    Java

    private FirebaseAuth mAuth;
// ...
// Initialize Firebase Auth
mAuth = FirebaseAuth.getInstance();
  2. هنگام مقداردهی اولیه «فعالیت»، بررسی کنید که آیا کاربر درحال‌حاضر به سیستم وارد شده است یا نه:

    Kotlin

    public override fun onStart() {
    super.onStart()
    // Check if user is signed in (non-null) and update UI accordingly.
    val currentUser = auth.currentUser
    if (currentUser != null) {
        reload()
    }
}

    Java

    @Override
public void onStart() {
    super.onStart();
    // Check if user is signed in (non-null) and update UI accordingly.
    FirebaseUser currentUser = mAuth.getCurrentUser();
    if(currentUser != null){
        reload();
    }
}
  3. وقتی کاربر جدیدی بااستفاده از فرم ثبت‌نام برنامه شما ثبت‌نام می‌کند، هر مرحله جدید اعتبارسنجی حساب را که برنامه شما لازم دارد تکمیل کنید، مثلاً تأیید کنید که گذرواژه حساب جدید به‌درستی تایپ شده است و الزامات پیچیدگی شما را برآورده می‌کند.
  4. با ارسال نشانی ایمیل و گذرواژه کاربر جدید به createUserWithEmailAndPassword، حساب جدیدی ایجاد کنید:

    Kotlin

    auth.createUserWithEmailAndPassword(email, password)
    .addOnCompleteListener(this) { task ->
        if (task.isSuccessful) {
            // Sign in success, update UI with the signed-in user's information
            Log.d(TAG, "createUserWithEmail:success")
            val user = auth.currentUser
            updateUI(user)
        } else {
            // If sign in fails, display a message to the user.
            Log.w(TAG, "createUserWithEmail:failure", task.exception)
            Toast.makeText(
                baseContext,
                "Authentication failed.",
                Toast.LENGTH_SHORT,
            ).show()
            updateUI(null)
        }
    }

    Java

    mAuth.createUserWithEmailAndPassword(email, password)
        .addOnCompleteListener(this, new OnCompleteListener<AuthResult>() {
            @Override
            public void onComplete(@NonNull Task<AuthResult> task) {
                if (task.isSuccessful()) {
                    // Sign in success, update UI with the signed-in user's information
                    Log.d(TAG, "createUserWithEmail:success");
                    FirebaseUser user = mAuth.getCurrentUser();
                    updateUI(user);
                } else {
                    // If sign in fails, display a message to the user.
                    Log.w(TAG, "createUserWithEmail:failure", task.getException());
                    Toast.makeText(EmailPasswordActivity.this, "Authentication failed.",
                            Toast.LENGTH_SHORT).show();
                    updateUI(null);
                }
            }
        });
    اگر حساب جدید ایجاد شده باشد، کاربر نیز به سیستم وارد می‌شود. در تماس برگشتی، می‌توانید از روش getCurrentUser برای دریافت داده‌های حساب کاربر استفاده کنید.

کاربری را با نشانی ایمیل و گذرواژه به سیستم وارد کنید

مراحل ورود به سیستم کاربر با گذرواژه مشابه مراحل ایجاد حساب جدید است. در فعالیت ورود به سیستم برنامه‌تان، این کارها را انجام دهید:

  1. در روش onCreate فعالیت ورود به سیستم، نمونه هم‌رسانی‌شده شیء FirebaseAuth را دریافت کنید:

    Kotlin

    private lateinit var auth: FirebaseAuth
// ...
// Initialize Firebase Auth
auth = Firebase.auth

    Java

    private FirebaseAuth mAuth;
// ...
// Initialize Firebase Auth
mAuth = FirebaseAuth.getInstance();
  2. هنگام مقداردهی اولیه «فعالیت»، بررسی کنید که آیا کاربر درحال‌حاضر به سیستم وارد شده است یا نه:

    Kotlin

    public override fun onStart() {
    super.onStart()
    // Check if user is signed in (non-null) and update UI accordingly.
    val currentUser = auth.currentUser
    if (currentUser != null) {
        reload()
    }
}

    Java

    @Override
public void onStart() {
    super.onStart();
    // Check if user is signed in (non-null) and update UI accordingly.
    FirebaseUser currentUser = mAuth.getCurrentUser();
    if(currentUser != null){
        reload();
    }
}
  3. وقتی کاربری به سیستم برنامه‌تان وارد می‌شود، نشانی ایمیل و گذرواژه کاربر را به signInWithEmailAndPassword ارسال کنید:

    Kotlin

    auth.signInWithEmailAndPassword(email, password)
    .addOnCompleteListener(this) { task ->
        if (task.isSuccessful) {
            // Sign in success, update UI with the signed-in user's information
            Log.d(TAG, "signInWithEmail:success")
            val user = auth.currentUser
            updateUI(user)
        } else {
            // If sign in fails, display a message to the user.
            Log.w(TAG, "signInWithEmail:failure", task.exception)
            Toast.makeText(
                baseContext,
                "Authentication failed.",
                Toast.LENGTH_SHORT,
            ).show()
            updateUI(null)
        }
    }

    Java

    mAuth.signInWithEmailAndPassword(email, password)
        .addOnCompleteListener(this, new OnCompleteListener<AuthResult>() {
            @Override
            public void onComplete(@NonNull Task<AuthResult> task) {
                if (task.isSuccessful()) {
                    // Sign in success, update UI with the signed-in user's information
                    Log.d(TAG, "signInWithEmail:success");
                    FirebaseUser user = mAuth.getCurrentUser();
                    updateUI(user);
                } else {
                    // If sign in fails, display a message to the user.
                    Log.w(TAG, "signInWithEmail:failure", task.getException());
                    Toast.makeText(EmailPasswordActivity.this, "Authentication failed.",
                            Toast.LENGTH_SHORT).show();
                    updateUI(null);
                }
            }
        });
    اگر ورود به سیستم موفقیت‌آمیز بود، می‌توانید از FirebaseUser برگشتی برای ادامه استفاده کنید.

توصیه‌شده: خط‌مشی گذرواژه تنظیم کنید

با اعمال الزامات پیچیدگی گذرواژه می‌توانید امنیت حساب را بهبود دهید.

برای پیکربندی خط‌مشی گذرواژه برای پروژه، بخش خط‌مشی گذرواژه را در برگه امنیت > اصالت‌سنجی > تنظیمات کنسول Firebase باز کنید:

تنظیمات اصالت‌سنجی

خط‌مشی‌های گذرواژه Firebase Authentication از الزامات گذرواژه زیر پشتیبانی می‌کنند:

  • نویسه حرف کوچک لازم است

  • نویسه حروف بزرگ لازم است

  • نویسه عددی لازم است

  • نویسه غیرالفباعددی لازم است

    نویسه‌های زیر شرط نویسه غیرالفباعددی را برآورده می‌کنند: ^ $ * . [ ] { } ( ) ? " ! @ # % & / \ , > < ' : ; | _ ~

  • حداقل طول گذرواژه (از ۶ تا ۳۰ نویسه متغیر است؛ مقدار پیش‌فرض ۶ است)

  • حداکثر طول گذرواژه (حداکثر طول ۴۰۹۶ نویسه)

می‌توانید اجرای خط‌مشی گذرواژه را در دو حالت فعال کنید:

  • الزامی: تلاش برای ثبت‌نام تا زمانی‌که کاربر گذرواژه‌ای مطابق با خط‌مشی شما به‌روزرسانی نکند ناموفق خواهد بود.

  • اعلان: کاربران مجازند با گذرواژه غیرمنطبق ثبت‌نام کنند. هنگام استفاده از این حالت، باید بررسی کنید که آیا گذرواژه کاربر با خط‌مشی سمت مشتری مطابقت دارد یا نه و اگر مطابقت ندارد، به نحوی از کاربر بخواهید گذرواژه خود را به‌روز کند.

کاربران جدید همیشه ملزم به انتخاب گذرواژه‌ای هستند که با خط‌مشی شما مطابقت داشته باشد.

اگر کاربر فعال دارید، توصیه می‌کنیم ارتقای اجباری را در ورود به سیستم فعال نکنید مگر اینکه قصد داشته باشید دسترسی کاربرانی را که گذرواژه‌هایشان با خط‌مشی شما مطابقت ندارد مسدود کنید. به‌جای آن، از حالت اعلان استفاده کنید که به کاربران امکان می‌دهد با گذرواژه‌های فعلی‌شان به سیستم وارد شوند و به آن‌ها اطلاع می‌دهد که گذرواژه‌شان چه شرایطی را ندارد.

توصیه می‌شود: محافظت دربرابر شمارش ایمیل را فعال کنید

برخی‌از روش‌های Firebase Authentication که نشانی‌های ایمیل را به‌عنوان پارامتر می‌گیرند، اگر نشانی ایمیل ثبت‌نشده باشد درحالی‌که باید ثبت‌شده باشد (برای مثال، هنگام ورود به سیستم با نشانی ایمیل و گذرواژه)، یا ثبت‌شده باشد درحالی‌که باید استفاده‌نشده باشد (برای مثال، هنگام تغییر نشانی ایمیل کاربر)، خطاهای خاصی را برمی‌گردانند. اگرچه این کار می‌تواند برای پیشنهاد کردن راهکارهای درمانی خاص به کاربران مفید باشد، اما بازیگران مخرب نیز می‌توانند از آن سوءاستفاده کنند تا نشانی‌های ایمیل ثبت‌شده توسط کاربران شما را کشف کنند.

برای کاهش این خطر، توصیه می‌کنیم مطمئن شوید که محافظت از شمارش ایمیل برای پروژه شما فعال باشد. می‌توانید این تنظیم را در کنسول Firebase بررسی کنید: به امنیت > اصالت‌سنجی > برگه تنظیمات بروید، و سپس روی کنش‌های کاربر کلیک کنید.

توجه داشته باشید که فعال کردن این ویژگی رفتار گزارش خطا را برای Firebase Authentication تغییر می‌دهد، بنابراین مطمئن شوید که برنامه‌تان به خطاهای خاص‌تر متکی نباشد.

مراحل بعدی

پس‌از اینکه کاربر برای اولین‌بار به سیستم وارد شد، حساب کاربری جدیدی ایجاد می‌شود و به اطلاعات اعتباری—یعنی نام کاربری و گذرواژه، شماره تلفن، یا اطلاعات ارائه‌دهنده اصالت‌سنجی—که کاربر با آن به سیستم وارد شده است پیوند داده می‌شود. این حساب جدید به‌عنوان بخشی از پروژه Firebase شما ذخیره می‌شود و می‌توان از آن برای شناسایی کاربر در همه برنامه‌های پروژه شما، صرف‌نظر از نحوه ورود کاربر به سیستم، استفاده کرد.

  • در برنامه‌هایتان، می‌توانید اطلاعات نمایه پایه کاربر را از FirebaseUser شیء دریافت کنید. مدیریت کاربران را ببینید.

  • در Firebase Realtime Database و Cloud Storage قوانین امنیتی، می‌توانید شناسه کاربر یکتای کاربر واردشده به سیستم را از متغیر auth دریافت کنید و از آن برای کنترل داده‌هایی که کاربر می‌تواند به آن‌ها دسترسی داشته باشد استفاده کنید.

می‌توانید به کاربران اجازه دهید با پیوند دادن اطلاعات اعتباری ارائه‌دهنده اصالت‌سنجی به حساب کاربری موجود بااستفاده از چندین ارائه‌دهنده اصالت‌سنجی به سیستم برنامه‌تان وارد شوند.

برای خروج از سیستم کاربر، signOut را فراخوانی کنید:

Kotlin

Firebase.auth.signOut()

Java

FirebaseAuth.getInstance().signOut();