Using NATIVE authentication

Derby's simplest authentication mechanism is NATIVE authentication.

When you use NATIVE authentication, user names and encrypted passwords are stored in a database. You can specify a dedicated credentials database for this purpose, or you can store the credentials in the same database you use for your application data. The credentials are stored in the SYSUSERS system table of the database.

To specify NATIVE authentication, specify one of the following values for the derby.authentication.provider property:

Working with a credentials database

With NATIVE authentication, a database can become a credentials database in any of the following ways:

When a database becomes a credentials database, the following things happen:

NATIVE authentication and other database properties

When NATIVE authentication is enabled, Derby behaves as if the derby.connection.requireAuthentication and derby.database.sqlAuthorization properties are also set. That is, a user name and password must be specified whenever a user connects to a database, and object owners control access to database objects. See Setting the SQL standard authorization mode for more information, and see NATIVE authentication and SQL authorization example for an example of the use of NATIVE authentication.

For maximum security, the passwords that users specify when they connect to databases have an expiration date that you can modify by using the property derby.authentication.native.passwordLifetimeMillis. The password of the database owner never expires. By default, ordinary user passwords expire after 31 days.

If a password is about to expire, or if the database owner's password is near what would be the expiration date, Derby issues a warning that the password will soon expire (or, in the database owner's case, that the password is stale). By default, the warning is issued if the password is due to expire in one-eighth of the password's lifetime. For example, if the password has a 31-day lifetime, the warning will be issued 3.875 days before the expiration date. You can change this proportion by using the property derby.authentication.native.passwordLifetimeThreshold.

Use the derby.authentication.builtin.algorithm property to change the way passwords are encrypted when they are stored in the SYSUSERS system table. The default algorithm is SHA-256. Two related properties are derby.authentication.builtin.saltLength and derby.authentication.builtin.iterations, which can be used to make the hashed passwords harder for attackers to crack.

Managing users and passwords

To manage users and passwords, Derby provides a group of system procedures:

Converting an existing database to use NATIVE authentication

If you wish to apply NATIVE authentication to a database that was created without it, the procedure is slightly different depending on whether you specify NATIVE:credentialsDB or NATIVE:credentialsDB:LOCAL:

Related concepts
Enabling user authentication
Defining users
External directory service
Programming applications for Derby user authentication
Related reference
List of user authentication properties