Passwords

Changing the password

Method

POST https://login.company.com/blitz/api/v3/users/{instanceId}/pswd

Password change. To find out the value of the instanceId for the user, you must first call the service for getting the user attributes with the GET method.

Required permissions: blitz_api_usec_chg or blitz_api_sys_usec_chg.

Headers

• When changing the password in user mode, you need to transmit headers with the user’s IP address and User-Agent.

• In the scenario of the user changing the password independently in the User Profile, it is possible to reset the user’s sessions. In this case, it may be undesirable for the user to log out of the current device/browser. In order to specify Blitz Identity Provider that a certain device must be saved based on the results of a successful password change (do not log out from it), you need to transfer the IB-CI-UA-ID header with the identifier of the current user device from the application to the password change service call.

  Tip

  The ID of the user’s current device can be obtained from the identification token.

• To send an e-mail in English, specify the Accept-Language: en header (available only in v3).

Request body

• current – the user’s current password (only when changing the password in user mode, it must be transmitted).

• password is the user’s new password (optional parameter). If the parameter is omitted, Blitz Identity Provider will generate a new password on its own.

• resetSessions – if the parameter is not specified or is set to true, then when changing the password, all user sessions will be canceled and the stored devices will be deleted. If you only need to change the password without resetting sessions, then you must explicitly specify the parameter in the value false.

• sendPswdToAttr is the name of the attribute with the phone number to send the password to the user (optional parameter). If the parameter is set, an SMS with a password will be sent to the user’s phone from the specified attribute.

Returns

• In case of a successful call to Blitz Identity Provider - HTTP 204 No Content.

• If the password change failed, an error message is displayed:

  • HTTP 401 Unauthorized in case of an access control error, the access token is incorrect or the user’s current password is incorrect.

  • HTTP 400 Bad Request - the new password does not meet the requirements of the password policy.

Examples

Request

Custom password change mode

POST /blitz/api/v3/users/Mzg…J1/pswd HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)…
Authorization: Bearer wzb…Tw
IB-CI-UA-ID: {SHA256}rVWFmwgRKWeW_flH4CA4yuW7OhKZ32Da94m0kzwWsVs

{
    "current": "QWErty123",
    "password": "P@$$w0rd",
    "resetSessions": false
}

Password change mode by the system

POST /blitz/api/v3/users/Mzg…J1/pswd HTTP/1.1
Content-Type: application/json
Authorization: Bearer qwa…Ez

{
    "password": "P@$$w0rd",
    "resetSessions": true
}

Sending a new password via SMS with automatic password generation

POST /blitz/api/v3/users/Mzg…J1/pswd HTTP/1.1
Content-Type: application/json
Authorization: Bearer qwa…Ez

{
    "sendPswdToAttr": "phone_number"
}

Password change request in English

curl -v --location --request POST 'https://demo.identityblitz.com/blitz/api/v3/users/YnVpbHQtaW46a2dhdnJpbG92QGlkYmxpdHoucnU6MTcxMDU5ODgyODY3MjU0ODg2NA/pswd' \
--header 'Content-Type: application/json' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer ...' \
--data-raw '{"password": "nN2L98Nu1234"}'

Errors

Incorrect current password

{
    "type": "security_error",
    "error": "invalid_credential",
    "desc": "Wrong subject identifier or current password"
}

Incorrect access token

{
    "type": "security_error",
    "error": "bad_access_token",
    "desc": "BEARER_AUTH: CRID does not match"
}

The new password does not comply with the password policy: too short

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "Password's length must be greater than 6",
            "pos": "password",
            "params": {
                "rule": "to_short",
                "low": 6
            }
        }
    ]
}

The new password does not comply with the password policy set in the LDAP directory

{
    "type": "input_error",
    "error": "password_policy_violated",
    "desc": "Failed to update password\n",
    "pos": "password",
    "params": {
        "rule": "id_store"
    }
}

The new password does not comply with the password policy: does not contain the required character groups

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "Password doesn't match enough symbols groups",
            "pos": "password",
            "params": {
                "rule": "not_enough_groups",
                "no_matched_groups": [
                    {
                     "desc": "password.policy.desc.digits",
                     "min_number_symbols": 1
                    },
                    {
                        "desc": "password.policy.desc.capital",
                        "min_number_symbols": 1
                    },
                    {
                        "desc": "password.policy.desc.special",
                        "min_number_symbols": 1
                    }
                ]
            }
        }
    ]
}

The new password does not comply with the password policy: the password was previously used

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "Password found in previous used ones",
            "pos": "password",
            "params": {
                "rule": "in_password_history"
            }
        }
    ]
}

The new password does not comply with the password policy: the new password matches the current one

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "A new password can't be the same as the current",
            "pos": "password",
            "params": {
                "rule": "eq_current"
            }
        }
    ]
}

The new password does not comply with the password policy: in the new password, the insufficient number of characters differs from the previous one

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "There are not enough new characters in a new password",
            "pos": "password",
            "params": {
                "rule": "not_enough_new_chars",
                "minNew": 5
            }
        }
    ]
}

The new password does not comply with the password policy: the password includes an entry from the dictionary of prohibited passwords

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "Password contains a word from the stop dictionary",
            "pos": "password",
            "params": {
                "rule": "in_stop_dic",
                "stop_word": "qwerty"
            }
        }
    ]
}

The new password does not comply with the password policy: the password matches the dictionary password

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "Password found in a password dictionary",
            "pos": "password",
            "params": {
                "rule": "in_password_dic"
            }
        }
    ]
}

The new password does not comply with the password policy: the password was changed earlier than the allowed period

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "password_policy_violated",
            "desc": "Password is too young",
            "pos": "password",
            "params": {
                "rule": "too_young",
                "minAgeInSec": 86400
            }
        }
    ]
}

The passed attribute for sending the password does not exist

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "Wrong mobile attribute 'phone_number_wrong'",
            "pos": "sendPswdToAttr"
        }
    ]
}

The user does not have a phone attribute set to send the password to the phone

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "User not contains mobile attribute 'phone_number'",
            "pos": "sendPswdToAttr"
        }
    ]
}

Changing the password of subordinate account

Method

POST https://login.company.com/blitz/api/v2/users/{subjectId}/password

Changing the password of the managed user account using the master user account. subjectId is the identifier (sub) of the managed account.

Headers

A header with a permission access token named blitz_change_password received by the lead account should be added to the request. The lead user can trigger a change of the subordinary account password only if the previously lead user was given the right to change the password change_password.

Request body

The value attribute with the value of the new password, which must meet the requirements of the configured password policy.

Returns

• If the password is changed successfully, the status is HTTP 200 (OK).

• If there is an error, a description of the error received.

Example

Request

POST /blitz/api/v2/users/c574a512-3704-4576-bc3a-3fe28b636e85/password HTTP/1.1
Authorization: Bearer cNwIX…Tg
Content-Type: application/json

{"value":"QWErty1234"}

Error

{
    "errors": [
        {
            "code": "access_denied",
            "desc": "Not enough rights: change_password",
            "params": {}
        }
    ]
}