Внедрение решения для идентификации с помощью FedCM на стороне проверяющей стороны.

Доверяющим сторонам (RP) необходимо выполнить следующие шаги, чтобы включить FedCM на своем сайте:

• Убедитесь, что конечные точки FedCM разрешены на сайте RP.
• Используйте API JavaScript FedCM для инициации аутентификации пользователя.
• Предоставьте свои метаданные (например, URL-адреса политики конфиденциальности и условий обслуживания) поставщику удостоверений.
• [необязательно] Настройте взаимодействие с пользователем, выбрав режим пользовательского интерфейса , предоставив подсказки для входа или домена , передав специальные параметры , запросив конкретную информацию о пользователе , предоставив собственное сообщение об ошибке или выбрав способ повторной аутентификации пользователей .

Как только конфигурация и конечные точки IdP станут доступны, RP могут вызвать navigator.credentials.get() , чтобы запросить разрешение пользователям войти в RP с помощью IdP.

Перед вызовом API необходимо подтвердить, что FedCM доступен в браузере пользователя . Чтобы проверить, доступен ли FedCM, оберните этот код вокруг вашей реализации FedCM:

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Чтобы разрешить пользователям входить в IdP на RP с помощью FedCM, RP может вызвать navigator.credentials.get() , например:

  const credential = await navigator.credentials.get({
    identity: {
      context: 'signin',
      providers: [{
        configURL: 'https://accounts.idp.example/config.json',
        clientId: '********',
        mode: 'active',
        params: {
          nonce: '******'
        }
      }]
    }
  });
  const { token } = credential;

Свойство контекста

С помощью дополнительного свойства context RP может изменить строку в диалоговом пользовательском интерфейсе FedCM (например, «Войти в rp.example…», «Использовать idp.example…»), например, для соответствия предопределенным контекстам аутентификации. Свойство context может иметь следующие значения:

• signin (по умолчанию)
• signup
• use

Например, установка context для use приведет к следующему сообщению:

Браузер обрабатывает варианты использования регистрации и входа по-разному в зависимости от наличия approved_clients в ответе от конечной точки списка учетных записей . Браузер не будет отображать текст раскрытия «Продолжить...», если пользователь уже зарегистрировался в RP.
Свойство providers принимает массив объектов IdentityProvider , которые имеют следующие свойства:

Собственность поставщиков

Свойство providers принимает массив объектов IdentityProvider , которые имеют следующие свойства:

Активный режим

FedCM поддерживает различные конфигурации режима UX . Пассивный режим — это режим по умолчанию, и разработчикам не нужно его настраивать.

Чтобы использовать FedCM в активном режиме:

1. Проверьте доступность функции в браузере пользователя.
2. Вызовите API с помощью временного жеста пользователя, например нажатия кнопки.
3. Передайте параметр mode в вызов API:

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

Пользовательский значок в активном режиме

Активный режим позволяет поставщикам удостоверений включать значок официального логотипа RP непосредственно в ответ конечной точки метаданных клиента . RP должен заранее предоставить данные о своем брендинге.

Вызов FedCM из iframe с перекрестным происхождением

FedCM можно вызвать из iframe с несколькими источниками, используя политику разрешений identity-credentials-get , если родительский фрейм это позволяет. Для этого добавьте allow="identity-credentials-get" к тегу iframe следующим образом:

  <iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

Вы можете увидеть это в действии на примере .

При необходимости, если родительский фрейм хочет ограничить источники для вызова FedCM, отправьте заголовок Permissions-Policy со списком разрешенных источников.

  Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

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

API подсказок для входа в систему

Используя подсказку для входа в систему, RP может порекомендовать, под какой учетной записью пользователю следует войти в систему. Это может быть полезно для повторной аутентификации пользователей, которые не уверены, какую учетную запись они использовали раньше.

RP могут выборочно отображать конкретную учетную запись, вызывая navigator.credentials.get() со свойством loginHint с одним из значений login_hints полученным из конечной точки списка учетных записей , как показано в следующем примере кода:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

Если ни одна учетная запись не соответствует loginHint , в диалоговом окне FedCM отображается приглашение для входа в систему, которое позволяет пользователю войти в учетную запись IdP, соответствующую подсказке, запрошенной RP. Когда пользователь нажимает на приглашение, открывается всплывающее окно с URL-адресом входа, указанным в файле конфигурации . Затем к ссылке добавляется подсказка для входа в систему и параметры запроса подсказки домена.

API подсказки домена

RP могут выборочно отображать только учетные записи, связанные с определенным доменом. Это может быть полезно для RP, которые ограничены корпоративным доменом.

Чтобы отобразить только определенные учетные записи домена, RP должен вызвать navigator.credentials.get() со свойством domainHint с одним из значений domain_hints полученным из конечной точки списка учетных записей , как показано в следующем примере кода:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

Если ни одна учетная запись не соответствует domainHint , в диалоговом окне FedCM отображается приглашение для входа в систему, которое позволяет пользователю войти в учетную запись IdP, соответствующую подсказке, запрошенной RP. Когда пользователь нажимает на приглашение, открывается всплывающее окно с URL-адресом входа, указанным в файле конфигурации . Затем к ссылке добавляется подсказка для входа в систему и параметры запроса подсказки домена.

Пользовательские параметры

Функция «Пользовательские параметры» позволяет RP предоставлять дополнительные параметры «ключ-значение» конечной точке утверждения идентификатора . С помощью API параметров RP могут передавать IdP дополнительные параметры для запроса разрешений на доступ к ресурсам помимо базового входа. Передача дополнительных параметров может быть полезна в следующих сценариях:

• RP необходимо динамически запрашивать дополнительные разрешения, которые есть у IdP, такие как адрес выставления счета или доступ к календарю. Пользователь может авторизовать эти разрешения через поток пользовательского интерфейса, контролируемый IdP, который запускается с помощью функции «Продолжить дальше» , и затем IdP поделится этой информацией.

Чтобы использовать API, RP добавляет параметры к свойству params как объект при вызове navigator.credentials.get() :

  let {token} = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
        // Key/value pairs that need to be passed from the
        // RP to the IdP but that don't really play any role with
        // the browser.
        params: {
          IDP_SPECIFIC_PARAM: '1',
          foo: 'BAR'
        }
      },
    }
  });

Браузер автоматически преобразует это в POST-запрос к IdP с параметрами в виде одного сериализованного объекта JSON в кодировке URL:

  // The assertion endpoint is drawn from the config file
  POST /fedcm_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

Если RP требуются какие-либо дополнительные разрешения, IdP может предоставить ссылку для перенаправления. Например, в node.js:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

Поля

RP может указать информацию о пользователе (любую комбинацию имени, адреса электронной почты и изображения профиля), которой поставщик удостоверений должен поделиться с ним. Запрошенная информация будет включена в пользовательский интерфейс раскрытия диалогового окна FedCM. Пользователь увидит сообщение, уведомляющее его о том, что idp.example поделится запрошенной информацией с rp.example , если пользователь решит войти в систему.

Чтобы использовать функцию полей, RP должен добавить массив fields в вызов navigator.credentials.get() . Поля могут содержать любые варианты name , email и picture . В будущем это можно расширить, включив в него больше значений. Запрос с fields будет выглядеть так:

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only user email and profile picture
        fields: [ 'email', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',

      },
    }
  });

Браузер автоматически преобразует его в HTTP-запрос к конечной точке утверждения идентификатора , который включает параметр fields , указанный RP, с полями, которые браузер раскрывает пользователю в параметре disclosure_shown_for . В целях обратной совместимости браузер также отправит disclosure_text_shown=true если текст раскрытия был показан и запрошенные поля включают все три поля : 'name' , 'email' и 'picture' .

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

Если fields представляют собой пустой массив, пользовательский агент пропустит пользовательский интерфейс раскрытия.

Это так, даже если ответ от конечной точки учетных записей не содержит идентификатор клиента, соответствующий RP в approved_clients .

В этом случае disclosure_text_shown отправленное в конечную точку утверждения идентификатора, является ложным в теле HTTP:

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false

Показать сообщение об ошибке

Иногда поставщик удостоверений не может выдать токен по законным причинам, например, когда клиент не авторизован или сервер временно недоступен. Если IdP возвращает ответ «ошибка», RP может его перехватить, а Chrome может уведомить пользователя, показывая пользовательский интерфейс браузера с информацией об ошибке, предоставленной IdP.

  try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    const code = e.code;
    const url = e.url;
  }

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

Автоматическая повторная аутентификация FedCM («автоматическая повторная аутентификация» вкратце) может позволить пользователям автоматически проходить повторную аутентификацию, когда они возвращаются после первоначальной аутентификации с использованием FedCM. «Первоначальная аутентификация» здесь означает, что пользователь создает учетную запись или входит на веб-сайт RP, впервые нажав кнопку «Продолжить как...» в диалоговом окне входа FedCM в одном и том же экземпляре браузера.

Хотя явный пользовательский опыт имеет смысл до того, как пользователь создал федеративную учетную запись, чтобы предотвратить отслеживание (что является одной из основных целей FedCM), он становится излишне громоздким после того, как пользователь прошел через это один раз: после того, как пользователь предоставляет разрешение на разрешение связи между RP и IdP, нет никаких преимуществ конфиденциальности или безопасности для принудительного подтверждения другого явного пользователя для чего-то, что он уже ранее подтвердил.

При автоматической повторной аутентификации браузер меняет свое поведение в зависимости от параметра, который вы указываете для mediation при вызове navigator.credentials.get() .

  const cred = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/fedcm.json',
        clientId: '1234',
      }],
    },
    mediation: 'optional', // this is the default
  });

  // `isAutoSelected` is `true` if auto-reauthn was performed.
  const isAutoSelected = cred.isAutoSelected;

mediation — это свойство API управления учетными данными . Оно ведет себя так же, как и для PasswordCredential и FederatedCredential , а также частично поддерживается PublicKeyCredential . Свойство принимает следующие четыре значения:

• 'optional' (по умолчанию): если возможно, выполняется автоматическая повторная аутентификация, в противном случае требуется посредничество. Мы рекомендуем выбрать эту опцию на странице входа.
• 'required' : для продолжения всегда требуется посредничество, например нажатие кнопки «Продолжить» в пользовательском интерфейсе. Выберите этот вариант, если ожидается, что ваши пользователи будут явно предоставлять разрешение каждый раз, когда им необходимо пройти аутентификацию.
• 'silent' : если возможно, выполните автоматическую повторную аутентификацию, в противном случае — молчаливый сбой, не требуя посредничества. Мы рекомендуем выбирать этот параметр на страницах, отличных от специальной страницы входа, но на которых вы хотите, чтобы пользователи оставались в системе, например на странице товара на веб-сайте доставки или странице статьи на новостном веб-сайте.
• 'conditional' : используется для WebAuthn и на данный момент недоступен для FedCM.

При этом вызове автоматическая повторная аутентификация происходит при следующих условиях:

• FedCM доступен для использования. Например, пользователь не отключил FedCM ни глобально , ни для RP в настройках.
• Пользователь использовал только одну учетную запись с FedCM API для входа на веб-сайт в этом браузере.
• Пользователь входит в IdP с этой учетной записью.
• Автоматическая повторная аутентификация не произошла в течение последних 10 минут.
• RP не вызвал navigator.credentials.preventSilentAccess() после предыдущего входа в систему.

При выполнении этих условий попытка автоматической повторной аутентификации пользователя начинается сразу после вызова функции FedCM navigator.credentials.get() .

При mediation: optional автоматическая повторная аутентификация может быть недоступна по причинам, известным только браузеру; RP может проверить, выполняется ли автоматическая повторная аутентификация, проверив свойство isAutoSelected .

Это полезно для оценки производительности API и соответствующего улучшения UX. Кроме того, когда он недоступен, пользователю может быть предложено войти в систему с явным посредничеством пользователя, которое представляет собой поток с mediation: required .

Принудительное посредничество с помощью preventSilentAccess()

Автоматическая повторная аутентификация пользователей сразу после выхода из системы не обеспечит хорошего пользовательского опыта. Вот почему FedCM имеет 10-минутный период молчания после автоматической повторной аутентификации, чтобы предотвратить такое поведение. Это означает, что автоматическая повторная аутентификация происходит не чаще одного раза в 10 минут, если только пользователь не войдет в систему повторно в течение 10 минут. RP должна вызвать navigator.credentials.preventSilentAccess() , чтобы явно запросить браузер отключить автоматическую повторную аутентификацию, когда пользователь явно выходит из RP, например, нажав кнопку выхода.

  function signout() {
    navigator.credentials.preventSilentAccess();
    location.href = '/signout';
  }

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

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

• В настольном Chrome перейдите в chrome://password-manager/settings > Войти автоматически.
• В Android Chrome откройте «Настройки» > «Менеджер паролей» > нажмите на шестеренку в правом верхнем углу > «Автоматический вход».

Отключив переключатель, пользователь может полностью отказаться от автоматической повторной аутентификации. Этот параметр сохраняется и синхронизируется на всех устройствах, если пользователь вошел в учетную запись Google на экземпляре Chrome и включена синхронизация.

Отключите IdP от RP

Если пользователь ранее вошел в RP, используя IdP через FedCM, отношения запоминаются браузером локально в виде списка подключенных учетных записей. RP может инициировать отключение, вызвав функцию IdentityCredential.disconnect() . Эту функцию можно вызвать из кадра RP верхнего уровня. RP необходимо передать configURL , clientId , который он использует в рамках IdP, и accountHint для отключения IdP. Подсказка учетной записи может представлять собой произвольную строку, если конечная точка отключения может идентифицировать учетную запись, например адрес электронной почты или идентификатор пользователя, который не обязательно соответствует идентификатору учетной записи, предоставленному конечной точкой списка учетных записей:

  // Disconnect an IdP account 'account456' from the RP 'https://idp.com/'. This is invoked on the RP domain.
  IdentityCredential.disconnect({
    configURL: 'https://idp.com/config.json',
    clientId: 'rp123',
    accountHint: 'account456'
  });

IdentityCredential.disconnect() возвращает Promise . Это обещание может вызвать исключение по следующим причинам:

• Пользователь не вошел в систему RP, используя IdP через FedCM.
• API вызывается из iframe без политики разрешений FedCM.
• configURL недействителен или отсутствует конечная точка отключения.
• Проверка политики безопасности контента (CSP) не удалась.
• Имеется ожидающий запрос на отключение.
• Пользователь отключил FedCM в настройках браузера.

Когда конечная точка отключения IdP возвращает ответ , RP и IdP отключаются в браузере, и обещание разрешается. Идентификаторы отключенных учетных записей указаны в ответе от конечной точки отключения .

Next steps