Connecting attribute storages#

Types of storage#

As user attribute storages Blitz Identity Provider allows you to use:

  1. External (connected) storage. This can be:

    • LDAP repository - this can be any server that supports the LDAP (389 Directory Server, OpenLDAP, FreeIPA, etc.), as well as Microsoft Active Directory or Samba4;

    • other storage that requires special REST services to be developed to connect to Blitz Identity Provider.

  2. Internal Storage. All user attributes are stored in the Blitz Identity Provider database. If Couchbase Server is used as a DBMS, Blitz Identity Provider database can be used to store a small number of accounts. If PostgreSQL is used as a DBMS, any number of accounts can be stored.

Blitz Identity Provider requires configuring at least one storage and configuring attributes to work correctly. By default, an internal configured storage and a number of attributes added.

Note

Each user account is stored in one specific storage. Blitz Identity Provider allows you to configure and connect multiple storages, but it is recommended that you use one primary storage for operation. Use of a second storage should be decided based on the applicable data model. For example, the connected corporate Active Directory can store data of the organization’s employees, and an additional LDAP storage can store data of specially registered “external” users (employees of partner organizations, freelancers, etc.).

To select and configure the storage to be used, you must first configure the attributes in the Data sources in Attribute storages section. The internal storage is configured by default. To add an external storage, click the Add new storage button, then specify the type of the external storage and configure the parameters of interaction with it. The created storages are disabled after creation - you should enable them using the toggle switch in the Attribute storages section.

../_images/storage_en.png

If you do not use an internal storage, you can delete it. To do this, go to the properties of the corresponding external storage and click the Delete button.

Using multiple storages can solve the problem of users’ logging records stored in different LDAP directories or in different branches of the same directory. For example, as a result of a merger between two companies, you can connect two directories to Blitz Identity Provider and provide user logins without configuring trust or building a meta-directory.

../_images/add_store_en.jpg

Connecting storage via LDAP#

If you are using an LDAP storage deployed in your organization as the source of user accounts, you must use the Data sources section of the admin console and perform the following steps to configure it:

  • add a new storage, specify the following data:

    • type of storage to be added - select LDAP;

    • storage address;

    • port;

    • check the Use SSL box if a secure connection should be used.

  • configure the LDAP-storage by configuring the following parameters:

    • storage description (optional);

    • whether the storage is to be used only for reading data or whether it is possible to write to it;

    • whether SSL connection should be used;

    • whether DNS-calls balancing to the LDAP-storage is needed - to do this press the DNS-balances button and set the parameters Domain name, Port, Use SSL, Mode of operation, Cache storage time, ms;

      Note

      During DNS balancing, Blitz Identity Provider queries the DNS server for all connection addresses by the specified LDAP directory domain name. If more than one address is registered in DNS, then depending on the selected mode of operation Blitz Identity Provider establishes connection to the first available server (FAILOVER mode of operation), to a random server (RANDOM mode of operation) or to each server in turn (ROUND_ROBIN mode of operation). The list of servers received from DNS is stored in Blitz Identity Provider cache for the time specified in the Cache storage time, ms setting.

    • connection pool settings;

  • specify the login and password of the user on behalf of whom the work with LDAP storage will be performed (this user must have the rights to read and write data), as well as the base DN - the partition of the directory with user accounts;

    Note

    It is acceptable to specify a user with read-only privileges if the storage is used only for reading.

  • specify search settings - search depth and maximum number of returned accounts (this affects the number of users displayed in the Users section of the admin console).

../_images/ldap_en.jpg

You can further customize attribute matching rules and specify partitioning rules and attribute value conversion rules. This allows you to:

  • give a system attribute a different name than its name in the LDAP directory. For example, if an attribute is specified as sn in the LDAP directory, but you want to use it as family_name in Blitz Identity Provider, select the attribute family_name and specify n as its name in LDAP. An example of this configuration is shown in the figure below;

  • use special rules for writing attributes to a given LDAP directory. For example, if you want to store a cell phone in the format +7(999)1234567 into an LDAP directory without brackets, then set a partitioning rule ^\+7\(([0-9]{3})\)([0-9]{7})$ and a conversion rule +7${1-}${2-} for the entry.

  • use special rules for reading attributes from a given LDAP directory. For example, if an attribute with a cell phone number is specified in the +79991234567 format in the LDAP directory, and Blitz Identity Provider uses the +7(999)1234567 format, you can use the ^\+7([0-9]{3})([0-9]{7})$ and the +7(${1-})${2-} conversion rule to read from the directory.

../_images/attr_matching_en.png

If an attribute created earlier is not supposed to be stored in this storage, you can delete the attribute using the delete button. In this case, the value of the deleted attribute will be stored in Blitz Identity Provider database instead of in the external storage to be connected when creating/editing an account.

If you plan to use the account lockout feature, you must remove the attribute defined in the Data sources section as a lockout attribute from the attribute matching rules table.

If Blitz Identity Provider is used to register users, and the entry is written to this directory, you should specify the parameters for creating new users - the DN of the parent container within which the users will be created, and the system attributes related to the specifics of the storage***.

Note

For example, objectclass, which defines the type of LDAP account to be created. For Microsoft Active Directory, objectclass must have the format Array of string and the value is top,person.

../_images/attrs_ldap_en.png

Connecting to storage via REST#

If an external database (not LDAP storage) is used as the source of user accounts, a connector must be developed to connect to it. The connector provides reading (or changing) the necessary data from the database and provides the data in the correct format as REST services to Blitz Identity Provider.

To configure interaction with REST services, perform the following steps:

  • add a new storage, specifying the type of storage to be added - REST;

  • specify storage description (optional);

  • specify whether the storage is used only for reading data or whether it is possible to write to it;

  • specify the maximum number of records returned by the search;

  • specify the list of attributes available using REST services;

  • specify the URLs of the following services:

    • service for user search;

    • service for receiving user data;

    • verification service for user login and password;

    • service for changing user password;

    • service for adding a new user;

    • service for changing user data;

    • service for deleting user.

The screenshot of the page with settings of connection to the storage using REST services is presented below.

../_images/rest_store_en.png

The following subsections describe the requirements for developing REST services that provide the necessary Blitz Identity Provider access to the accounts storage.

Service for receiving user data#

In some cases Blitz Identity Provider requests data of a particular user. The service for obtaining user data should process requests using the GET method, in which the id attribute - the internal user identifier in the connected database - is specified in the URL. When specifying the URL of this service in the admin console, you must use a substitution string for the user identifier - ${id}, for example:

https://idstore.identityblitz.com/users/${id}

If the user is found, the service should respond 200 OK and return user data in JSON format in UTF-8 encoding. If the user is not found: 400 Bad Request, error code USER_NOT_FOUND in text/plain; charset=utf-8 format.

Request example:

GET /users/ID123 HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

An example of a response if the user is found:

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:28:59 GMT
Content-Type: application/json; charset=utf-8

{
  "id": "ID123",
  "attrs": {
    "sub": "BIP123",
    "given_name": "Ivan",
    "family_name": "Ivanov",
    "email": "ivanov@test.org",
    "phone_number": "+79991234567"
  }
}

Answer for the case when the user is not found:

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:28:59 GMT
Content-Type: text/plain; charset=utf-8

USER_NOT_FOUND

Verification service for user login and password#

Verification service for user login and password must process POST requests, body should contain the following parameters (in the application/x-www-form-urlencoded):

  • id - internal identifier of the user in the connected database;

  • password – password.

If successful, the service should return a 200 OK response.

If the service cannot authenticate, it should return 400 Bad Request with one of the following errors:

  • INVALID_CREDENTIALS - incorrect user login or password;

  • UNWILLING_TO_PERFORM - user is locked;

  • INAPPROPRIATE_AUTHENTICATION - user cannot be authenticated by password;

  • PASSWORD_EXPIRED - user’s password is expired.

Request example:

POST /users/bind HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

id=ivanov&password=12345678

Response example (successful login and/or password):

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:38:53 GMT
Content-Type: application/json; charset=utf-8

Response example (wrong login and/or password):

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:38:53 GMT
Content-Type: text/plain; charset=utf-8

INVALID_CREDENTIALS

Service for changing user password#

Service for changing user login and password must process POST` requests, body should contain the following parameters (in the ``application/x-www-form-urlencoded):

  • id - user identifier, obtained from the result of the user’s password;

  • old_password - old password;

  • new_password – new password.

If successful, the service should return a 200 OK response.

In case of error, the service should return 400 Bad Request with one of the following errors:

  • INVALID_CREDENTIALS - user with the given ID and password is not found;

  • UNWILLING_TO_PERFORM - user is locked;

  • CONSTRAINT_VIOLATION - new password does not correspond to the security policy.

The other errors returned should be similar to the procedure to verify the login and password.

Request example:

POST /users/changePassword HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

id=ivanov&old_password=12345678&new_password=0987654321

Response example:

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:43:23 GMT
Content-Type: text/plain; charset=utf-8

CONSTRAINT_VIOLATION

Service for adding a new user#

Service for adding a new user must process PUT requests, body should contain the following parameters (in the application/json format):

  • password - user’s password (optional);

  • attrs - user’s attributes.

If successful, the service should return the user’s data in JSON format in UTF-8 encoding.

If the password doesn’t meet the security policy, the service should return 400 Bad Request with CONSTRAINT_VIOLATION error.

If such a user already exists, the service should return 400 Bad Request with error USER_ALREADY_EXISTS and note that the user with this identifier already exists.

Request example:

PUT /users HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

{
    "password":"********",
    "attrs": {
            "sub": "ivanov@test.org",
            "email": "ivanov@test.org"
    }
}

Response example (user created):

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:28:53 GMT
Content-Type: application/json; charset=utf-8

{
    "id": "ID678",
    "attrs": {
        "sub": "ivanov@test.org",
        "email": "ivanov@test.org"
    }
}

Response example (account is already registered):

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:43:23 GMT
Content-Type: text/plain; charset=utf-8

USER_ALREADY_EXISTS:ivanov@test.org

Service for changing user data#

The service of changing user data should process requests using the POST method, the id attribute - the internal identifier of the user in the connected database - should be specified in the URL of the called service. When specifying the URL of this service in the admin console, you must use a substitution string for the user identifier - ${id}, for example:

http://idstore.identityblitz.com/users/${id}

The body of the data change request contains the following parameters (in application/json format):

  • password - the new value of the user’s password (if the password is not sent, it must not change);

  • replaced - new values of the user’s attributes to be replaced or added;

  • deleted - list of names of attributes to be deleted.

If successful, the service should return the user’s data in JSON format in UTF-8 encoding.

If new password doesn’t meet the security policy, the service should return 400 Bad Request with CONSTRAINT_VIOLATION error.

If such a user does not exist, the service should return 400 Bad Request with error USER_NOT_FOUND.

Request example:

POST /users/ID123 HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

{
    "replaced": {
        "email": "ivanov@domain.org"
    },
    "deleted": ["family_name"],
    "password": "########"
}

Response example:

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:38:53 GMT
Content-Type: application/json; charset=utf-8

{
    "id": "ID123",
    "attrs": {
        "sub": "BIP123",
        "given_name": "Ivan",
        "email": "ivanov@domain.org"
    }
}

Service for deleting user#

The service of user account deletion should process requests using the DELETE method, the id attribute - the internal user identifier in the connected database - should be specified in the URL of the called service. When specifying the URL of this service it is necessary to use the substitution string for the user identifier - ${id}, for example:

http://idstore.identityblitz.com/users/${id}

If successful, the service must return the response 200 OK.

If a user does not exist, the service should return 400 Bad Request with error USER_NOT_FOUND.

Request example:

DELETE /users/ID123 HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

Response example:

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:28:53 GMT
Content-Type: application/json; charset=utf-8

Configuring internal storage#

If you are using Blitz Identity Provider database as the source of your user accounts, you must take the following steps:

  • add a new storage - specify the type of BUILT-IN storage to be added;

  • specify the storage ID;

  • provide a description of the storage;

  • define whether the storage is read-only or not;

  • specify the maximum number of accounts returned in search.

../_images/09_en.PNG

Note

If PostgreSQL is used as the DBMS, any number of accounts can be stored. If Couchbase Server is used as the DBMS, the internal storage can be used to store a small number of accounts.