Updating Blitz Identity Provider#

Important

If the update is installed skipping intermediate versions, you should install the latest version of blitz.bin, and the rest of the settings should be made according to all releases skipped during the update.

Attention

In the case of PostgreSQL DBMS, you should also check the current resources.zip file to see what new DDL scripts have appeared in it, and execute them if such changes do not exist in the current database scheme.

5.23 -> 5.26#

  1. If the PostgreSQL database is used, apply the script: 023-5.26.0.sql.

  2. Install blitz-5.26.bin.

  3. In the configuration file, add attributes for permissions blitz_acpi_sys_users, blitz_acpi_sys_users_chg, blitz_api_user, blitz_api_user_chg to the attrs parameter. An example of adding attributes for the blitz_api_user permission is shown below.

    "attrs" : [
    "sub",
    "family_name",
    "company",
    "given_name"],
"client-level" : false,
"deprecated" : false,
"descriptions" : {
    "default" : "Получение атрибутов"
},
"enabled" : true,
"names" : {
    "default" : "blitz_api_user"
},
"sysname" : "blitz_api_user"
},

5.22.5 -> 5.23#

  1. If the PostgreSQL database is used, apply the script: 022-5.23.0.sql.

  2. Install JDK 11 on Blitz Identity Provider servers. Find out the current JAVA_HOME value.

  3. Specify the new value of the JAVA_HOME parameter in the /etc/default/blitz-* configuration files.

  4. Install blitz-5.23.0.bin.

  5. If configured, migrate names to the new format in the blitz.prod.local.idp.internal-store-jdbc.pool section:

    • max_total_conn -> maxTotalConn,

    • max_idle_conn -> maxIdleConn,

    • min_idle_conn -> minIdleConn,

    • max_wait_conn_ms -> maxWaitConnMs.

    In the same section, add advanced parameters to configure the connection pool.

    Example of the block after editing:

    "internal-store-jdbc" : {
     "pool" : {
         "maxIdleConn" : 10,
         "maxTotalConn" : 20,
         "maxWaitConnMs" : 30000,
         "minIdleConn" : 7,
         "testOnBorrow" : false,
         "testOnCreate" : false,
         "testOnReturn" : false,
         "testWhileIdle" : true,
         "timeBetweenEvictionRunsMillis" : 30000,
         "validationQuery" : ""
     }
}

  6. Enable the following new features as needed:

    • Require second-factor validation during access recovery only if at least one method from the list of additional validation methods is enabled for the user (Need additional validation -> Require if available).

    • Add the ability to register a user in an external identity provider when logging in through that provider.

    • Determine whether information about linked external accounts of users will be displayed in the Admin console and User profiles. You can do so in the console, by using a Java procedure, or via API.

    • In the RADIUS request processing procedure add functions that allow for selecting a login confirmation method and displaying a brief instruction on confirmation methods.

    • Configure the interval with which the system reads the Couchbase Server cluster global configuration.

5.21.1 -> 5.22.5#

  1. Install blitz-5.22.5.bin.

  2. Enable the following new features as needed:

    • Configure logging in via email.

    • Select an account storage used for logging in via SMS.

    • Disable memorizing a user login for future log-ins.

    • Enable a session reset in the login procedure.

    • Handle custom errors in the login procedure.

    • Configure application tags and analyze them in the login procedure.

    • Customize a logo and CSS layout of the User Profile.

5.20.0 -> 5.21.0 (5.21.1)#

  1. If the PostgreSQL database is used, apply the script: 021-5.21.0.sql.

  2. Install blitz-5.21.0.bin.

  3. If necessary, use a new feature: configure access to network services over the RADIUS protocol.

  4. The new version changes issuer (the default identity provider identifier), as well as the OpenID Connect Discovery service URL:

    • In previous versions, issuer was equal to the domain value, where domain is the system external domain name. Now issuer is formed as domain/context, where context is the URL path where Blitz Identity Provider is running.

    • In previous versions, the OIDC Discovery service was located at https://<issuer>/<context>/oauth/.well-known/openid-configuration. Now the address is formed as https://<issuer>/.well-known/openid-configuration.

    With that said, after the update is installed, the OIDC Discovery service will automatically move to https://<domain>/<context>/.well-known/openid-configuration.

    The system will continue to work due to the redirect from the old address to the new one, enforced for backward compatibility. In this situation, you can select one of the following ways:

    1. Without changing the application settings, explicitly specify the issuer value in the blitz.prod.local.idp.net section of the /usr/share/identityblitz/blitz-config/blitz.conf configuration file as the part before /.well-known/openid-configuration. This will help avoid unnecessary redirects when the system is running.

      Attention

      The solution is not recommended in the long term.

      "net" : {
   "domain" : "demo.idblitz.ru",
   "issuer" : "demo.idblitz.ru/blitz/oauth",
   ...
},
...

    2. Recommended Bring the settings of your system and connected applications into compliance with the new rules by specifying the value of the OIDC Discovery address as https://<domain>/<context>/.well-known/openid-configuration.

5.18.0 -> 5.20.0#

  1. If the PostgreSQL database is used, apply the script: 020-5.20.0.sql.

  2. Install blitz-5.20.0.bin.

  3. If necessary, customize new authentication methods:

  4. If necessary, use new customization features using Java programming:

5.16.2 -> 5.18.0#

  1. In case of using PostgreSQL database, apply scripts:

    1. 018-5.17.0.sql

    2. 019-5.18.0.sql

  2. In the blitz.conf configuration file, find the blitz.prod.local.idp.provisioning.recovery settings block. Apply the following changes:

    1. Rename the security-question setting into system-security-questions.

    2. Create the factor2 block. Copy and paste the methods section with its entire content into it. Remove the original methods section.

    3. In the factor2 block, set "mode" :  "by_user_required_factor".

    Example of the block after editing#
    "recovery" : {
    "dropInactivityLock" : true,
    "factor2" : {
        "methods" : [
            "email",
            "sms",
            "totp"
        ],
        "mode" : "by_user_required_factor"
    },
    "recovery-contacts" : [
        "phone_number",
        "email"
    ],
    "search-attrs" : [
        "email",
        "phone_number"
    ],
    "system-security-questions" : {
        "attrs" : [
            "family_name"
        ]
    }
}

  3. Install blitz-5.18.0.bin.

5.15.x -> 5.16.x#

  1. In the nginx settings, block access to the /blitz/metrics addresses from external networks:

    location /blitz/metrics {
    return 404;
}

  2. If you use special bundle for applications via lang-variant (lang-variant optional field in the application settings), you need to register all language options in the blitz. conf -> lang-variant -> lang.

    Example:

    "lang": {
    "ignore-browser": false,
    "lang-variants": ["12345", "12346"], // this field
    "languages": ["ru","en"],
    "portal-lang-cookie": {
        "domain": ".identityblitz.ru",
        "name": "portal_lang"
    }
}

  3. Install new blitz.bin.

  4. If necessary, configure gathering performance metrics in Prometheus via direct access to /blitz/metrics at internal addresses of application servers.

  5. If necessary, configure the storage of application settings in separate files.

5.14.0 -> 5.15.x#

  1. In case of using PostgreSQL database, apply scripts:

    1. 017-5.15.0.sql

  2. Install new blitz.bin.

5.11.x -> 5.14.0#

  1. In case of using PostgreSQL database, apply scripts:

    1. 015-5.12.0.sql,

    2. 016-5.13.0.sql

  2. Install new blitz.bin.

  3. In the “Appearance” section, check that a unique name is set for all templates in the “Template name” field. If there are several templates with the same name, rename them.

  4. For each configured external identity provider in the new block “User selection” fill in the values of the settings “User’s name” and “User ID”. Filling example:

    • The username is ${given_name-} ${family_name-}

    • The user ID is ${email&maskInMiddle(4,8)}

    Configuration is used during the user bind process when the user first logs in through the external identity provider. Based on the customization, the user is shown a card of Blitz Identity Provider account found for binding that matches the external Identity Provider account.

  5. Verify login functions through external identity providers, if the appearance of the login binding screens is compromised, then adjust the appearance themes used.

  6. Adjust the settings in the console.conf configuration file:

    1. If login/password login to the admin console is used, add the roleClaim setting to console.conf with an empty value:

    Example:

    {
"login" : {
    "fp" : {

    ...
    "subjectClaim" : "sub",
    "roleClaim" : "",
    ...
    },
    "mode" : "credentials"
}
}

    1. If the SSO login function to the admin console is used, add the roleClaim setting to the login.fp block in console.conf. As a value, specify the name of the attribute from id_token in which the administrator role is passed (common role names: root, security, ysadmin, app_admin, ui_admin, support, are taken from the credentials settings file from roles.name). Configure the external IDP to pass an attribute with a role. The attribute can be text (String) - then one role is passed, or an array of strings (ArrayOfString), then multiple roles can be passed.

    Example:

    {
"login" : {
    "fp" : {

    ...
    "subjectClaim" : "sub",
    "roleClaim" : "SOME_CLAIM_NAME",
    ...
    },
    "mode" : "sso"
}
}

    From the “Administrators” menu of the console, you can remove those admin users who log in only through the external SSO logon.

5.10.0 -> 5.11.x#

  1. If using PostgreSQL database, apply the 000-service-tasks.sql, 013-tasks.sql, 014-sec_ch_ua.sql scripts.

  2. Check for non-standard lines in custom_messages. If the $[device.mkey&dic(dics.devices)] function is used in the lines with the texts of letters, replace it with $[device.mkey&dic(dics.devices,os.ver)].

  3. Install new blitz.bin.

  4. In the play.conf file, adjust the memcached connection settings - add operationTimeout, timeoutExceptionthreshold, maxReconnectDelay:

    • operationTimeout - time to wait for memcached request execution in ms;

    • timeoutExceptionThreshold - the number of attempts to execute the request, after which the node is considered unavailable;

    • maxReconectDelay - the interval between attempts to establish a connection to the node in seconds.

    Example configuration file with added settings with recommended values:

    "memcached" : {
"operationTimeout" : 1000,
"timeoutExceptionThreshold" : 1,
"maxReconnectDelay" : 10,
"servers" : [
    …
]
}

  5. In case of using PostgreSQL DBMS, if necessary, switch task processing from RabbitMQ broker to jdbc broker ( if RabbitMQ is not used for anything else and you want to abandon its further use). It is recommended to use the jdbc broker only in environments with low load.

    To configure the use of the jdbc broker is required:

    • Check that the stores settings block in the blitz.conf file has the default-type setting set to jdbc:

    "stores" : {
"default-type" : "jdbc"
},

    • In the blitz.conf file in the tasks block, adjust the broker settings as follows:

    "tasks" : {
"broker-type" : "task-store",
"executionRules" : [
    {
    "maxAttempts" : 2,
    "queue" : "blitz-tasks",
    "redeliveryDelayInSec" : 60
    }
],
"queues" : [
    {
    "dequeueBatchSize" : 10,
    "dequeuePeriodInSec" : 30,
    "executorPoolSize" : 5,
    "name" : "blitz-tasks"
    }
]
}

    • To the server running task processing, add the startup parameter akka.coordinated-shutdown.phases.service-stop.timeout to a value of 30s:

    Dakka.coordinated-shutdown.phases.service-stop.timeout=30s