اصالت‌سنجی بااستفاده از GitHub در پلاتفرم‌های Apple

با ادغام «ورود به سیستم OAuth» عمومی در برنامه‌تان بااستفاده از «کیت توسعه نرم‌افزار Firebase» برای اجرای جریان ورود به سیستم سرتاسر، می‌توانید به کاربران اجازه دهید بااستفاده از ارائه‌دهندگان OAuth مانند GitHub، با Firebase اصالت‌سنجی کنند.

قبل از شروع

برای ورود به سیستم کاربران بااستفاده از حساب‌های GitHub، ابتدا باید GitHub را به‌عنوان ارائه‌دهنده ورود به سیستم برای پروژه Firebase خود فعال کنید:

از Swift Package Manager برای نصب و مدیریت وابستگی‌های Firebase استفاده کنید.

به راهنمای نصب ما مراجعه کنید تا با روش‌های مختلفی که می‌توانید کیت‌های توسعه نرم‌افزار Firebase را به پروژه Apple خود اضافه کنید آشنا شوید.

1. در Xcode، درحالی‌که پروژه برنامه‌تان باز است، به File > Add Packages (فایل > افزودن بسته‌ها) بروید.
2. وقتی خواسته شد، مخزن کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple را اضافه کنید:

  https://github.com/firebase/firebase-ios-sdk.git

توجه: پروژه‌های جدید باید از نسخه پیش‌فرض (جدیدترین) کیت توسعه نرم‌افزار استفاده کنند، اما درصورت نیاز می‌توانید نسخه قدیمی‌تری را انتخاب کنید.
3. کتابخانه Firebase Authentication را انتخاب کنید.
4. پرچم -ObjC را به بخش Other Linker Flags (سایر پرچم‌های پیونددهنده) در تنظیمات ساخت هدف اضافه کنید.
5. وقتی تمام شد، Xcode به‌طور خودکار شروع به حل و بارگیری وابستگی‌های شما در پس‌زمینه می‌کند.

اکنون، چند مرحله پیکربندی را انجام دهید:

1. در کنسول Firebase، به امنیت > اصالت‌سنجی بروید.
2. در برگه روش ورود به سیستم، ارائه‌دهنده ورود به سیستم GitHub را فعال کنید.
3. شناسه کارخواه و رمز کارخواه را از کنسول توسعه‌دهنده آن ارائه‌دهنده به پیکربندی ارائه‌دهنده اضافه کنید:
   1. برنامه‌تان را به‌عنوان برنامه توسعه‌دهنده در GitHub ثبت کنید و شناسه کارخواه و رمز کارخواه OAuth 2.0 برنامه‌تان را دریافت کنید.
   2. مطمئن شوید URI تغییرمسیر OAuth Firebase شما (برای مثال، my-app-12345.firebaseapp.com/__/auth/handler) به‌عنوان نشانی وب فراخوانی برگشتی «اجازه‌نامه» در صفحه تنظیمات برنامه‌تان در پیکربندی برنامه GitHub شما تنظیم شده باشد.
4. روی ذخیره کردن کلیک کنید.

جریان ورود به سیستم را با کیت توسعه نرم‌افزار Firebase مدیریت کنید

برای مدیریت جریان ورود به سیستم با کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple، این مراحل را دنبال کنید:

1. طرح‌واره‌های نشانی وب سفارشی را به پروژه Xcode خود اضافه کنید:

   1. پیکربندی پروژه را باز کنید: روی نام پروژه در نمای درختی سمت راست دوکلیک کنید. برنامه‌تان را از بخش TARGETS انتخاب کنید، سپس برگه Info را انتخاب کنید و بخش URL Types را ازهم باز کنید.
   2. روی دکمه + کلیک کنید و «شناسه برنامه کدگذاری‌شده» خود را به‌عنوان طرح‌واره نشانی وب اضافه کنید. فیلدهای دیگر را خالی بگذارید.

      می‌توانید «شناسه برنامه کدبندی‌شده» را در کنسول Firebase پیدا کنید: به تنظیمات > برگه موارد کلی بروید، سپس به بخش برنامه‌های شما پیمایش کنید تا جزئیات مربوط به برنامه iOS خود را مشاهده کنید.

      پس‌از تکمیل، پیکربندی شما باید چیزی شبیه به موارد زیر باشد (اما با مقادیر مختص برنامه‌تان):

      

2. بااستفاده از شناسه ارائه‌دهنده github.com، نمونه‌ای از OAuthProvider ایجاد کنید.

   Swift

       var provider = OAuthProvider(providerID: "github.com")
       

   Objective-C

       FIROAuthProvider *provider = [FIROAuthProvider providerWithProviderID:@"github.com"];
       

3. اختیاری: پارامترهای OAuth سفارشی دیگری را که می‌خواهید با درخواست OAuth ارسال شود مشخص کنید.

   Swift

       provider.customParameters = [
         "allow_signup": "false"
       ]
       

   Objective-C

       [provider setCustomParameters:@{@"allow_signup": @"false"}];
       

   برای پارامترهایی که GitHub پشتیبانی می‌کند، اسناد GitHub OAuth را ببینید. توجه داشته باشید که نمی‌توانید پارامترهای الزامی Firebase را با setCustomParameters ارسال کنید. این پارامترها عبارت‌اند از client_id، redirect_uri، response_type، scope، و state.

4. اختیاری: دامنه‌های OAuth 2.0 دیگری را علاوه‌بر نمایه اصلی که می‌خواهید از ارائه‌دهنده اصالت‌سنجی درخواست کنید مشخص کنید. اگر برنامه شما به دسترسی به داده‌های خصوصی کاربر از GitHub API نیاز دارد، باید درخواست اجازه‌های دسترسی به GitHub API را در بخش اجازه‌های API در کنسول توسعه‌دهنده GitHub ارسال کنید. گستره‌های OAuth درخواست‌شده باید دقیقاً با گستره‌های ازپیش‌پیکربندی‌شده در اجازه‌های میانای برنامه‌سازی کاربردی برنامه مطابقت داشته باشد.

   Swift

       // Request read access to a user's email addresses.
       // This must be preconfigured in the app's API permissions.
       provider.scopes = ["user:email"]
       

   Objective-C

       // Request read access to a user's email addresses.
       // This must be preconfigured in the app's API permissions.
       [provider setScopes:@[@"user:email"]];
       

   برای کسب اطلاعات بیشتر، به اسناد دامنه‌های GitHub مراجعه کنید.

5. اختیاری: اگر می‌خواهید نحوه ارائه SFSafariViewController یا UIWebView توسط برنامه‌تان را هنگام نمایش reCAPTCHA به کاربر سفارشی‌سازی کنید، کلاس سفارشی‌ای ایجاد کنید که با پروتکل AuthUIDelegate مطابقت داشته باشد و آن را به credentialWithUIDelegate ارسال کنید.

6. بااستفاده از شیء ارائه‌دهنده OAuth، با Firebase اصالت‌سنجی کنید.

   Swift

       provider.getCredentialWith(nil) { credential, error in
         if error != nil {
           // Handle error.
         }
         if credential != nil {
           Auth().signIn(with: credential) { authResult, error in
             if error != nil {
               // Handle error.
             }
             // User is signed in.
             // IdP data available in authResult.additionalUserInfo.profile.
   
             guard let oauthCredential = authResult.credential as? OAuthCredential else { return }
             // GitHub OAuth access token can also be retrieved by:
             // oauthCredential.accessToken
             // GitHub OAuth ID token can be retrieved by calling:
             // oauthCredential.idToken
           }
         }
       }
       

   Objective-C

       [provider getCredentialWithUIDelegate:nil
                                  completion:^(FIRAuthCredential *_Nullable credential,
                                               NSError *_Nullable error) {
         if (error) {
          // Handle error.
         }
         if (credential) {
           [[FIRAuth auth] signInWithCredential:credential
                                     completion:^(FIRAuthDataResult *_Nullable authResult,
                                               NSError *_Nullable error) {
             if (error) {
               // Handle error.
             }
             // User is signed in.
             // IdP data available in authResult.additionalUserInfo.profile.
   
             FIROAuthCredential *oauthCredential = (FIROAuthCredential *)authResult.credential;
             // GitHub OAuth access token can also be retrieved by:
             // oauthCredential.accessToken
             // GitHub OAuth ID token can be retrieved by calling:
             // oauthCredential.idToken
           }];
         }
       }];
       

   بااستفاده از کد دسترسی OAuth، می‌توانید GitHub API را فراخوانی کنید.

   برای مثال، برای دریافت اطلاعات نمایه پایه، می‌توانید REST API را فراخوانی کنید، و کد دسترسی را در سرصفحه Authorization ارسال کنید:

   https://api.github.com/user

7. درحالی‌که مثال‌های بالا بر جریان‌های ورود به سیستم تمرکز دارند، شما همچنین می‌توانید یک ارائه‌دهنده GitHub را به یک کاربر موجود پیوند دهید. برای مثال، می‌توانید چندین ارائه‌دهنده را به یک کاربر پیوند دهید تا بتواند با هرکدام از آن‌ها به سیستم وارد شود.

   Swift

       Auth().currentUser.link(withCredential: credential) { authResult, error in
         if error != nil {
           // Handle error.
         }
         // GitHub credential is linked to the current user.
         // IdP data available in authResult.additionalUserInfo.profile.
         // GitHub OAuth access token can also be retrieved by:
         // (authResult.credential as? OAuthCredential)?.accessToken
         // GitHub OAuth ID token can be retrieved by calling:
         // (authResult.credential as? OAuthCredential)?.idToken
       }
       

   Objective-C

       [[FIRAuth auth].currentUser
           linkWithCredential:credential
                   completion:^(FIRAuthDataResult * _Nullable authResult, NSError * _Nullable error) {
         if (error) {
           // Handle error.
         }
         // GitHub credential is linked to the current user.
         // IdP data available in authResult.additionalUserInfo.profile.
         // GitHub OAuth access token is can also be retrieved by:
         // ((FIROAuthCredential *)authResult.credential).accessToken
         // GitHub OAuth ID token can be retrieved by calling:
         // ((FIROAuthCredential *)authResult.credential).idToken
       }];
       

8. از همین الگو می‌توان با reauthenticateWithCredential استفاده کرد که می‌توان از آن برای بازیابی اعتبارنامه‌های جدید برای عملیات حساس که نیاز به ورود به سیستم اخیر دارند استفاده کرد.

   Swift

       Auth().currentUser.reauthenticateWithCredential(withCredential: credential) { authResult, error in
         if error != nil {
           // Handle error.
         }
         // User is re-authenticated with fresh tokens minted and
         // should be able to perform sensitive operations like account
         // deletion and email or password update.
         // IdP data available in result.additionalUserInfo.profile.
         // Additional OAuth access token is can also be retrieved by:
         // (authResult.credential as? OAuthCredential)?.accessToken
         // GitHub OAuth ID token can be retrieved by calling:
         // (authResult.credential as? OAuthCredential)?.idToken
       }
       

   Objective-C

       [[FIRAuth auth].currentUser
           reauthenticateWithCredential:credential
                             completion:^(FIRAuthDataResult * _Nullable authResult, NSError * _Nullable error) {
         if (error) {
           // Handle error.
         }
         // User is re-authenticated with fresh tokens minted and
         // should be able to perform sensitive operations like account
         // deletion and email or password update.
         // IdP data available in result.additionalUserInfo.profile.
         // Additional OAuth access token is can also be retrieved by:
         // ((FIROAuthCredential *)authResult.credential).accessToken
         // GitHub OAuth ID token can be retrieved by calling:
         // ((FIROAuthCredential *)authResult.credential).idToken
       }];
       

رسیدگی به خطاهای «حساب با اعتبارنامه دیگری وجود دارد»

اگر تنظیم یک حساب برای هر نشانی ایمیل را در کنسول Firebase فعال کرده باشید، وقتی کاربری سعی می‌کند با ایمیلی که قبلاً برای ارائه‌دهنده کاربر Firebase دیگری (مثل Google) وجود دارد به سیستم ارائه‌دهنده‌ای (مثل GitHub) وارد شود، خطای FIRAuthErrorCodeAccountExistsWithDifferentCredential به‌همراه شیء موقت FIRAuthCredential (اعتبارنامه GitHub) ایجاد می‌شود. برای تکمیل ورود به سیستم ارائه‌دهنده موردنظر، کاربر باید ابتدا به سیستم ارائه‌دهنده موجود (Google) وارد شود و سپس به FIRAuthCredential قبلی (اعتبارنامه GitHub) پیوند دهد. این مورد به‌صورت زیر نشان داده می‌شود:

Swift

  // Sign-in with an OAuth credential.
  provider.getCredentialWith(nil) { credential, error in
    // An account with the same email already exists.
    if (error as NSError?)?.code == AuthErrorCode.accountExistsWithDifferentCredential.rawValue {
      // Get pending credential and email of existing account.
      let existingAcctEmail = (error! as NSError).userInfo[AuthErrorUserInfoEmailKey] as! String
      let pendingCred = (error! as NSError).userInfo[AuthErrorUserInfoUpdatedCredentialKey] as! AuthCredential
      // Lookup existing account identifier by the email.
      Auth.auth().fetchProviders(forEmail:existingAcctEmail) { providers, error in
        // Existing email/password account.
        if (providers?.contains(EmailAuthProviderID))! {
          // Existing password account for email. Ask user to provide the password of the
          // existing account.
          // Sign in with existing account.
          Auth.auth().signIn(withEmail:existingAcctEmail, password:password) { user, error in
            // Successfully signed in.
            if user != nil {
              // Link pending credential to account.
              Auth.auth().currentUser?.linkAndRetrieveData(with: pendingCred) { result, error in
                // ...
              }
            }
          }
        }
      }
      return
    }

    // Other errors.
    if error != nil {
      // handle the error.
      return
    }

    // Sign in with the credential.
    if credential != nil {
      Auth.auth().signInAndRetrieveData(with: credential!) { result, error in
        if error != nil {
          // handle the error.
          return
        }
      }
    }
  }

  

Objective-C

  // Sign-in with an OAuth credential.
  [provider getCredentialWithUIDelegate:nil
                             completion:^(FIRAuthCredential *_Nullable credential, NSError *_Nullable error) {
    // An account with the same email already exists.
    if (error.code == FIRAuthErrorCodeAccountExistsWithDifferentCredential) {
      // Get pending credential and email of existing account.
      NSString *existingAcctEmail = error.userInfo[FIRAuthErrorUserInfoEmailKey];
      FIRAuthCredential *pendingCred = error.userInfo[FIRAuthErrorUserInfoUpdatedCredentialKey];
      // Lookup existing account identifier by the email.
      [[FIRAuth auth] fetchProvidersForEmail:existingAcctEmail
                                 completion:^(NSArray<NSString *> *_Nullable providers,
                                              NSError *_Nullable error) {
        // Existing email/password account.
        if ( [providers containsObject:FIREmailAuthProviderID] ) {
          // Existing password account for email. Ask user to provide the password of the
          // existing account.

          // Sign in with existing account.
          [[FIRAuth auth] signInWithEmail:existingAcctEmail
                                 password:password
                               completion:^(FIRUser *user, NSError *error) {
            // Successfully signed in.
            if (user) {
              // Link pending credential to account.
              [[FIRAuth auth].currentUser linkWithCredential:pendingCred
                                                  completion:^(FIRUser *_Nullable user,
                                                               NSError *_Nullable error) {
                // ...
              }];
            }
          }];
        }
      }];
      return;
    }

    // Other errors.
    if (error) {
      // handle the error.
      return;
    }

    // Sign in with the credential.
    if (credential) {
      [[FIRAuth auth] signInAndRetrieveDataWithCredential:credential
          completion:^(FIRAuthDataResult *_Nullable authResult,
                       NSError *_Nullable error) {
        if (error) {
          // handle the error.
          return;
        }
      }];
    }
  }];
  

مراحل بعدی

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

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

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

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

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

Swift

let firebaseAuth = Auth.auth()
do {
  try firebaseAuth.signOut()
} catch let signOutError as NSError {
  print("Error signing out: %@", signOutError)
}

Objective-C

NSError *signOutError;
BOOL status = [[FIRAuth auth] signOut:&signOutError];
if (!status) {
  NSLog(@"Error signing out: %@", signOutError);
  return;
}

همچنین ممکن است بخواهید کد رسیدگی به خطا را برای طیف کامل خطاهای اصالت‌سنجی اضافه کنید. رسیدگی به خطاها را ببینید.