API администрирования#

Администрировать Blitz Identity Provider можно с помощью:

консоли управления;
конфигурационных файлов;
административные REST-сервисов.

Административные REST-сервисы в Blitz Identity Provider в текущей версии позволяют выполнять следующие действия:

регистрация приложений;
получение настроек приложений;
изменение настроек приложений;
удаление приложений.

Административные REST-сервисы доступны по адресу https://login.company.com/blitz/admin/api/v3/...

Для включения административных сервисов предварительно должны быть сделаны настройки на веб-сервере, используемом Blitz Identity Provider. Не рекомендуется публиковать административные REST-сервисы в сети Интернет.

Пример блока location в настройках веб-сервера nginx для включения доступности административных REST-сервисов:

location /blitz/admin/api {
    proxy_intercept_errors off;
    proxy_pass  http://blitz-console/blitz/admin/api;
}

Доступ к административным REST-сервисам регулируется с помощью разрешений (scope), приведенных в таблице:

Разрешения (scope) для административных REST API

№

Разрешение

Название

Описание

blitz_api_sys_app

Разрешение на чтение настроек приложений

Для использования сервиса

GET /blitz/admin/api/v3/app/{appId}

blitz_api_sys_app_chg

Разрешение на внесение изменений в настройки приложений

Для использования сервисов:

PUT /blitz/admin/api/v3/app/{appId}

POST /blitz/admin/api/v3/app/{appId}

DELETE /blitz/admin/api/v3/app/{appId}

Чтобы получить маркер доступа на системное разрешение, приложение должно выполнить запрос методом POST на URL для получения маркера (https://login.company.com/blitz/oauth/te). Запрос должен содержать заголовок Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

Пример заголовка:

Authorization: Basic YWlzOm…XQ=

Тело запроса должно содержать следующие параметры:

grant_type – принимает значение client_credentials;
scope – запрашиваемое системное разрешение.

Пример запроса:

POST blitz/oauth/te HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ZG5ld…lg

grant_type=client_credentials&scope=blitz_api_sys_app+blitz_api_sys_app_chg

В ответ приложение получит маркер доступа (access_token), время его жизни (expires_in) и тип маркера (token_type). Возможные ошибки при вызове /oauth/te соответствуют RFC 6749.

Пример ответа с успешным выполнением запроса:

{
   "access_token": "QFiJ9mPgERPuusd36mQvD4mfzYolH_CmuddAJ3YKTOI",
   "expires_in": 3600,
   "scope": "blitz_api_sys_app blitz_api_sys_app_chg",
   "token_type": "Bearer"
}

Рекомендуется, чтобы приложение кэшировало полученный маркер доступа для многократного использования на время, немного меньшее, чем параметр expires_in, после чего осуществляло получение нового маркера доступа для обновления в кэше.

Если приложение попытается вызвать с просроченным маркером доступа соответствующий ему REST-сервис, то получит ошибку HTTP 401 Unauthorized.

Получение настроек приложений#

Для получения настроек приложения по его идентификатору необходимо методом GET вызвать сервис по адресу https://login.company.com/blitz/admin/api/v3/app/{appId}.

Необходимые разрешения: blitz_api_sys_app.

В результате выполнения запроса Blitz Identity Provider вернет JSON, содержащий настройки приложения.

Пример запроса:

GET /blitz/admin/api/v3/app/test-app HTTP/1.1
Authorization: Bearer cNw…Nz

Пример ответа:

HTTP/2 200
…
content-type: application/json
etag: 96_1658847045000

{
    "name":"…",
    "tags": [
        "tag1",
        "tag2"
    ],
    "domain":"…",
    "startPageUrl":"…",
    "oauth": {
        "clientSecret":"…",
        "redirectUriPrefixes":["…"],
        "predefinedRedirectUri":"…",
        "availableScopes":["…","…"],
        "defaultScopes":["…"],
        "enabled":true,
        "autoConsent":true,
        "idToken":{"claims":["…"]},
        "accessTokenTtl":3600,
        "defaultAccessType":"online",
        "refreshTokenTtl":86400,
        "dynReg":{
            "isAllow":true,
            "allowedPlainJsonClaims":["device_type"]
        },
        "pixyMandatory":true,
        "deviceGrant": {
            "userCodeFormat":"[0-9]{3,3}-[0-9]{3,3}-[0-9]{3,3}",
            "userCodeTtl":120,
            "verificationUrl":"…",
            "useCompleteUri":true
        },
        "teAuthMethod":"client_secret_basic",
        "grantTypes":["authorization_code","client_credentials"],
        "responseTypes":["code"],
        "extraClientSecret":"…",
        "accessTokenFormat":"jwt",
        "logout": {
            "logoutAutoConsent":false,
            "logoutUriPrefixes":["…"],
            "predefinedLogoutUri":"…",
            "frontchannelLogoutUri":"…",
            "frontchannelLogoutSessionRequired":true,
            "backchannelLogoutUri":"…"
        }
    },
    "simple": {
        "ssl":true,
        "formSelector":"…",
        "loginSelector":"…",
        "logoutUrl":"…",
        "postLogoutUrl":"…"
    },
    "rest": {
        "Basic":{"pswd":"…"},
        "TLS":[]
    },
    "theme":"default",
    "saml": {
        "spMetadata":"…",
        "spAttributeFilterPolicy": {
            "id":"test-app",
            "attributeRules":[{"attr":"…","isPermitted":true}]
        },
        "saml2SSOProfile": {
            "signAssertions":"always",
            "encryptAssertions":"always",
            "encryptNameIds":"always",
            "includeAttributeStatement":true
        }
    }
}

Содержимое ответа может отличаться в зависимости от заданных для приложения настроек и сконфигурированных протоколов подключения. Блоки saml, oauth, simple, rest могут отсутствовать, если соответствующие протоколы для приложения не настроены.

В ответе сервиса присутствует заголовок etag. Значение из этого заголовка следует использовать в заголовке If-Match, если планируется после получения настроек приложения вызывать сервисы регистрации приложения, редактирования настроек приложения или удаления приложения. С помощью etag Blitz Identity Provider проверяет, что между последним получением etag и вызовом операции изменения настроек с If-Match не выполнялись какие-либо еще изменения в конфигурационном файле на сервере в параллельных сеансах (оптимистичное блокирование).

При использовании SAML в настройке spMetadata будет находиться закодированный в Base64URL файл метаданных для приложения (Service Provider Metadata).

Имена возвращаемых сервисом настроек соответствуют именам в конфигурационном файле blitz.conf.

Если настройки приложения по переданному appId не будут найдены, то сервер Blitz Identity Provider вернет ошибку HTTP 404 Not found.

Регистрация приложения#

Для регистрации приложения необходимо выполнить запрос методом PUT по адресу https://login.company.com/blitz/admin/api/v3/app/{appId}.

Необходимые разрешения: blitz_api_sys_app_chg.

В запрос может быть (опционально) добавлен заголовок If-Match, содержащий последнее полученное от сервера значение etag.

Тело запроса должно содержать значения настроек регистрируемого приложения.

Пример запроса:

PUT /blitz/admin/api/v3/app/test-app2 HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json
If-Match: 98_1658857264000

{
    "name":"…",
    "tags": [
        "tag1",
        "tag2"
    ],
    "domain":"…",
    "startPageUrl":"…",
    "oauth": {
        "clientSecret":"…",
        "redirectUriPrefixes":["…"],
        "predefinedRedirectUri":"…",
        "availableScopes":["…","…"],
        "defaultScopes":["…"],
        "enabled":true,
        "autoConsent":true,
        "idToken":{"claims":["…"]},
        "accessTokenTtl":3600,
        "defaultAccessType":"online",
        "refreshTokenTtl":86400,
        "dynReg":{
            "isAllow":true,
            "allowedPlainJsonClaims":["device_type"]
        },
        "pixyMandatory":true,
        "deviceGrant": {
            "userCodeFormat":"[0-9]{3,3}-[0-9]{3,3}-[0-9]{3,3}",
            "userCodeTtl":120,
            "verificationUrl":"…",
            "useCompleteUri":true
        },
        "teAuthMethod":"client_secret_basic",
        "grantTypes":["authorization_code","client_credentials"],
        "responseTypes":["code"],
        "extraClientSecret":"…",
        "accessTokenFormat":"jwt",
        "logout": {
            "logoutAutoConsent":false,
            "logoutUriPrefixes":["…"],
            "predefinedLogoutUri":"…",
            "frontchannelLogoutUri":"…",
            "frontchannelLogoutSessionRequired":true,
            "backchannelLogoutUri":"…"
        }
    },
    "simple": {
        "ssl":true,
        "formSelector":"…",
        "loginSelector":"…",
        "logoutUrl":"…",
        "postLogoutUrl":"…"
    },
    "rest": {
        "Basic":{"pswd":"…"},
        "TLS":[]
    },
    "theme":"default",
    "saml": {
        "spMetadata":"…",
        "spAttributeFilterPolicy": {
            "id":"…",
            "attributeRules":[{"attr":"…","isPermitted":true}]
        },
        "saml2SSOProfile": {
            "signAssertions":"always",
            "encryptAssertions":"always",
            "encryptNameIds":"always",
            "includeAttributeStatement":true
        }
    }
}

При регистрации приложения, работающего по SAML, нужно учесть следующие особенности:

в spMetadata нужно передавать содержимое метаданных приложения, закодированное в формате Base64URL.
в настройку id в spAttributeFilterPolicy необходимо передать тот же id, что передан в URL в качестве appId.

Если регистрация успешна, то сервер вернет HTTP 200, актуальные данные приложения и актуальное значение etag.

Пример ответа:

HTTP/2 200
…
content-type: application/json
etag: 99_1658857631000

{
    "id":"test-app2",
    "name":"…",
    …
    "oauth": {
        …
    },
    …
}

Если при регистрации приложения будет обнаружено, что данные в конфигурационном файле на сервере были изменены между получением etag и вызовом регистрации, то сервер вернет ответ с кодом HTTP 412 Precondition Failed и телом ошибки:

{
   "type":"process_error",
   "error":"cas_mismatch",
   "desc":"cas_mismatch"
}

Если при регистрации приложения возникла ошибка, то сервер вернет ответ с кодом HTTP 400 Bad Request с описанием ошибки.

Пример ответа с ошибкой регистрации:

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "json.error.mandatory.field",
            "desc": "json.error.expected.array",
            "pos": "oauth.redirectUriPrefixes"
        },
        …
    ]
}

Изменение настроек приложения#

Для изменения настроек приложения необходимо выполнить запрос методом POST по адресу https://login.company.com/blitz/admin/api/v3/app/{appId}.

Необходимые разрешения: blitz_api_sys_app_chg.

В запрос должен быть добавлен заголовок If-Match, содержащий последнее полученное от сервера значение etag.

Тело запроса должно содержать значения изменяемых настроек приложения после редактирования. Должна быть передана вся ветка с изменяемым параметром. Например, если параметр находится на третьем уровне, то нужно также прислать его родительские параметры на первом и втором уровнях. Для того чтобы удалить параметр, необходимо прислать всю ветку со значением null для этого параметра.

Пример запроса изменения метки приложения:

POST /blitz/admin/api/v3/app/test-app HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json
If-Match: 98_1658857264000

{
    "tags": [
        "default",
        "2F"
    ]
}

Если изменение успешно, то сервер вернет HTTP 200, актуальные значения настроек приложения и новый etag.

Пример ответа:

HTTP/2 200
…
content-type: application/json
etag: 99_1658857631000

{
    "name": "",
    "tags": [
        "default",
        "2F"
    ],
    "domain": "test.app1.ru",
    "id": "app1",
    "simple": {
        "formSelector": "select",
        "postLogoutUrl": "http://localhost",
        "ssl": true,
        "loginSelector": "select",
        "js": "dyMw==",
        "logoutUrl": "https://localhost"
    },
    "disabled": false
}

Пример запроса удаления меток приложения:

POST /blitz/admin/api/v3/app/test-app HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json
If-Match: 98_1658857264000

{
    "tags": null
}

Пример ответа:

HTTP/2 200
…
content-type: application/json
etag: 99_1658857631000

{
    "name": "",
    "domain": "test.app1.ru",
    "id": "app1",
    "simple": {
        "formSelector": "select",
        "postLogoutUrl": "http://localhost",
        "ssl": true,
        "loginSelector": "select",
        "js": "dyMw==",
        "logoutUrl": "https://localhost"
    },
    "disabled": false
}

Если при редактировании приложения будет обнаружено, что данные в конфигурационном файле на сервере были изменены между получением etag и вызовом редактирования, то сервер вернет ответ с кодом HTTP 412 Precondition Failed и телом ошибки:

{
   "type":"process_error",
   "error":"cas_mismatch",
   "desc":"cas_mismatch"
}

Если при редактировании приложения возникла ошибка, что переданы неправильные данные, то сервер вернет ответ с кодом HTTP 400 Bad Request с описанием ошибок.

Пример ответа с ошибкой:

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "json.error.mandatory.field",
            "desc": "json.error.expected.array",
            "pos": "oauth.redirectUriPrefixes"
        },
        …
    ]
}

Удаление приложения#

Для удаления приложения необходимо выполнить запрос методом DELETE по адресу https://login.company.com/blitz/admin/api/v3/app/{appId}.

Необходимые разрешения: blitz_api_sys_app_chg.

В запрос должен быть добавлен заголовок If-Match, содержащий последнее полученное от сервера значение etag.

Пример запроса:

DELETE /blitz/admin/api/v3/app/test-app HTTP/1.1
Authorization: Bearer cNw…Nz
If-Match: 99_1658857631000

Если приложение успешно удалено, то сервер вернет HTTP 204.

Если при удалении приложения будет обнаружено, что данные в конфигурационном файле на сервере были изменены между получением etag и вызовом удаления, то сервер вернет ответ с кодом HTTP 412 Precondition Failed и телом ошибки:

{
   "type":"process_error",
   "error":"cas_mismatch",
   "desc":"cas_mismatch"
}