This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Configuring a JDBC User Store
JDBC user store manager is configured with org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager
user store manager class. By default, the WSO2 product database contains user store tables. When you configure a RDBMS (JDBC) user store, you can use internal user store tables or you can use an external database as a user store. If you going to use default user store tables, see User Management Related Tables section.
Before you begin!
Please read following topics:
- Read Configuring User Stores to get a high-level understanding of the user stores available in WSO2 Identity Server (WSO2 IS).
- If you want to configure a primary user store, you need to follow the steps given in Configuring the Primary User Store.
- If you want to configure a secondary user store, you need to follow the steps given in Configuring Secondary User Stores.
In this page, you can find following details related to configuring a JDBC user store:
Properties used in JDBC userstore manager
Following are the properties used in JDBC user store manager:
Property Name | Display Name | Description |
---|---|---|
DomainName | DomainName | Unique name to identify the user store. This should only be configured for secondary user stores. |
url | Connection URL | Connection URL to the database which can include additional connection parameters as well Sample values: jdbc:mysql://localhost:3306/wso2is |
userName | Connection Name | The username used to connect to database and perform various operations. This user does not have to be an administrator in the database or have an administrator role in the WSO2 product that you are using, but this user MUST have privileges to do required operation. |
password | Connection Password | Password for the ConnectionName user. |
driverName | Driver Name | JDBC driver name which used to connect to the database. This driver should be available in the <PRODUCT_HOME>/repository/components/lib folder. |
Disabled | Disabled | This is to deactivate the user store. If you need to temporarily deactivate a user store, you can use this option. If you disable the user store from the disable option, it also will set this parameter. (Default: false) Possible values: true: Disable user store temporarily. |
ReadOnly | Read-Only | Indicates whether user store operates in the read-only mode or not. Possible values: true: Operates in read-only mode false: Operates in read-write mode |
ReadGroups | ReadGroups | When WriteGroups is set to false, it Indicates whether groups should be read from the user store. If this is disabled by setting it to false, none of the groups in the user store can be read, and the following group configurations are NOT mandatory: GroupSearchBase, GroupNameListFilter, or GroupNameAttribute. Possible values: true: Read groups from user store false: Do not read groups from user store |
WriteGroups | WriteGroups | Indicates whether groups should be written to the user store. Possible values: true : Write groups to user store false : Do not write groups to user store, so only internal roles can be created. Depending on the value of ReadGroups property, it will read existing groups from user store or not |
UsernameJavaRegEx | Username RegEx (Java) | The regular expression used by the back-end components for username validation. By default, strings with non-empty characters have a length of 3 to 30 are allowed. You can provide ranges of alphabets, numbers and also ranges of ASCII values in the RegEx properties. Default: [a-zA-Z0-9._-|//]{3,30}$ |
UsernameJavaScriptRegEx | Username RegEx (Javascript) | The regular expression used by the front-end components for username validation. Default: ^[\S]{3,30}$ |
UsernameJavaRegExViolationErrorMsg | Username RegEx Violation Error Message | Error message when the Username is not matched with UsernameJavaRegEx |
PasswordJavaRegEx | Password RegEx (Java) | The regular expression used by the back-end components for password validation. By default, strings with non-empty characters have a length of 5 to 30 are allowed. You can provide ranges of alphabets, numbers and also ranges of ASCII values in the RegEx properties. Default: ^[\S]{5,30}$ |
PasswordJavaScriptRegEx | Password RegEx (Javascript) | The regular expression used by the front-end components for password validation. Default: ^[\S]{5,30}$ |
PasswordJavaRegExViolationErrorMsg | Password RegEx Violation Error Message | Error message when the Password is not matched with passwordJavaRegEx |
RolenameJavaRegEx | Role Name RegEx (Java) | The regular expression used by the back-end components for role name validation. By default, strings with non-empty characters have a length of 3 to 30 are allowed. You can provide ranges of alphabets, numbers and also ranges of ASCII values in the RegEx properties. Default: [a-zA-Z0-9._-|//]{3,30}$ |
RolenameJavaScriptRegEx | Role Name RegEx (Javascript) | The regular expression used by the front-end components for role name validation. Default: ^[\S]{3,30}$ |
CaseInsensitiveUsername | Case Insensitive Username | Indicates whether the user name should be case insensitive or not. |
SCIMEnabled | Enable SCIM | This is to configure whether user store is supported for SCIM provisioning. Possible values: True : User store support for SCIM provisioning. False : User does not store support for SCIM provisioning. |
IsBulkImportSupported | Bulk Import Support | Define whether the userstore support for bulk user import operation |
PasswordHashMethod | Password Hashing Algorithm | Specifies the Password Hashing Algorithm used the hash the password before storing in the user store. If you enter SHA as the value, it is considered as SHA-1. It is always better to configure an algorithm with a higher bit value so that the digest bit size is higher. |
MultiAttributeSeparator | Multiple Attribute Separator | This property is used to define a character to separate multiple attributes. This ensures that it will not appear as part of a claim value. Normally “,” is used to separate multiple attributes, but you can define ",,," or "..." or a similar character sequence Default: “,” |
StoreSaltedPassword | Enable Salted Passwords | Indicates whether to stores the password with salted value Default: true Possible values: false By default WSO2 IS stores the password with a salted value. The recommended way to protect passwords is to use salted password hashing. Once it is salted, the passwords are less vulnerable to dictionary and brute force attacks. Setting this property to false causes passwords to be stored without a salted value. This means that if two users (Bob and Alice) have the same password, it is stored as the same hash value. However, if salted passwords are used, WSO2 IS adds a random value to the password and then generates the hash of the password. Therefore if two users have the same password, they would be stored as different hashed values. This is a more secure method of storing passwords. |
MaxUserNameListLength | Maximum User List Length | Controls the number of users listed in the user store of a WSO2 product. This is useful when you have a large number of users and do not want to list them all. Setting this property to 0 displays all users. (Default: 100) In some user stores, there are policies to limit the number of records that can be returned from a query. By setting the value to 0, it will list the maximum results returned by the user store. If you need to increase this number, you need to set it in the user store level. Eg: Active directory has the MaxPageSize property with the default value of 1000. |
MaxRoleNameListLength | Maximum Role List Length | Controls the number of roles listed in the user store of a WSO2 product. This is useful when you have a large number of roles and do not want to list them all. Setting this property to 0 displays all roles. (Default: 100) In some user stores, there are policies to limit the number of records that can be returned from a query. By setting the value to 0, it will list the maximum results returned by the user store. If you need to increase this number, you need to set it in the user store level. Eg: Active directory has the MaxPageSize property with the default value of 1000. |
UserRolesCacheEnabled | Enable User Role Cache | This is to indicate whether to cache the role list of a user. (Default: true) Possible values: false: Set it to false if the user roles are changed by external means and those changes should be instantly reflected in the Carbon instance. |
TenantManager | Define the tenant manager class specific to each user store type. This is only used in primary user store since its shared among tenants. JDBC : org.wso2.carbon.user.core.tenant.JDBCTenantManager LDAP / AD : org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager | |
CountRetrieverClass | Count Implementation | This defines the user /role count retriever implementation class (Only supported for) Possible values: |
Addition to these properties, you can configure SQL queries that are used in JDBC user store manager and if required can change default queries. Those are not listed under this property section but you can see it in the sample configuration with default queries. If you do not change the default queries, you can remove those from the configuration file since those are defined in the user store manager implementation.
Sample Configuration for JDBC User store manager
Configure Primary user store with datasource
When configuring a JDBC user store as a primary user store, you can use a datasource to configure database connection configurations and point that datasource from user store manager configurations. This is a much cleaner way to configure primary user store with a JDBC user store.
To define a datasource, you can use master-datasources.xml
file, which is stored in <PRODUCT_HOME>/repository/conf/datasources/
directory. For detailed information on setting up databases, see Setting Up the Physical Database, and for information on the purpose of defining datasources and how they are configured for a product, see Managing Datasources.
There are two possible methods for updating datasources:
Shown below is howmaster-datasources.xml
file is configured to connect to the default H2 database in your system. If you have replaced the default database with a new RDBMS, which you are now using as the JDBC users store, you have to update themaster-datasource.xml
file with the relevant information.<datasource> <name>WSO2_CARBON_DB</name> <description>The datasource used for registry and user manager</description> <jndiConfig> <name>jdbc/WSO2CarbonDB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:h2:repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000</url> <username>wso2carbon</username> <password>wso2carbon</password> <driverClassName>org.h2.Driver</driverClassName> <maxActive>50</maxActive> <maxWait>60000</maxWait> <testOnBorrow>true</testOnBorrow> <validationQuery>SELECT 1</validationQuery> <validationInterval>30000</validationInterval> </configuration> </definition> </datasource>
Alternatively, instead of using the
master-datasource.xml
file, you can also create a new XML file with the datasource information of your new RDBMS and store it in the same<PRODUCT_HOME>/repository/conf/datasources/
directory.Now, the datasource configuration and the user store manager configuration in u
ser-mgt.xml
file should be linked together. You can do this by referring the datasource information (typically defined in themaster-datasources.xml
file) from theuser-mgt.xml
file as explained below.
The RDBMS that is used for storing authorization information is configured under the<Configuration>
section in theuser-mgt.xml
file, by adding<Property name="dataSource">
as shown below. The following example refers to the default WSO2CarbonDB datasource.<Configuration> ....... <Property name="dataSource">jdbc/WSO2CarbonDB</Property> </Configuration>
Configuring user store manager no need to set the connection detail. See the following sample configuration.
If you are using the same RDBMS as the user store in your system, this datasource reference would suffice. However, if you have set up a separate RDBMS as the user store, instead of using a common RDBMS for authorization information as well as the user store, you must refer to the datasource configuration from within the User Store Manager configuration in the
user-mgt.xml
file by adding the<Property name="dataSource">
property.
Special requirements
Add relevant JDBC driver to the classpath by copying its JAR file into the <PRODUCT_HOME>/repository/components/lib
directory.
You need to restart the server after doing these changes.