Unified Identity Management logo figure Unified Identity Management logo figure

UserDeviceContext

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

Введение

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

  • для принятия решения об аутентификации (например, разрешать вход только с разрешенного IP)

  • для протоколирования в данных аудита

  • для передачи во внешние системы, например, в системы антифрода.

Часть этой информации может быть получена от клиента UIDM, например, от мобильного или Web-приложения, а часть - определяется самим сервером UIDM.

Как использовать

Дополнительные параметры пользователя можно передавать в запросах протокола OAuth2 и M2M, пример запроса приведен далее.

Атрибуты контекста передаются с запросами на аутентификацию, результатом которых будет создание токена.

Атрибуты deviceDeterminedLocationContext, deviceDeterminedNetworkContext, mobileDeviceContext, additionalContextAttributes , описывающие контекст пользователя с точки зрения клиента UIDM, передаются с инициирующим запросом в виде параметров запроса.

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

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

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

Состав модели UserDeviceContext

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

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

{
  "deviceDeterminedLocationContext": {
    "coordinates": {
      "lat": {
        "valueDegrees": double
      },
      "lon": {
        "valueDegrees": double
      },
      "height": {
        "valueMeters": double
      }
    },
    "city": {
      "cityId": string,
      "nameNat": string,
      "nameInt": string
    },
    "region": {
      "regionId": string,
      "nameNat": string,
      "nameInt": string
    },
    "country": {
      "isoCode": string,
      "nameNat": string,
      "nameInt": string
    },
  },
  "geoIpDeterminedLocationContext": {
    "coordinates": {
      "lat": {
        "valueDegrees": double
      },
      "lon": {
        "valueDegrees": double
      },
      "height": {
        "valueMeters": double
      }
    },
    "city": {
      "cityId": string,
      "nameNat": string,
      "nameInt": string
    },
    "region": {
      "regionId": string,
      "nameNat": string,
      "nameInt": string
    },
    "country": {
      "isoCode": string,
      "nameNat": string,
      "nameInt": string
    },
  },
  "serverDeterminedIpNetworkContext": {
    "remoteAddress": string
  },
  "deviceDeterminedNetworkContext": {
    "mac": {
      "macAddress": string
    },
    "innerIp": {
      "remoteAddress": string
    },
    "extIp": {
      "remoteAddress": string
    },
  },
  "userAgentContext": {
    "userAgentString": string,
    "deviceType": string,
    "deviceBrand": string,
    "deviceModel": string,
    "osFamily": string,
    "osNameVersion": string,
    "browserType": string,
    "browserFamily": string,
    "browserNameVersion": string
  },
  "mobileDeviceContext": {
    "deviceId": string,
    "deviceLocale": string,
    "deviceOS": string,
    "deviceOSVersion": string,
    "appVersion": string,
    "deviceRoot": boolean,
    "deviceName": string,
  }
  "additionalContextAttributes": {
    "customParam1": string,
    "customParam2": string,
    "customParam3": string
  }
}

deviceDeterminedLocationContext

Передается клиентом UIDM

Содержит

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

  • высоту над уровнем моря в метрах

geoIpDeterminedLocationContext

Определяется сервером UIDM

Информация о местоположении, определяемая по данным базы GeoIp.

serverDeterminedIpNetworkContext

Определяется сервером UIDM

Сетевой контекст, определяемый сервером UIDM на основании HTTP-заголовков запроса. ipAddress может передаваться в стандартном формате IPv4 или IPv6

deviceDeterminedNetworkContext

Передается клиентом UIDM

Сетевой контекст определяемый клиентом (устройством).

Передается с параметрами mac, extIp, innerIp запроса. IP-адреса могут передаваться в стандартных форматах IPv4 или IPv6

userAgentContext

Определяется сервером UIDM

Информация об устройстве пользователя, полученная сервером UIDM на основе анализа HTTP заголовка UserAgent.

mobileDeviceContext

Передается клиентом UIDM

Контекст передаваемый с клиента (устройства) с данными по мобильному устройству.

Передается с параметром device_info запроса в виде JSON-строки.

{
  "deviceId": string,
  "deviceLocale": string,
  "deviceOS": string,
  "deviceOSVersion": string,
  "appVersion": string,
  "deviceRoot": boolean,
  "deviceName": string,
}

additionalContextAttributes

Передается клиентом UIDM

Кастомные атрибуты контекста передаются с одноименными параметрами запроса и определяются конфигурацией.

Формат запроса с передачей UserDeviceContext параметров

Формат запроса

Пример отправки параметров UserDeviceContext со вторым запросом в цепочке аутентификации (на шаге аутентификации пользователя по логину и паролю).

POST /sso/oauth2/access_token HTTP/1.1
Host: <sso_host>
Accept: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=%2Fcustomer&
service=dispatcher&
execution=<execution>&
username=<username>&
password=<password>&
mac=<mac>&
innerIp=<innerIp>&
extIp=<extIp>&
device_info=<device_info>&
custom_param=<custom_param>&
_eventId=next

Базовые параметры запроса

В данном документе информация приведена для справки, подробнее см. спецификацию на протокол. * <sso_host> - базовый адрес сервера WebSSO, например sso.rooxteam.com * <client_id> - идентификатор клиента, например selfcare * <client_secret> - пароль клиента * <scope> - OAuth2.0 scope в кодировке UTF-8, опционально, регистрозависимо * <grant_type> - способ авторизации пользователя, всегда используется значение urn:roox:params:oauth:grant-type:m2m * <realm> - группа пользователей WebSSO, всегда используется значение %2Fcustomer, которое является uri-encoded значением /customer * <execution> - идентификатор предсессии аутентификации, значение берется из предыдущего ответа сервера * <service> - имя цепочки аутентификации, всегда dispatcher * <username> - имя пользователя (номер телефона) * <password> - пароль пользователя * <_eventId> - идентификатор действия, всегда next

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

  • <mac> - MAC-адрес сетевого адаптера (поле deviceDeterminedNetworkContext.mac.macAddress)

  • <innerIp> - внутренний IP-пользователя пользователя (поле deviceDeterminedNetworkContext.innerIp.remoteAddress)

  • <extIp> - внешний IP-адрес пользователя (поле deviceDeterminedNetworkContext.extIp.remoteAddress)

  • <device_info> - JSON-строка с информацией об устройстве пользователя (поле mobileDeviceContext)

  • <custom_param> - дополнительный параметр контекста (поле additionalContextAttributes.custom_param)

Настройки, управляющие функциональностью

Управление дополнительными атрибутами контекста

Ключ com.rooxteam.sso.userContext.additionalAttributes.{custom_attr_name}.max_length={length}

Описание

Разрешить использовать дополнительный параметр контекста с именем`{custom_attr_name}` и задать максимально-возможную длину {length} (целое число от 1 до TBD)

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

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

Значение по-умолчанию - если ключи не заданы, дополнительные параметры не передаются

Добавление атрибутов контекста в клеймы токена

Любой атрибут контекста UIDM может передать в клеймах токена. Наименование клейма устанавливается конфигурацией. Атрибуты контекста, которые попадут в клейм, также устанавливаются конфигурацией.

Ключ

com.rooxteam.sso.userContext.claim_properties

Описание

Устанавливает соответствие между параметрами атрибута клейма токена и атрибутами контекста.

Значения передаются в виде списка {attr_name}={nested_property}, где {attr_name} - наименование клейма в токене, {nested_property} - полное с учетом пути имя атрибута контекста, которое надо передать в клейм

Например, чтобы передать в клейм токена атрибут с именем mac и значением MAC-адреса из deviceDeterminedNetworkContext, нужно задать следующее соответствие: mac=deviceDeterminedNetworkContext.mac.macAddress.

Список разделяется запятыми.

Значение по умолчанию

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

Ключ

com.rooxteam.sso.userContext.claim_name

Описание

Устанавливает наименование клейма в который будут попадать атрибуты UserDeviceContext, заданные настройкой com.rooxteam.sso.userContext.claim_properties

Значение по умолчанию

device_ctx

Пример конфигурации для следующей постановки

Необходимо передать в клейм токена с именем devctx значения контекста: mac, innerIp, extIp, customParam1.

Конфигурация:

com.rooxteam.sso.userContext.additionalAttributes.customParam1.max_length=10
com.rooxteam.sso.userContext.claim_name=devctx
com.rooxteam.sso.userContext.claim_properties=mac=deviceDeterminedNetworkContext.mac.macAddress,innerIp=deviceDeterminedNetworkContext.innerIp.remoteAddress,extIp=deviceDeterminedNetworkContext.extIp.remoteAddress,customParam1=additionalContextAttributes.customParam1

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

{
  ...
  "devctx": {
    "mac": "01:23:45:67:89:ab",
    "innerIp": "192.168.0.42",
    "extIp": "179.253.12.11",
    "customParam1": "value1"
  }
  ...
}

Добавление атрибутов контекста в аудит

Любой атрибут контекста можно передать в аудит (поле data) или внешнюю систему (например, антифрод) Наименование параметра и атрибутов устанавливается конфигурацией аналогично добавлению клейма в токен.

Ключ

com.rooxteam.sso.userContext.audit_name

Описание

Устанавливает наименование атрибута в поле data аудита, в который будут попадать атрибуты UserDeviceContext, заданные настройкой com.rooxteam.sso.userContext.claim_properties

Значение по-умолчанию

device_ctx

Ключ

com.rooxteam.sso.userContext.audit_properties

Описание

Устанавливает соответствие между параметрами атрибута для аудита и атрибутами контекста.

Важно
Данный параметр работает только в протоколе M2M! В протоколе Login-API в аудит попадают атрибуты контекста из клаймов токена. См. конфигурационный ключ com.rooxteam.sso.userContext.claim_properties

Значения передаются в виде списка {attr_name}={nested_property}, где {attr_name} - наименование параметра атрибута аудита, {nested_property} - полное с учетом пути имя атрибута контекста, которое надо сохранить в аудит

Например, чтобы сохранить в аудит параметр с именем mac и значением MAC-адреса из deviceDeterminedNetworkContext, нужно задать следующее соответствие: mac=deviceDeterminedNetworkContext.mac.macAddress.

Список разделяется запятыми.

Значение по-умолчанию Если параметр не задан, никакие атрибуты в аудит не передаются.