Триггеры блокировки аутентификации

2-го поколения 1-го поколения

Блокирующие функции позволяют выполнять пользовательский код, который изменяет результат регистрации или входа пользователя в ваше приложение. Например, вы можете запретить аутентификацию пользователя, если он не соответствует определённым критериям, или обновить информацию о пользователе перед её возвратом в клиентское приложение.

Примечание: функции блокировки доступны только для использования с Firebase и Firebase CLI. Они не поддерживаются Google Cloud Identity Platform.

Прежде чем начать

Чтобы использовать функции блокировки, необходимо обновить проект Firebase до Firebase Authentication with Identity Platform . Если вы ещё не сделали этого, сделайте это.

Понимание блокирующих функций

Вы можете зарегистрировать функции блокировки для следующих событий:

• beforeCreate : срабатывает перед сохранением нового пользователя в базе данных Firebase Authentication и перед возвратом токена в клиентское приложение.

• beforeSignIn : срабатывает после проверки учётных данных пользователя, но до того, как Firebase Authentication вернёт токен ID вашему клиентскому приложению. Если ваше приложение использует многофакторную аутентификацию, функция срабатывает после того, как пользователь пройдёт проверку второго фактора. Обратите внимание, что создание нового пользователя также срабатывает beforeSignIn , помимо beforeCreate .

• beforeEmail (только Node.js) : срабатывает перед отправкой электронного письма (например,
  пользователю отправляется электронное письмо для входа в систему или сброса пароля.

• beforeSms (только Node.js) : срабатывает перед отправкой SMS-сообщения пользователю, например, при многофакторной аутентификации.

При использовании функций блокировки помните следующее:

• Функция должна ответить в течение 7 секунд. По истечении 7 секунд Firebase Authentication возвращает ошибку, и клиентская операция завершается неудачей.

• Клиентским приложениям передаются коды HTTP-ответов, отличные от 200 Убедитесь, что клиентский код обрабатывает все ошибки, которые может возвращать ваша функция.

• Функции применяются ко всем пользователям вашего проекта, включая пользователей, содержащихся в клиенте . Firebase Authentication предоставляет вашей функции информацию о пользователях, включая всех клиентов, к которым они принадлежат, что позволяет вам реагировать соответствующим образом.

• Привязка другого поставщика удостоверений к учетной записи повторно активирует все зарегистрированные функции beforeSignIn .

• Анонимная и пользовательская аутентификация не запускают функции блокировки.

Внимание: при удалении функции необходимо также отменить регистрацию триггеров в Firebase Authentication . В противном случае все пользователи не смогут пройти аутентификацию в вашем приложении.

Развернуть функцию блокировки

Чтобы вставить свой код в процессы аутентификации пользователей, разверните блокирующие функции. После развёртывания блокирующих функций ваш код должен быть успешно выполнен для успешной аутентификации и создания пользователя.

Блокирующая функция разворачивается так же, как и любая другая функция (подробнее см. на странице « Начало работы Cloud Functions ). Вкратце:

1. Напишите функцию, которая обрабатывает целевое событие.

   Например, для начала вы можете добавить в index.js пустую функцию следующего вида:

   const functions = require('firebase-functions/v1');
   
   exports.beforeCreate = functions.auth.user().beforeCreate((user, context) => {
     // TODO
   });
   
   The above example has omitted the implementation of custom auth logic. See
   the following sections to learn how to implement your blocking functions and
   [Common scenarios](#common-scenarios) for specific examples.
   

1. Разверните свои функции с помощью Firebase CLI:

   firebase deploy --only functions
   

   Вам придется заново развертывать свои функции каждый раз при их обновлении.

Получение информации о пользователе и контексте

События beforeSignIn и beforeCreate предоставляют объекты User и EventContext , содержащие информацию о входе пользователя в систему. Используйте эти значения в своем коде, чтобы определить, следует ли разрешить выполнение операции.

Список свойств, доступных для объекта User , см. в справочнике API UserRecord .

Объект EventContext содержит следующие свойства:

Имя	Описание	Пример
locale	Локаль приложения. Вы можете установить локаль с помощью клиентского SDK или передав заголовок локали в REST API.	fr или sv-SE
ipAddress	IP-адрес устройства, на котором конечный пользователь регистрируется или с которого входит в систему.	114.14.200.1
userAgent	Пользовательский агент, запускающий функцию блокировки.	Mozilla/5.0 (X11; Linux x86_64)
eventId	Уникальный идентификатор события.	rWsyPtolplG2TBFoOkkgyg
eventType	Тип события. Здесь представлена информация о названии события, например, beforeSignIn или beforeCreate , а также о соответствующем использованном методе входа, например, Google или электронная почта/пароль.	providers/cloud.auth/eventTypes/user.beforeSignIn:password
authType	Всегда USER .	USER
resource	Проект или арендатор Firebase Authentication .	projects/ project-id /tenants/ tenant-id
timestamp	Время возникновения события, отформатированное как строка RFC 3339 .	Tue, 23 Jul 2019 21:10:57 GMT
additionalUserInfo	Объект, содержащий информацию о пользователе.	AdditionalUserInfo
credential	Объект, содержащий информацию об учетных данных пользователя.	AuthCredential

Блокировка регистрации или входа

Чтобы заблокировать попытку регистрации или входа, добавьте в функцию исключение HttpsError . Например:

Node.js

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

В следующей таблице перечислены ошибки, которые вы можете вызвать, а также сообщения об ошибках по умолчанию:

Имя	Код	Сообщение
invalid-argument	400	Клиент указал недопустимый аргумент.
failed-precondition	400	Запрос не может быть выполнен в текущем состоянии системы.
out-of-range	400	Клиент указал неверный диапазон.
unauthenticated	401	Отсутствует, недействителен или просрочен токен OAuth.
permission-denied	403	У клиента нет достаточных разрешений.
not-found	404	Указанный ресурс не найден.
aborted	409	Конфликт параллелизма, например конфликт чтения-изменения-записи.
already-exists	409	Ресурс, который клиент пытался создать, уже существует.
resource-exhausted	429	Либо исчерпана квота ресурсов, либо достигнут предел скорости.
cancelled	499	Запрос отменен клиентом.
data-loss	500	Невосстановимая потеря данных или повреждение данных.
unknown	500	Неизвестная ошибка сервера.
internal	500	Внутренняя ошибка сервера.
not-implemented	501	Метод API не реализован сервером.
unavailable	503	Сервис недоступен.
deadline-exceeded	504	Срок подачи запроса истек.

Вы также можете указать собственное сообщение об ошибке:

Node.js

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

В следующем примере показано, как заблокировать регистрацию в вашем приложении пользователей, не относящихся к определенному домену:

Node.js

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}"`);
  }
});

Независимо от того, используете ли вы сообщение по умолчанию или пользовательское, Cloud Functions оборачивает ошибку и возвращает её клиенту как внутреннюю ошибку. Например:

throw new functions.auth.HttpsError('invalid-argument', `Unauthorized email [e-mail]}`);

Ваше приложение должно обнаружить ошибку и обработать её соответствующим образом. Например:

JavaScript

// Blocking functions can also be triggered in a multi-tenant context before user creation.
// firebase.auth().tenantId = 'tenant-id-1';
firebase.auth().createUserWithEmailAndPassword('[e-mail]', '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.
    }
  });

Изменение пользователя

Вместо того чтобы блокировать попытку регистрации или входа, вы можете разрешить продолжение операции, но изменить объект User , который сохраняется в базе данных Firebase Authentication и возвращается клиенту.

Чтобы изменить пользователя, верните объект из обработчика событий, содержащий поля для изменения. Вы можете изменить следующие поля:

• displayName
• disabled
• emailVerified
• photoUrl
• customClaims
• sessionClaims (только beforeSignIn )

За исключением sessionClaims , все измененные поля сохраняются в базе данных Firebase Authentication , что означает, что они включаются в токен ответа и сохраняются между сеансами пользователя.

В следующем примере показано, как установить отображаемое имя по умолчанию:

Node.js

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

Если вы регистрируете обработчик событий для beforeCreate и beforeSignIn , обратите внимание, что beforeSignIn выполняется после beforeCreate . Пользовательские поля, обновлённые в beforeCreate , видны в beforeSignIn . Если в обоих обработчиках событий задано поле, отличное от sessionClaims , значение, заданное в beforeSignIn перезапишет значение, заданное в beforeCreate . Только для sessionClaims : они распространяются на заявки токена текущего сеанса, но не сохраняются и не сохраняются в базе данных.

Например, если установлены какие-либо sessionClaims , beforeSignIn вернет их вместе со всеми утверждениями beforeCreate , и они будут объединены. При объединении, если ключ sessionClaims совпадает с ключом в customClaims , соответствующие customClaims будут перезаписаны в утверждениях токена ключом sessionClaims . Однако перезаписанный ключ customClaims по-прежнему будет сохранен в базе данных для будущих запросов.

Поддерживаемые учетные данные и данные OAuth

Вы можете передавать учётные данные и данные OAuth функциям блокировки от различных поставщиков удостоверений. В следующей таблице показаны учётные данные и данные, поддерживаемые каждым поставщиком удостоверений:

Поставщик удостоверений	Идентификационный токен	Токен доступа	Время истечения срока действия	Секрет токена	Обновить токен	Заявки на вход
Google	Да	Да	Да	Нет	Да	Нет
Фейсбук	Нет	Да	Да	Нет	Нет	Нет
Твиттер	Нет	Да	Нет	Да	Нет	Нет
GitHub	Нет	Да	Нет	Нет	Нет	Нет
Майкрософт	Да	Да	Да	Нет	Да	Нет
LinkedIn	Нет	Да	Да	Нет	Нет	Нет
Яху	Да	Да	Да	Нет	Да	Нет
Яблоко	Да	Да	Да	Нет	Да	Нет
САМЛ	Нет	Нет	Нет	Нет	Нет	Да
ОИДК	Да	Да	Да	Нет	Да	Да

Обновление токенов

Чтобы использовать токен обновления в функции блокировки, необходимо сначала установить флажок на странице «Функции блокировки» консоли Firebase .

Токены обновления не будут возвращаться поставщиками удостоверений при входе напрямую с использованием учётных данных OAuth, таких как токен ID или токен доступа. В этом случае те же учётные данные OAuth на стороне клиента будут переданы в функцию блокировки.

В следующих разделах описываются все типы поставщиков удостоверений, а также поддерживаемые ими учетные данные и учетные данные.

Поставщики OIDC общего назначения

При входе пользователя в систему через универсального поставщика OIDC будут переданы следующие учетные данные:

• Идентификатор токена : предоставляется, если выбран поток id_token .
• Токен доступа : предоставляется при выборе потока кода. Обратите внимание, что поток кода в настоящее время поддерживается только через REST API.
• Токен обновления : предоставляется, если выбрана область offline_access .

Пример:

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

Google

Когда пользователь входит в систему через Google, будут переданы следующие учетные данные:

• Идентификационный токен
• Токен доступа
• Токен обновления : предоставляется только в том случае, если запрашиваются следующие пользовательские параметры:
  • access_type=offline
  • prompt=consent , если пользователь ранее дал согласие и не было запрошено новой области действия

Пример:

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

Узнайте больше о токенах обновления Google .

Фейсбук

Когда пользователь входит в систему через Facebook, будут переданы следующие учетные данные:

• Токен доступа : возвращается токен доступа, который можно обменять на другой токен доступа. Узнайте больше о различных типах токенов доступа , поддерживаемых Facebook, и о том, как обменять их на долгосрочные токены .

GitHub

Когда пользователь входит в систему GitHub, будут переданы следующие учетные данные:

• Токен доступа : не имеет срока действия, если не будет отозван.

Майкрософт

При входе пользователя в систему Microsoft будут переданы следующие учетные данные:

• Идентификационный токен
• Токен доступа
• Токен обновления : передается в функцию блокировки, если выбрана область offline_access .

Пример:

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

Яху

Когда пользователь входит в систему Yahoo, следующие учетные данные будут переданы без каких-либо пользовательских параметров или областей:

• Идентификационный токен
• Токен доступа
• Обновить токен

LinkedIn

Когда пользователь входит в систему LinkedIn, будут переданы следующие учетные данные:

• Токен доступа

Яблоко

Когда пользователь входит в систему с помощью Apple, следующие учетные данные будут переданы без каких-либо специальных параметров или областей:

• Идентификационный токен
• Токен доступа
• Обновить токен

Распространенные сценарии

В следующих примерах показаны некоторые распространенные варианты использования блокирующих функций:

Разрешить регистрацию только с определенного домена

В следующем примере показано, как запретить пользователям, не являющимся частью домена example.com , регистрироваться в вашем приложении:

Node.js

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}"`);
  }
});

Блокировка регистрации пользователей с неподтвержденными адресами электронной почты

В следующем примере показано, как запретить пользователям с неподтвержденными адресами электронной почты регистрироваться в вашем приложении:

Node.js

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

Требование подтверждения адреса электронной почты при регистрации

В следующем примере показано, как потребовать от пользователя подтверждения адреса электронной почты после регистрации:

Node.js

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.`);
  }
});

Обработка определенных адресов электронной почты поставщиков удостоверений как проверенных

В следующем примере показано, как обрабатывать электронные письма пользователей от определенных поставщиков удостоверений как проверенные:

Node.js

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

Блокировка входа с определенных IP-адресов

Следующий пример блокирует вход с определенных диапазонов IP-адресов:

Node.js

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

Настройка пользовательских и сеансовых заявок

В следующем примере показано, как устанавливать пользовательские и сеансовые утверждения:

Node.js

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,
      }
    }
  }
});

Отслеживание IP-адресов для мониторинга подозрительной активности

Вы можете предотвратить кражу токенов, отслеживая IP-адрес, с которого пользователь входит в систему, и сравнивая его с IP-адресами при последующих запросах. Если запрос кажется подозрительным (например, IP-адреса принадлежат разным географическим регионам), вы можете попросить пользователя войти повторно.

1. Используйте утверждения сеанса для отслеживания IP-адреса, с которого пользователь входит в систему:

   Node.js

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

2. Когда пользователь пытается получить доступ к ресурсам, требующим аутентификации с помощью Firebase Authentication , сравните IP-адрес в запросе с IP-адресом, использованным для входа:

   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!' })
         });
       }
     });
   });
   

Проверка фотографий пользователей

В следующем примере показано, как очистить фотографии профилей пользователей:

Node.js

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,
          };
        }
      });
});

Дополнительную информацию о том, как обнаруживать и очищать изображения, см. в документации Cloud Vision .

Доступ к учетным данным OAuth поставщика удостоверений пользователя

В следующем примере показано, как получить токен обновления для пользователя, вошедшего в учётную запись Google, и использовать его для вызова API Google Календаря. Токен обновления сохраняется для доступа в автономном режиме.

Node.js

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();
          });
      });
    })
  }
});

Переопределение вердикта reCAPTCHA Enterprise для пользовательской операции

В следующем примере показано, как переопределить вердикт reCAPTCHA Enterprise для поддерживаемых пользовательских потоков.

Дополнительную информацию об интеграции reCAPTCHA Enterprise с аутентификацией Firebase см. в разделе Включение reCAPTCHA Enterprise.

Функции блокировки можно использовать для разрешения или блокировки потоков на основе пользовательских факторов, тем самым переопределяя результат, предоставленный reCAPTCHA Enterprise.

Node.js

const functions = require("firebase-functions/v1");
exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
 if (
   context.smsType === "SIGN_IN_OR_SIGN_UP" &&
   context.additionalUserInfo.phoneNumber.includes('+91')
 ) {
   return {
     recaptchaActionOverride: "ALLOW",
   };
 }

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

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