Настройка Token Exchange#

Blitz Identity Provider поддерживает технологию обмена маркеров доступа OAuth 2.0 Token Exchange. Стандартным применением данной технологии в Blitz Identity Provider является взаимодействие шлюза безопасности Blitz Keeper с сервисом авторизации для получения доступа к защищаемым сервисам.

Для настройки Token Exchange выполните описанную ниже последовательность действий.

Шаг 1. Создание правила доступа к сервисам#

Правила доступа по Token Exchange к защищаемым сервисам создаются в директории /usr/share/identityblitz/blitz-config/token_exchange/rules/. Каждое правило создается как отдельный текстовый файл без расширения.

Пример файла с правилом доступа (тип specialize):

{
    "name": "rule-name",
    "type": "specialize",
    "desc": "",
    "subjectTokenCond": {
        "clientRights": [],
        "userRights": [],
        "scopes": ["openid"],
        "userClaims": {},
        "userGroups": []
    },
    "issue": {
        "ttlInSec": 3600,
        "allowedScopes": ["openid","profile"],
        "allowedClaims": ["sub","global_role","org_id","rights"],
        "addingScopes": [],
        "addingClaims": []
    }
}

Пример файла с правилом доступа (тип impersonate):

{
    "name": "rule-name",
    "type": "impersonate",
    "desc": "",
    "subjectTokenCond": {
        "clientRights": [],
        "userRights": [],
        "scopes": ["openid"],
        "userClaims": {},
        "userGroups": []
    },
    "authClientCond": {
        "requiredRights":[
            {
                "rights": ["right1"],
                "target": {
                    "type": "its",
                    "name": "app1"
                }
            }
    },
    "issue": {
        "ttlInSec": 3600,
        "allowedScopes": ["openid","profile"],
        "allowedClaims": ["sub","global_role","org_id","rights"],
        "addingScopes": [],
        "addingClaims": []
    }
}

Нужно заполнить следующие атрибуты правила доступа:

  • name – имя правила, которое должно совпадать с именем файла с правилом доступа;

  • type – тип правила. Поддерживаются следующие типы правил:

    • specialize – по такому правилу приложение запрашивает обмен маркера доступа, выданного этому же приложению. Обмен выполняется с целью специализации маркера доступа – замены в нем разрешений (scope), атрибутов (claims) и списка получателей (audience, aud), формат маркера (jwt или opaque);

    • impersonate – по такому правилу приложение запрашивает обмен маркера доступа, выданного другому приложению. Обмен выполняется при условии, что в предоставленном на обмен маркере доступа запрашивающее обмен приложение присутствует в списке получателей (audience, aud). Обмен используется в сценариях, когда приложение А получило исходно маркер доступа, подготовило его для передачи приложению Б (через обмен по типу правила specialize), передало приложению Б, так, что приложение Б выпустило на основе полученного маркера доступа свой собственный (через обмен по типу правила impersonate).

  • desc – описание правила. Можно ввести любую текстовую информацию;

  • subjectTokenCond – условия выполнения правила. Если все указанные в правиле условия будут выполняться, то правило считается выполненным. Если хотя бы одно из условий в правиле не будет выполнено, то все правило считается невыполненным. Условия выполнения правил могут быть следующие:

    • clientRights – проверка наличия у приложения указанных прав доступа;

      Пример правила:

      "clientRights": [
{
    "rights": ["right1"],
    "target": {
    "type": "its",
    "name": "app1"
    }
}
]

      В указанном примере проверяется наличие у вызывающего приложения права доступа right1 в отношении другого приложения (app1). Параметр its в настройке target указывает тип объекта, в отношении которого проверяется наличие права доступа. Возможные значения: its – право на приложение; grps – право на группу доступа; отсутствие type – право на учетную запись пользователя.

    • userRights – проверка наличия у пользователя указанных прав доступа.

      Пример 1 правила:

      "userRights": [
{
    "rights": ["right2"],
    "target": {
    "type": "grps",
    "name": "org1",
    "ext": "orgs"
    }
}
]

      В указанном примере проверяется наличие у пользователя права доступа right2 в отношении группы пользователей (org1). В случае типа объекта группы доступа указывается дополнительный параметр ext, определяющий профиль группы доступа (см. Включение отображения групп в blitz.conf).

      Пример 2 правила:

      "userRights": [
{
    "rights": ["security_administrator"],
    "target": {
    "type": "grps",
    "name": "${org_id}",
    "ext": "orgs"
    }
}
]

      В указанном правиле проверяется наличие у пользователя права доступа security_administrator в отношении группы пользователей из профиля orgs, имеющей идентификатор, совпадающий со значением атрибута org_id из состава исходного маркера доступа. В отличии от примера 1 в данном примере иллюстрируется возможность в качестве имени объекта права доступа указывать не конкретное значение объекта, а ссылаться на объект на основе значений из присланного маркера доступа ($org_id).

      Пример 3 правила:

      "userRights": [
{
    "rights": ["right3"],
    "target": {
    "type": "its",
    "name": "app1"
    }
}
]

      В данном примере проверяется наличие у пользователя права доступа right3 в отношении приложения app1.

    • scopes – проверка присутствия в маркере доступа требуемых разрешений (см. Общие настройки OAuth 2.0);

      Пример правила:

      "scopes": ["scope1"]

      В данном примере проверяется наличие в исходном маркере доступа разрешения с именем scope1.

    • userClaims – проверка, что у учетной записи пользователя атрибуты имеют указанные значения.

      Пример правила:

      "userClaims": {"role":"FIN"}

      В данном примере проверяется наличие у пользователя в учетной записи атрибута role с заполненным значением FIN. Допустимо использовать только атрибуты с типом String.

    • userGroups – проверка, что учетная запись пользователя входит в указанные группы доступа.

      Пример правила:

      "userGroups": [
{
    "name": "admin",
    "profile": "roles"
}
]

      В данном примере проверяется, что пользователь входит в группу доступа admin с профилем roles.

  • authClientCond – условия замены client_id. Эти условия проверяются только для правил с типом impersonate. В правиле проверяется, что новое приложение имеет права доступа для обмена маркера доступа. Поддерживается условие requiredRights.

    Пример правила:

    "requiredRights":[
  {
    "rights": ["right1"],
    "target": {
      "type": "its",
      "name": "app1"
    }
  }
]

    В указанном примере проверяется наличие у вызывающего приложения права доступа right1 в отношении другого приложения (app1). Параметр its в настройке target указывает тип объекта, в отношении которого проверяется наличие права доступа. Возможные значения: its – право на приложение; grps – право на группу доступа; отсутствие type – право на учетную запись пользователя.

  • issue – правила выпуска нового маркера доступа, применяемые в случае, если правило было успешно выполнено. Правила выпуска нового маркера доступа состоят из:

    • ttlInSec – время жизни (в секундах) выпускаемого маркера доступа;

    • allowedScopes – разрешения, которые можно оставить в выпускаемом маркере доступа;

    • allowedClaims – атрибуты пользователя, которые можно оставить в выпускаемом маркере доступа;

    • addingScopes – добавляемые в маркер доступа разрешения;

    • addingClaims – добавляемые в маркер доступа атрибуты пользователя.

Шаг 2. Настройка обмена маркеров доступа#

Чтобы определить, как будет происходить обмен маркеров доступа по Token Exchange, а именно для каких защищаемых сервисов какие правила доступа будут применяться, необходимо в конфигурационном файле blitz.conf добавить блок настроек blitz.prod.local.idp.token-exchange следующего вида:

"token-exchange" : {
  "resources" : [
    {
      "uri" : "http://secured_service_host/api/service1",
      "methods" : ["GET","POST"],
      "rules" : [
        "rule1",
        "rule2"
      ]
    },
    {
      "audience" : "secured-api",
      "rules" : [
        "rule3"
      ]
    },
    …
  ]
}

В блоке resources нужно для каждого сервиса заполнить настройки:

  • rules – перечислить имена правил доступа к сервису. Каждому правилу соответствует свой файл настроек. Доступ к сервису разрешается, если хотя бы одно из правил из этого списка будет выполненным. Если все перечисленные правила не будут выполнены, то тогда доступ к сервису будет запрещен;

  • uri – необязательный параметр, может задавать адрес защищаемого сервиса. В задании адреса сервиса допустимо использовать звездочку (*) для пропуска одного компонента пути адреса и двойную звездочку (**) для пропуска оставшейся части пути адреса сервиса;

  • methods – необязательный параметр, указывает перечень HTTP-методов вызываемого сервиса;

  • audience – необязательный параметр, может задавать имя приложения. Данное значение будет включено в выпущенный новый маркер доступа в атрибут aud. Обязательно должен быть указан один из параметров uri или audience.