Administration API#
You can administer Blitz Identity Provider using:
admin console;
configuration files;
administrative REST services.
Administrative REST services in Blitz Identity Provider in the current version allow you to perform the following actions:
application registration;
get application settings;
change application settings;
delete applications.
Administrative REST services are available at https://login.company.com/blitz/admin/api/v3/...
To enable administrative services, settings must first be made on the web server used by Blitz Identity Provider. It is not recommended to publish administrative REST services on the Internet.
An example of the location block in the nginx web server settings to enable the availability of administrative REST services:
location /blitz/admin/api {
proxy_intercept_errors off;
proxy_pass http://blitz-console/blitz/admin/api;
}
Access to administrative REST services is regulated using the permissions (scope) listed in the table:
Permissions (scope) for administrative REST APIs
No. |
Permission |
Name |
Description |
|---|---|---|---|
|
Permission to read application settings |
To use the service
|
|
|
Permission to make changes to application settings |
To use the services:
|
To get an access token for system permission, the application must make a POST request to the URL to receive the token (https://login.company.com/blitz/oauth/te). The request must contain the header Authorization with the value Basic {secret}, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.
Example of a header:
Authorization: Basic YWlzOm…XQ=
The request body must contain the following parameters:
grant_type– takes the valueclient_credentials;scopeis the requested system permission.
Request example:
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
In response, the application will receive an access token (access_token), its lifetime (expires_in) and the token type (token_type). Possible errors when calling /oauth/te correspond to RFC 6749.
Example of a response with successful execution of the request:
{
"access_token": "QFiJ9mPgERPuusd36mQvD4mfzYolH_CmuddAJ3YKTOI",
"expires_in": 3600,
"scope": "blitz_api_sys_app blitz_api_sys_app_chg",
"token_type": "Bearer"
}
It is recommended that the application caches the received access token for repeated use for a time slightly less than the expires_in parameter, after which it receives a new access token for updating in the cache.
If the application tries to call the corresponding REST service with an expired access token, it will receive the error HTTP 401 Unauthorized.
Getting application settings#
To get the application settings by its identifier, you need to use the GET method to call the service at https://login.company.com/blitz/admin/api/v3/app/{appId}.
Required permissions: blitz_api_sys_app.
As a result of executing the request, Blitz Identity Provider will return a JSON containing the application settings..
Request example:
GET /blitz/admin/api/v3/app/test-app HTTP/1.1
Authorization: Bearer cNw…Nz
Response example:
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
}
}
}
The content of the response may differ depending on the settings set for the application and the configured connection protocols. The saml, oauth, simple, and rest blocks may be missing if the appropriate protocols for the application are not configured.
The service’s response contains the etag header. The value from this header should be used in the If-Match header if you plan to call the application registration services, edit application settings, or delete the application after receiving the application settings. Using etag Blitz Identity Provider checks that no other changes were made to the configuration file on the server in parallel sessions (optimistic blocking) between the last receipt of etag and calling the settings change operation with If-Match.
When using SAML, the spMetadata setting will contain a Base64URL encoded metadata file for the application (Service Provider Metadata).
The names of the settings returned by the service correspond to the names in the configuration file blitz.conf.
If the application settings for the transmitted appId are not found, the Blitz Identity Provider server returns the error HTTP 404 Not found.
Application registration#
To register an application, you need to make a PUT request at https://login.company.com/blitz/admin/api/v3/app/{appId}.
Required permissions: blitz_api_sys_app_chg.
The If-Match header can be (optionally) added to the request, containing the last etag value received from the server.
The request body must contain the settings values of the registered application.
Request example:
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
}
}
}
When registering an application running on SAML, you need to consider the following features:
the contents of the application metadata encoded in the Base64URL format must be passed to
spMetadata.in the
idsetting in the spAttributeFilterPolicy, you must pass the sameidthat is passed in the URL as theappId.
If registration is successful, the server will return HTTP 200, the current application data and the current value etag.
Response example:
HTTP/2 200
…
content-type: application/json
etag: 99_1658857631000
{
"id":"test-app2",
"name":"…",
…
"oauth": {
…
},
…
}
If, during application registration, it is found that the data in the configuration file on the server was changed between receiving the etag and calling registration, the server will return a response with the code HTTP 412 Precondition Failed and the error body:
{
"type":"process_error",
"error":"cas_mismatch",
"desc":"cas_mismatch"
}
If an error occurred during application registration, the server will return a response with the code HTTP 400 Bad Request with a description of the error.
Example of a response with a registration error:
{
"type": "input_error",
"error": "wrong_values",
"errors": [
{
"type": "input_error",
"error": "json.error.mandatory.field",
"desc": "json.error.expected.array",
"pos": "oauth.redirectUriPrefixes"
},
…
]
}
Changing application settings#
To change the application settings, you need to make a POST request to https://login.company.com/blitz/admin/api/v3/app/{appId}.
Required permissions: blitz_api_sys_app_chg.
The If-Match header should be added to the request, containing the last etag value received from the server.
The request body must contain the new values of the application settings you want to change. You must send the entire branch with the parameter to be changed. For example, if the parameter is at level #3, its parent parameters at levels #1 and #2 must also be sent. To delete a parameter, the entire branch with the null value for that parameter must be sent.
Example of changing an application tag:
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"
]
}
If the change is successful, the server will return HTTP 200, the current values of the application settings and a new etag.
Response example:
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
}
Example of deleting an application tags:
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
}
Response example:
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
}
If, when editing the application, it is found that the data in the configuration file on the server was changed between receiving the etag and calling the edit, the server will return a response with the code HTTP 412 Precondition Failed and the error body:
{
"type":"process_error",
"error":"cas_mismatch",
"desc":"cas_mismatch"
}
If an error occurred while editing the application that incorrect data was transmitted, the server will return a response with the code HTTP 400 Bad Request with a description of the errors.
Example of an error response:
{
"type": "input_error",
"error": "wrong_values",
"errors": [
{
"type": "input_error",
"error": "json.error.mandatory.field",
"desc": "json.error.expected.array",
"pos": "oauth.redirectUriPrefixes"
},
…
]
}
Deleting an application#
To delete an application, you must make a request using the DELETE method at https://login.company.com/blitz/admin/api/v3/app/{appId}.
Required permissions: blitz_api_sys_app_chg.
The If-Match header should be added to the request, containing the last etag value received from the server.
Request example:
DELETE /blitz/admin/api/v3/app/test-app HTTP/1.1
Authorization: Bearer cNw…Nz
If-Match: 99_1658857631000
If the application is successfully deleted, the server returns HTTP 204.
If, when deleting the application, it is found that the data in the configuration file on the server was changed between receiving the etag and calling the deletion, the server will return a response with the code HTTP 412 Precondition Failed and the error body:
{
"type":"process_error",
"error":"cas_mismatch",
"desc":"cas_mismatch"
}