Общие сведения

Провайдер аутентификации облачного сервиса Фреш позволяет войти в приложение пользователя из стороннего сервиса без использования дополнительной аутентификации и авторизации.

Этот способ аутентификации предназначен для организации "прозрачного" входа по технологии единого входа (Single Sign-On), когда пользователь уже работает в своем личном кабинете в стороннем (по отношению к сервису Фреш) сервисе.

Организация единого входа возможна 2-мя способами:

  1. Если сторонний сервис поддерживает технологию OAuth2 или OpenID-Connect,  то на стороне сервиса Фреш нужно выполнить настройки в соответствии с данными провайдера стороннего сервиса.
  2. Если сторонний сервис не поддерживает технологию OAuth2 или OpenID-Connect, то на стороне этого сервиса должна быть выполнена разработка для обеспечения поддержки прозрачной аутентификации.

Настройка сервиса Фреш для "прозрачного" входа из сервисов, поддерживающих OAuth2 и OpenID-Connect описана в главе "Использование сторонних провайдеров аутентификации" документа "1С:Облачная подсистема Фреш".

Схема работы с использованием OAuth2 или OpenId-Connect

Сервис Фреш поддерживает стандарт OpenID-Connect в части Authorization Code Flow – https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowSteps
В этой схеме Фреш является клиентом (приложением) к стороннему провайдеру.

Также поддерживаются некоторые отступления от стандарта, чтобы реализовать возможность авторизации через провайдеры, которые реализуют только OAuth2 и не используют стандарт OpenID-Connect целиком. Подробнее см. главу документации Продвинутые настройки взаимодействия с провайдером аутентификации.

Подключение приложения

Для подключения в стороннем провайдере необходимо установить идентификаторы приложения Фреш:

  • client_id – идентификатор приложения Фреш;
  • client_secret – защищенный ключ приложения Фреш;
  • redirect_uri – адрес приложения, куда будет переадресован пользователь после авторизации, в зависимости от сайта возможны разные адреса, например для 1cfresh.com будет адрес: https://1cfresh.com/a/openid/e1cib/oid2op/sso/callback

Точки взаимодействия

В сервисе Фреш настраиваются точки взаимодействия, которые используются в процессе авторизации и регистрации. Для примера используется провайдер https://login.1c.ru/oidc

Точка взаимодействияПример
Получение кода авторизацииhttps://login.1c.ru/oidc/authorize
Получение токенаhttps://login.1c.ru/oidc/accesstoken
Получение информации о пользователеhttps://login.1c.ru/oidc/profile

Получение ключа доступа

Ключ доступа необходим для работы Фреш со сторонним провайдером. Примеры далее будут использовать сервис-провайдер openid connect http://login.1c.ru/ и приложение https://1cfresh.com/

1. Авторизация пользователя. Необходимо перенаправить пользователя по адресу http://login.1c.ru/oidc/authorize, передав следующие параметры:

ПараметрОписаниеПример

client_id

Идентификатор приложения Фреш

fresh

redirect_uri

Адрес, на который будет переадресован пользователь после прохождения авторизации. Должен совпадать с redirect_uri, указанным на этапе подключения приложения Фреш

https://1cfresh.com/a/openid/e1cib/oid2op/sso/callback

scope

Набор разрешений, запрашиваемых приложением Фреш у провайдера, бывает не обязателен для определенных провайдеров.

openid 

response_type

Тип ответа, который необходимо получить. Фреш использует параметр code.

code

state

Любое значение, которое провайдер вернет на redirect_uri. Фреш использует JWT-токен для передачи значений возврата.

abc.def.jhi

Сервис Фреш выполняет этот запрос самостоятельно при переходе по ссылке входя через SSO, например https://1cfresh.com/a/openid/e1cib/oid2op/sso/login/portal.

2. Разрешение прав доступа. Если пользователь не авторизован, ему будет показана форма входа провайдера. После успешного входа пользователю будет предложено авторизовать приложение, разрешив доступ к своим данным.

3. Получение ключа доступа access_token. После успешной авторизации приложения браузер пользователя будет перенаправлен по адресу redirect_uri. При этом код для получения ключа доступа code будет передан параметром. Для получения access_token приложение Фреш выполнит POST запрос на https://login.1c.ru/oidc/accessToken, передав следующие параметры:

ПараметрОписание

client_id

Идентификатор приложения

client_secret

Защищенный ключ приложения

redirect_uri

Адрес, на который будет переадресован пользователь после прохождения авторизации. Должен совпадать с redirect_uri, указанным на этапе подключения приложения

code

Код, полученный после прохождения авторизации

grant_type

Тип запрашиваемого ресурса. Значение равно "authorization_code".

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

{  
   "access_token":"AT-1-JkxTQxtX3CqqLNBzPF5Qgxsj4HdwYaKFoOp",
   "token_type":"bearer",
   "expires_in":28800
}

Поле access_token в общем случае обязательно, но может быть передано и в данных при возврате на запрос разрешения прав доступа (шаг 2).

Получение данных пользователя

Приложение Фреш выполнит запрос по адресу получения данных пользователя, в примере это http://login.1c.ru/oidc/profile, передав access_token в заголовке Authrization.

В результате выполнения запроса приложение Фреш ожидает получить данные пользователя в ответе в виде JSON, например:

{  
   "sub":"test@1c.ru",
   "email": "test@1c.ru"
   "phone":"1111",
   "first_name":"Имя",
   "last_name": "Фамилия",
   "middle_name": "Отчество",
   "public_id": "7730643014"
}

Обрабатываемые свойства, которые ожидает получить приложение Фреш:

СвойствоОбязательноеОписание
subДаИдентификатор пользователя с стороннем сервисе для сопоставления пользователя в приложении Фреш
emailДаАдрес электронной почты пользователя. Используется в сервисе Фреш для поиска уже существующих пользователей. В рамках сервиса не может быть указано 2х одинаковых email.
phone
Номер телефона
first_name
Имя
last_name
Фамилия
middle_name
Отчество
public_id
Публичный идентификатор пользователя, например ИНН.

Имена свойств могут отличаться. Взаимодействие с провайдером в приложении Фреш настраивается для каждого провайдера индивидуально.

Схема работы без использования OAuth2 и OpenId-Connect

Схема работы, которую должен поддержать сервис, не поддерживающий OAuth2 или OpenID-Connect

Вход в приложение

Процесс входа пользователя в приложение облачного сервиса Фреш по технологии единого входа без использования OAuth2 или OpenID-Connect:

  1. Обслуживающая организация перенаправляет пользователя на адрес OpenID-провайдера методом POST. В теле запроса содержатся данные аутентификации, адрес приложения, одноразовый ключ (вместо пароля).
  2. Данные верифицируются OpenId-провайдером с помощью симметричной подписи без обращению к провайдеру.
  3. Устанавливает cookie одноразового входа.
  4. OpenID-провайдер перенаправляет пользователя на адрес приложения.
  5. Приложение перенаправляет пользователя на OpenID-провайдер и передает OpenID-провайдеру ранее установленную им cookie (это стандартная схема работы с OpenID-провайдером).
  6. OpenID-провайдер обнаруживает cookie и перенаправляет пользователя на приложение с разрешением входа.

Получение секретного ключа

Для подписи данных авторизации используется секретный ключ. Секретный ключ генерируется OpenID-провайдером облачного сервиса Фреш.

Возможны 2 варианта автоматизированного получения секретного ключа:

  1. Периодическая отправка ключа, инициируемая облачным сервисом Фреш
  2. Отправка ключа по запросу от обслуживающей организации

Для обоих вариантов на стороне обслуживающей организации разворачивается отдельный HTTP-сервис, на который облачный сервис Фреш отправляет секретный ключ. Если в ответ на POST-запрос к этому сервису получен ответ с кодом 200, то это считается подтверждением получения секретного ключа. Адрес и параметры доступа к сервису получения секретного ключа задаются администратором сервиса Фреш в настройках поставщика удостоверений сквозной аутентификации. Для доступа к серверу обслуживающей организации может использоваться пользовательский сертификат.

На адрес сервиса для передачи ключа приходит запрос с разметкой JSON c данными:

  • id - идентификатор ключа подписи
  • expired - срок действия ключа подписи
  • key - двоичные данные ключа подписи в формате base64
Пример данных ключа подписи
{
"id": "19ab9b16-3262-49da-93a6-beef57a5e9fa",
"expired": "2018-08-10T09:43:42",
"key": "VT/QeNEo4yPotXZT6YNC2RHJwub4pAPqGs6Lq2Kbeqg="
}

Переданный ключ используется для подписи запросов с помощью алгоритма HMACSHA256.

Запросы на получение секретного ключа обслуживающей организацией

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

  • account/update_sso_key - выполняет запрос на отправку обновления ключа SSO авторизации
  • account/confirm_sso_key - подтверждает получение ключа SSO авторизации
  • account/truncate_sso_key - удаляет все ключи SSO авторизации кроме актуального.

Параметры запроса к Open-ID провайдеру

Имя

Описание

Обязательный

Пример

1
server

Адрес OpenID провайдера сервериса

Даhttps://stage.1cfresh.com/a/oid/hs/oid2op
2
assoc_handle
Идентификатор секретного ключа, генерируется на стороне OpenId провайдера и передается вместе с данными ключа для подписи.

Да

f5b66343-59bb-423a-8176-031a8f4f0ed3
3
response_nonce

Одноразовый номер для защиты от атак повторного использования (дата в формате XML до Z + GUID)

Генерируется обслуживающей организацией при каждом запросе.

Да

2017-11-16T09:31:34Zeab4f5ad-4bfa-4d8c-a1d3-f4bc08234bbf
4
provider
Уникальный код обслуживающей организации

Да

987
5
user_id
Уникальный идентификатор пользователя сервиса (GUID)Да*85e87f4f-0100-11e8-819b-0050568925e0
6
user
Логин пользователя в облачном сервисе Фреш

Да*

user.95@yopmail.com
7
tenant

Номер области данных пользователя

Да

365
8
sig

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

  1. assoc_handle
  2. response_nonce
  3. provider
  4. user_id
  5. user
  6. tenant

Да

5lm3OTtPXcpvopR0ueIYDncvgNOmCq/ZP088lm2xnMU=

Алгоритм вычисления подписи на псевдокоде:

sig = Base64Строка(HMACSHA256(
  assoc_handle + response_nonce + provider + user_id + user + tenant, key
))

Например, на языке C# эти действия могут быть выполнены инструкциями:

var data = Encoding.UTF8.GetBytes(
  assoc_handle + response_nonce + provider + user_id + user + tenant);
var sig = (new HMACSHA256(key)).ComputeHash(data);
9
anchor
Якорь на данные в приложении
e1cib/command/ОбщаяКоманда.МониторОсновныхПоказателей

* Для входа можно использовать идентификатор пользователя (user_id) или логин пользователя (user).

Пример страницы для перенаправления пользователя в приложение

Шаблон HTML-страницы
<!DOCTYPE html>
<html>
  <head>
  <meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
  <meta http-equiv='pragma' content='no-cache'/>
  <meta http-equiv='cache-control' content='no-cache'/>
  <meta http-equiv='expires' content='-1'/>
</head>
  <body onload='document.forms.form.submit()'>
    <form name='form' action='{{server}}' method='post'>
      <input type='hidden' name='assoc_handle' value='{{assoc_handle}}'/>
      <input type='hidden' name='response_nonce' value='{{response_nonce}}'/>
      <input type='hidden' name='provider' value='{{provider}}'/>
      <input type='hidden' name='user_id' value='{{user_id}}'/>
      <input type='hidden' name='user' value='{{user}}'/>
      <input type='hidden' name='tenant' value='{{tenant}}'/>
      <input type='hidden' name='sig' value='{{sig}}'/>
      <input type='hidden' name='anchor' value='{{anchor}}'/>
    </form>
  </body>
</html>
Пример HTML-страницы
<!DOCTYPE html>
<html>
	<head>
		<meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
		<meta http-equiv='pragma' content='no-cache'/>
		<meta http-equiv='cache-control' content='no-cache'/>
		<meta http-equiv='expires' content='-1'/>
	</head>
	<body onload='document.forms.form.submit()'>
		<form name='form' action='https://stage.1cfresh.com/a/oid/hs/oid2op?cmd=sso' method='post'>
			<input type='hidden' name='assoc_handle' value='f5b66343-59bb-423a-8176-031a8f4f0ed3'/>
			<input type='hidden' name='response_nonce' value='2017-11-16T09:31:34Zeab4f5ad-4bfa-4d8c-a1d3-f4bc08234bbf'/>
			<input type='hidden' name='provider' value='987'/>
			<input type='hidden' name='user' value='user.95@yopmail.com'/>
			<input type='hidden' name='user_id' value=''/>
			<input type='hidden' name='tenant' value='365'/>
			<input type='hidden' name='sig' value='5lm3OTtPXcpvopR0ueIYDncvgNOmCq/ZP088lm2xnMU='/>
			<input type='hidden' name='anchor' value=''/>
		</form>
	</body>
</html>


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