Firebase Authentication'ı engelleme işlevleriyle genişletme

Engelleme işlevleri, bir kullanıcının uygulamanıza kaydolmasının veya oturum açmasının sonucunu değiştiren özel bir kod yürütmenize olanak tanır. Örneğin, belirli ölçütleri karşılamayan bir kullanıcının kimlik doğrulaması yapmasını engelleyebilir veya kullanıcıyı istemci uygulamanıza döndürmeden önce bilgilerini güncelleyebilirsiniz.

Başlamadan önce

Engelleme işlevlerini kullanmak için Firebase projenizi, Identity Platform ile Firebase Authentication'a yükseltmeniz gerekir. Henüz yükseltme yapmadıysanız önce yükseltme yapın.

Engelleme işlevlerini anlama

Engelleme işlevlerini iki etkinlik için kaydedebilirsiniz:

• beforeCreate: Yeni bir kullanıcı Firebase Authentication veritabanına kaydedilmeden ve istemci uygulamanıza jeton döndürülmeden önce tetiklenir.

• beforeSignIn: Kullanıcının kimlik bilgileri doğrulandıktan sonra ancak Firebase Authentication istemci uygulamanıza kimlik jetonu döndürmeden önce tetiklenir. Uygulamanızda çok öğeli kimlik doğrulaması kullanılıyorsa işlev, kullanıcı ikinci faktör olduğunu doğruladıktan sonra tetiklenir. Yeni bir kullanıcı oluşturma işleminin beforeCreate ek olarak beforeSignIn öğesini de tetiklediğini unutmayın.

Engelleme işlevlerini kullanırken aşağıdakileri göz önünde bulundurun:

• İşleviniz 7 saniye içinde yanıt vermelidir. 7 saniye sonra Firebase Authentication hata döndürür ve istemci işlemi başarısız olur.

• 200 dışındaki HTTP yanıt kodları istemci uygulamalarınıza iletilir. İstemci kodunuzun, işlevinizin döndürebileceği hataları işlediğinden emin olun.

• İşlevler, kiracıda bulunanlar da dahil projenizdeki tüm kullanıcılar için geçerlidir. Firebase Authentication, kullanıcıların üyesi oldukları kiracılar da dahil olmak üzere işlevinizin kullanıcıları hakkında bilgi sağlar. Böylece siz de buna göre yanıt verebilirsiniz.

• Başka bir kimlik sağlayıcıyı bir hesaba bağlamak, kayıtlı tüm beforeSignIn işlevlerini yeniden tetikler.

• Anonim ve özel kimlik doğrulama, engelleme işlevlerini tetiklemez.

Engelleme işlevi dağıtma

Özel kodunuzu kullanıcı kimlik doğrulama akışlarına eklemek için engelleme işlevlerini dağıtın. Engelleme işlevleriniz dağıtıldıktan sonra, kimlik doğrulama ve kullanıcı oluşturma işleminin başarılı olması için özel kodunuzun başarıyla tamamlanması gerekir.

Engelleme işlevini, herhangi bir işlevi dağıttığınız şekilde dağıtırsınız. (ayrıntılar için Cloud Functions Başlarken sayfasına bakın). Özet olarak:

1. beforeCreate etkinliğini, beforeSignIn etkinliğini veya her ikisini birden işleyen Cloud Functions işlevleri yazın.

   Örneğin, başlamak için index.js öğesine aşağıdaki işlemsiz işlevleri ekleyebilirsiniz:

   const functions = require('firebase-functions');
   
   exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
     // TODO
   });
   
   exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
     // TODO
   });
   

   Yukarıdaki örneklerde özel kimlik doğrulama mantığının uygulanması atlanmıştır. Engelleme işlevlerinizi nasıl uygulayacağınızı öğrenmek için aşağıdaki bölümlere ve spesifik örnekler için Sık karşılaşılan senaryolar bölümüne bakın.

2. Firebase CLI'yı kullanarak işlevlerinizi dağıtın:

   firebase deploy --only functions
   

   İşlevlerinizi her güncellediğinizde yeniden dağıtmanız gerekir.

Kullanıcı ve bağlam bilgilerini alma

beforeSignIn ve beforeCreate etkinlikleri, oturum açan kullanıcıyla ilgili bilgiler içeren User ve EventContext nesneleri sağlar. Bir işlemin devam etmesine izin verilip verilmeyeceğini belirlemek için kodunuzda bu değerleri kullanın.

User nesnesinde kullanılabilen özelliklerin listesi için UserRecord API referansına bakın.

EventContext nesnesi aşağıdaki özellikleri içerir:

Kayıt veya oturum açmayı engelleme

Bir kayıt veya oturum açma girişimini engellemek için işlevinize HttpsError komutunu ekleyin. Örnek:

throw new functions.auth.HttpsError('permission-denied');

Aşağıdaki tabloda, bildirebileceğiniz hatalar ve varsayılan hata mesajları listelenmiştir:

Özel bir hata mesajı da belirtebilirsiniz:

throw new functions.auth.HttpsError('permission-denied', 'Unauthorized request origin!');

Aşağıdaki örnekte, belirli bir alanda olmayan kullanıcıların uygulamanıza kaydolmasını nasıl engelleyeceğiniz gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  // (If the user is authenticating within a tenant context, the tenant ID can be determined from
  // user.tenantId or from context.resource, e.g. 'projects/project-id/tenant/tenant-id-1')

  // Only users of a specific domain can sign up.
  if (user.email.indexOf('@acme.com') === -1) {
    throw new functions.auth.HttpsError('invalid-argument', `Unauthorized email "${user.email}"`);
  }
});

Varsayılan veya özel mesaj kullanma durumunuzdan bağımsız olarak, Cloud Functions hatayı sarmalar ve istemciye dahili hata olarak döndürür. Örnek:

throw new functions.auth.HttpsError('invalid-argument', `Unauthorized email user@evil.com}`);

Uygulamanız hatayı yakalamalı ve uygun şekilde işlemelidir. Örnek:

// Blocking functions can also be triggered in a multi-tenant context before user creation.
// firebase.auth().tenantId = 'tenant-id-1';
firebase.auth().createUserWithEmailAndPassword('johndoe@example.com', 'password')
  .then((result) => {
    result.user.getIdTokenResult()
  })
  .then((idTokenResult) => {
    console.log(idTokenResult.claim.admin);
  })
  .catch((error) => {
    if (error.code !== 'auth/internal-error' && error.message.indexOf('Cloud Function') !== -1) {
      // Display error.
    } else {
      // Registration succeeds.
    }
  });

Bir kullanıcıyı değiştirme

Bir kayıt veya oturum açma girişimini engellemek yerine, işlemin devam etmesine izin verebilirsiniz. Ancak, Firebase Authentication'ın veritabanına kaydedilen ve istemciye döndürülen User nesnesini değiştirin.

Bir kullanıcıyı değiştirmek için etkinlik işleyicinizden, değiştirilecek alanları içeren bir nesne döndürün. Aşağıdaki alanları değiştirebilirsiniz:

• displayName
• disabled
• emailVerified
• photoUrl
• customClaims
• sessionClaims (yalnızca beforeSignIn)

sessionClaims hariç olmak üzere, değiştirilen tüm alanlar Firebase Authentication'ın veritabanına kaydedilir. Yani bu alanlar yanıt jetonuna dahil edilir ve kullanıcı oturumları arasında devam eder.

Aşağıdaki örnekte, varsayılan görünen adın nasıl ayarlanacağı gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  return {
    // If no display name is provided, set it to "Guest".
    displayName: user.displayName || 'Guest';
  };
});

Hem beforeCreate hem de beforeSignIn için bir etkinlik işleyici kaydederseniz beforeSignIn kodunun beforeCreate sonrasında yürütüleceğini unutmayın. beforeCreate aracında güncellenen kullanıcı alanları beforeSignIn üzerinde görünür. Her iki etkinlik işleyicide de sessionClaims dışında bir alan ayarlarsanız beforeSignIn içinde ayarlanan değer, beforeCreate öğesinde ayarlanan değerin üzerine yazar. Yalnızca sessionClaims için mevcut oturumun jeton taleplerine çoğaltılırlar ancak veritabanında saklanmaz veya depolanmaz.

Örneğin, herhangi bir sessionClaims ayarlanırsa beforeSignIn bunları tüm beforeCreate hak talepleriyle birlikte döndürür ve birleştirilir. İkisi de birleştirildiğinde, bir sessionClaims anahtarı customClaims içindeki bir anahtarla eşleşirse jeton taleplerinde sessionClaims anahtarı, eşleşen customClaims değerinin üzerine yazılır. Ancak gereksiz customClaims anahtarı, gelecekteki istekler için veritabanında saklanmaya devam eder.

Desteklenen OAuth kimlik bilgileri ve verileri

OAuth kimlik bilgilerini ve verilerini, çeşitli kimlik sağlayıcılardan engelleme işlevlerine aktarabilirsiniz. Aşağıdaki tabloda her kimlik sağlayıcı için hangi kimlik bilgileri ve verilerin desteklendiği gösterilmektedir:

Jetonları yenile

Engelleme işlevinde yenileme jetonu kullanmak için önce Firebase konsolunun Engelleme işlevleri sayfasındaki onay kutusunu seçmeniz gerekir.

Herhangi bir kimlik sağlayıcı, doğrudan bir OAuth kimlik bilgisi (ör. kimlik jetonu veya erişim jetonu) ile oturum açarken kimlik sağlayıcılar tarafından yenileme jetonları döndürülmez. Bu durumda, istemci taraflı OAuth kimlik bilgileri engelleme işlevine de iletilir.

Aşağıdaki bölümlerde her bir kimlik sağlayıcı türü ve desteklenen kimlik bilgileri ile verileri açıklanmaktadır.

Genel OIDC sağlayıcıları

Kullanıcı, genel bir OIDC sağlayıcısıyla oturum açtığında aşağıdaki kimlik bilgileri iletilir:

• Kimlik jetonu: id_token akışı seçilirse sağlanır.
• Erişim jetonu: Kod akışı seçiliyse sağlanır. Kod akışının şu anda yalnızca REST API aracılığıyla desteklendiğini unutmayın.
• Yenileme jetonu: offline_access kapsamı seçiliyse sağlanır.

Örnek:

const provider = new firebase.auth.OAuthProvider('oidc.my-provider');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);

Google

Bir kullanıcı Google ile oturum açtığında aşağıdaki kimlik bilgileri aktarılır:

• Kimlik jetonu
• Erişim jetonu
• Yenileme jetonu: Yalnızca aşağıdaki özel parametreler isteniyorsa sağlanır:
  • access_type=offline
  • prompt=consent, kullanıcı daha önce izin verdiyse ve yeni kapsam istenmediyse

Örnek:

const provider = new firebase.auth.GoogleAuthProvider();
provider.setCustomParameters({
  'access_type': 'offline',
  'prompt': 'consent'
});
firebase.auth().signInWithPopup(provider);

Google yenileme jetonları hakkında daha fazla bilgi edinin.

Facebook

Bir kullanıcı Facebook ile oturum açtığında, aşağıdaki kimlik bilgisi aktarılır:

• Erişim jetonu: Başka bir erişim jetonuyla değiştirilebilecek bir erişim jetonu döndürülür. Facebook tarafından desteklenen farklı erişim jetonu türleri ve bunları uzun ömürlü jetonlar ile nasıl değiştirebileceğiniz hakkında daha fazla bilgi edinin.

GitHub

Bir kullanıcı GitHub ile oturum açtığında aşağıdaki kimlik bilgisi aktarılır:

• Erişim jetonu: İptal edilmediği sürece süresi dolmaz.

Microsoft

Bir kullanıcı Microsoft ile oturum açtığında aşağıdaki kimlik bilgileri aktarılır:

• Kimlik jetonu
• Erişim jetonu
• Yenileme jetonu: offline_access kapsamı seçilirse engelleme işlevine iletilir.

Örnek:

const provider = new firebase.auth.OAuthProvider('microsoft.com');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);

Yahoo

Bir kullanıcı Yahoo ile oturum açtığında aşağıdaki kimlik bilgileri, özel parametreler veya kapsamlar olmadan aktarılır:

• Kimlik jetonu
• Erişim jetonu
• Yenileme jetonu

LinkedIn

Bir kullanıcı LinkedIn ile oturum açtığında aşağıdaki kimlik bilgileri aktarılır:

• Erişim jetonu

Apple

Bir kullanıcı Apple ile oturum açtığında aşağıdaki kimlik bilgileri, özel parametre veya kapsam olmadan aktarılır:

• Kimlik jetonu
• Erişim jetonu
• Yenileme jetonu

Sık karşılaşılan senaryolar

Aşağıdaki örneklerde, işlevlerin engellenmesine ilişkin bazı yaygın kullanım alanları gösterilmektedir:

Yalnızca belirli bir alandan kayıt yapılmasına izin verme

Aşağıdaki örnekte, example.com alanının parçası olmayan kullanıcıların uygulamanıza kaydolmasını nasıl engelleyeceğiniz gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (!user.email || user.email.indexOf('@example.com') === -1) {
    throw new functions.auth.HttpsError(
      'invalid-argument', `Unauthorized email "${user.email}"`);
  }
});

Doğrulanmamış e-postalara sahip kullanıcıların kaydolmasını engelleme

Aşağıdaki örnekte, doğrulanmamış e-postalara sahip kullanıcıların uygulamanıza kaydolmasını nasıl engelleyeceğiniz gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.email && !user.emailVerified) {
    throw new functions.auth.HttpsError(
      'invalid-argument', `Unverified email "${user.email}"`);
  }
});

Kayıtta e-posta doğrulaması isteme

Aşağıdaki örnekte, bir kullanıcının kaydolduktan sonra e-posta adresini doğrulamasının nasıl zorunlu tutulacağı gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  const locale = context.locale;
  if (user.email && !user.emailVerified) {
    // Send custom email verification on sign-up.
    return admin.auth().generateEmailVerificationLink(user.email).then((link) => {
      return sendCustomVerificationEmail(user.email, link, locale);
    });
  }
});

exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
 if (user.email && !user.emailVerified) {
   throw new functions.auth.HttpsError(
     'invalid-argument', `"${user.email}" needs to be verified before access is granted.`);
  }
});

Belirli kimlik sağlayıcı e-postalarının doğrulanmış olarak değerlendirilmesi

Aşağıdaki örnekte, belirli kimlik sağlayıcılardan gelen kullanıcı e-postalarının nasıl doğrulanmış olarak ele alınacağı gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.email && !user.emailVerified && context.eventType.indexOf(':facebook.com') !== -1) {
    return {
      emailVerified: true,
    };
  }
});

Belirli IP adreslerinden oturum açmayı engelleme

Belirli IP adresi aralıklarından oturum açmayı engellemeyle ilgili örnek aşağıdaki örnekte:

exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
  if (isSuspiciousIpAddress(context.ipAddress)) {
    throw new functions.auth.HttpsError(
      'permission-denied', 'Unauthorized access!');
  }
});

Özel ve oturum hak taleplerini ayarlama

Aşağıdaki örnekte, özel ve oturum hak taleplerinin nasıl ayarlanacağı gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (context.credential &&
      context.credential.providerId === 'saml.my-provider-id') {
    return {
      // Employee ID does not change so save in persistent claims (stored in
      // Auth DB).
      customClaims: {
        eid: context.credential.claims.employeeid,
      },
      // Copy role and groups to token claims. These will not be persisted.
      sessionClaims: {
        role: context.credential.claims.role,
        groups: context.credential.claims.groups,
      }
    }
  }
});

Şüpheli etkinliği izlemek için IP adreslerini izleme

Kullanıcının oturum açtığı IP adresini izleyip sonraki isteklerde IP adresiyle karşılaştırarak jeton hırsızlığını önleyebilirsiniz. İstek şüpheli görünüyorsa (örneğin, IP'ler farklı coğrafi bölgelerdense) kullanıcıdan tekrar oturum açmasını isteyebilirsiniz.

1. Kullanıcının oturum açarken kullandığı IP adresini izlemek için oturum hak taleplerini kullanın:

   Node.js

   exports.beforeSignIn = functions.auth.user().beforeSignIn((user, context) => {
     return {
       sessionClaims: {
         signInIpAddress: context.ipAddress,
       },
     };
   });
   

2. Bir kullanıcı Firebase Authentication ile kimlik doğrulama gerektiren kaynaklara erişmeye çalıştığında istekteki IP adresini oturum açmak için kullanılan IP ile karşılaştırın:

   Node.js

   app.post('/getRestrictedData', (req, res) => {
     // Get the ID token passed.
     const idToken = req.body.idToken;
     // Verify the ID token, check if revoked and decode its payload.
     admin.auth().verifyIdToken(idToken, true).then((claims) => {
       // Get request IP address
       const requestIpAddress = req.connection.remoteAddress;
       // Get sign-in IP address.
       const signInIpAddress = claims.signInIpAddress;
       // Check if the request IP address origin is suspicious relative to
       // the session IP addresses. The current request timestamp and the
       // auth_time of the ID token can provide additional signals of abuse,
       // especially if the IP address suddenly changed. If there was a sudden
       // geographical change in a short period of time, then it will give
       // stronger signals of possible abuse.
       if (!isSuspiciousIpAddressChange(signInIpAddress, requestIpAddress)) {
         // Suspicious IP address change. Require re-authentication.
         // You can also revoke all user sessions by calling:
         // admin.auth().revokeRefreshTokens(claims.sub).
         res.status(401).send({error: 'Unauthorized access. Please login again!'});
       } else {
         // Access is valid. Try to return data.
         getData(claims).then(data => {
           res.end(JSON.stringify(data);
         }, error => {
           res.status(500).send({ error: 'Server error!' })
         });
       }
     });
   });
   

Kullanıcı fotoğrafları filtreleniyor

Aşağıdaki örnekte kullanıcıların profil fotoğraflarının nasıl arındırılacağı gösterilmektedir:

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (user.photoURL) {
    return isPhotoAppropriate(user.photoURL)
      .then((status) => {
        if (!status) {
          // Sanitize inappropriate photos by replacing them with guest photos.
          // Users could also be blocked from sign-up, disabled, etc.
          return {
            photoUrl: PLACEHOLDER_GUEST_PHOTO_URL,
          };
        }
      });
});

Görüntüleri algılama ve temizleme hakkında daha fazla bilgi edinmek için Cloud Vision belgelerini inceleyin.

Kullanıcının kimlik sağlayıcı OAuth kimlik bilgilerine erişme

Aşağıdaki örnekte, Google ile oturum açmış bir kullanıcı için yenileme jetonunun nasıl alınacağı ve Google Takvim API'lerini çağırmak için nasıl kullanılacağı gösterilmektedir. Yenileme jetonu çevrimdışı erişim için depolanır.

const {OAuth2Client} = require('google-auth-library');
const {google} = require('googleapis');
// ...
// Initialize Google OAuth client.
const keys = require('./oauth2.keys.json');
const oAuth2Client = new OAuth2Client(
  keys.web.client_id,
  keys.web.client_secret
);

exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
  if (context.credential &&
      context.credential.providerId === 'google.com') {
    // Store the refresh token for later offline use.
    // These will only be returned if refresh tokens credentials are included
    // (enabled by Cloud console).
    return saveUserRefreshToken(
        user.uid,
        context.credential.refreshToken,
        'google.com'
      )
      .then(() => {
        // Blocking the function is not required. The function can resolve while
        // this operation continues to run in the background.
        return new Promise((resolve, reject) => {
          // For this operation to succeed, the appropriate OAuth scope should be requested
          // on sign in with Google, client-side. In this case:
          // https://www.googleapis.com/auth/calendar
          // You can check granted_scopes from within:
          // context.additionalUserInfo.profile.granted_scopes (space joined list of scopes).

          // Set access token/refresh token.
          oAuth2Client.setCredentials({
            access_token: context.credential.accessToken,
            refresh_token: context.credential.refreshToken,
          });
          const calendar = google.calendar('v3');
          // Setup Onboarding event on user's calendar.
          const event = {/** ... */};
          calendar.events.insert({
            auth: oauth2client,
            calendarId: 'primary',
            resource: event,
          }, (err, event) => {
            // Do not fail. This is a best effort approach.
            resolve();
          });
      });
    })
  }
});

Kullanıcı işlemi için reCAPTCHA Enterprise kararını geçersiz kıl

Aşağıdaki örnekte, desteklenen kullanıcı akışları için reCAPTCHA Enterprise kararının nasıl geçersiz kılınacağı gösterilmektedir.

reCAPTCHA Enterprise'ı Firebase Authentication ile entegre etme hakkında daha fazla bilgi için reCAPTCHA Enterprise'ı etkinleştirme bölümüne bakın.

Engelleme işlevleri, özel faktörlere göre akışlara izin vermek veya akışları engellemek için kullanılabilir. Böylece, reCAPTCHA Enterprise tarafından sağlanan sonuç geçersiz kılınır.

 const {
   auth,
 } = require("firebase-functions/v1");

exports.checkrecaptchaV1 = auth.user().beforeSignIn((userRecord, context) => {
 // Allow users with a specific email domain to sign in regardless of their recaptcha score.
 if (userRecord.email && userRecord.email.indexOf('@acme.com') === -1) {
   return {
     recaptchaActionOverride: 'ALLOW',
   };
 }

 // Allow users to sign in with recaptcha score greater than 0.5
 if (context.additionalUserInfo.recaptchaScore > 0.5) {
   return {
     recaptchaActionOverride: 'ALLOW',
   };
 }

 // Block all others.
 return {
   recaptchaActionOverride: 'BLOCK',
 };
});