# Using Security with .properties File

Quarkus provides support for properties file-based authentication intended for development and testing purposes. It is not recommended to use this authentication in production as, at present, only plain-text and MD5 hashed passwords are used, and properties files are generally too limited.

Add the following to your build file:

pom.xml

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-elytron-security-properties-file</artifactId>
    </dependency>

build.gradle

    implementation("io.quarkus:quarkus-elytron-security-properties-file")

## Configuration

The elytron-security-properties-file extension currently supports two different realms for storing authentication and authorization information. Both support storage of this information in properties files.

The following sections detail the specific configuration properties.

| Basic authentication must be explicitly enabled with `quarkus.http.auth.basic=true`, if more than one authentication mechanism is used.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property | Type | Default
--- | --- | ---
`quarkus.security.users.embedded.plain-text` If the properties are stored in plain text. If this is false (the default) then it is expected that the passwords are of the form HEX( MD5( username ":" realm ":" password ) ) Environment variable: `QUARKUS_SECURITY_USERS_EMBEDDED_PLAIN_TEXT` | boolean | `false`
`quarkus.security.users.embedded.algorithm` Determine which algorithm to use. This property is ignored if `plainText` is true. Environment variable: `QUARKUS_SECURITY_USERS_EMBEDDED_ALGORITHM` | `digest-md5`, `digest-sha`, `digest-sha-256`, `digest-sha-384`, `digest-sha-512`, `digest-sha-512-256` | `digest-md5`
`quarkus.security.users.embedded.users."users"` The realm users user1=password\nuser2=password2…​ mapping. See Embedded Users. Environment variable: `QUARKUS_SECURITY_USERS_EMBEDDED_USERS__USERS_` | Map<String,String> | `none`
`quarkus.security.users.embedded.roles."roles"` The realm roles user1=role1,role2,…​\nuser2=role1,role2,…​ mapping See Embedded Roles. Environment variable: `QUARKUS_SECURITY_USERS_EMBEDDED_ROLES__ROLES_` | Map<String,String> | `none`
Property Files Realm Configuration | Type | Default
`quarkus.security.users.file.realm-name` The realm name. This is used when generating a hashed password Environment variable: `QUARKUS_SECURITY_USERS_FILE_REALM_NAME` | string | `Quarkus`
`quarkus.security.users.file.enabled` Determine whether security via the file realm is enabled. Environment variable: `QUARKUS_SECURITY_USERS_FILE_ENABLED` | boolean | `false`
`quarkus.security.users.file.plain-text` If the properties are stored in plain text. If this is false (the default) then it is expected that the passwords are of the form HEX( MD5( username ":" realm ":" password ) ) Environment variable: `QUARKUS_SECURITY_USERS_FILE_PLAIN_TEXT` | boolean | `false`
`quarkus.security.users.file.users` Classpath resource name of properties file containing user to password mappings. See Users.properties. Environment variable: `QUARKUS_SECURITY_USERS_FILE_USERS` | string | `users.properties`
`quarkus.security.users.file.roles` Classpath resource name of properties file containing user to role mappings. See Roles.properties. Environment variable: `QUARKUS_SECURITY_USERS_FILE_ROLES` | string | `roles.properties`
Embedded Realm Configuration | Type | Default
`quarkus.security.users.embedded.realm-name` The realm name. This is used when generating a hashed password Environment variable: `QUARKUS_SECURITY_USERS_EMBEDDED_REALM_NAME` | string | `Quarkus`
`quarkus.security.users.embedded.enabled` Determine whether security via the embedded realm is enabled. Environment variable: `QUARKUS_SECURITY_USERS_EMBEDDED_ENABLED` | boolean | `false`

### Properties Files Realm Configuration

The properties files realm supports the mapping of users to passwords and users to roles with a combination of properties files. They are configured with properties starting with `quarkus.security.users.file`.

Example of the `application.properties` file section for property files realm

    quarkus.security.users.file.enabled=true
    quarkus.security.users.file.users=test-users.properties
    quarkus.security.users.file.roles=test-roles.properties
    quarkus.security.users.file.realm-name=MyRealm
    quarkus.security.users.file.plain-text=true

#### Users.properties

The `quarkus.security.users.file.users` configuration property specifies a classpath resource which is a properties file with a user-to-password mapping, one per line.

The following Example of `test-users.properties` illustrates the format:

Example of `test-users.properties`

    scott=jb0ss (1)
    jdoe=p4ssw0rd (2)
    stuart=test
    noadmin=n0Adm1n

1 | User `scott` has password defined as `jb0ss`
2 | User `jdoe` has password defined as `p4ssw0rd`

This file has usernames and passwords stored in plain text, which is not recommended. If plain text is set to false (or omitted) in the config, then passwords must be stored in the form `MD5 ( username : realm : password )`. This can be generated for the first example above by running the command `echo -n scott:MyRealm:jb0ss | md5` from the command line.

#### Roles.properties

Example of `test-roles.properties`

    scott=Admin,admin,Tester,user (1)
    jdoe=NoRolesUser (2)
    stuart=admin,user (3)
    noadmin=user

1 | User `scott` has been assigned the roles `Admin`, `admin`, `Tester` and `user`
2 | User `jdoe` has been assigned the role `NoRolesUser`
3 | User `stuart` has been assigned the roles `admin` and `user`.

### Embedded Realm Configuration

The embedded realm also supports the mapping of users to passwords and users to roles. It uses the main `application.properties` Quarkus configuration file to embed this information. They are configured with properties starting with `quarkus.security.users.embedded`.

The following is an example application.properties file section illustrating the embedded realm configuration:

Example of the `application.properties` file section for embedded realm

    quarkus.security.users.embedded.enabled=true
    quarkus.security.users.embedded.plain-text=true
    quarkus.security.users.embedded.users.scott=jb0ss
    quarkus.security.users.embedded.users.stuart=test
    quarkus.security.users.embedded.users.jdoe=p4ssw0rd
    quarkus.security.users.embedded.users.noadmin=n0Adm1n
    quarkus.security.users.embedded.roles.scott=Admin,admin,Tester,user
    quarkus.security.users.embedded.roles.stuart=admin,user
    quarkus.security.users.embedded.roles.jdoe=NoRolesUser
    quarkus.security.users.embedded.roles.noadmin=user

As with the first example, this file has usernames and passwords stored in plain text, which is not recommended. If plain text is set to false (or omitted) in the config, then passwords must be stored in the form `MD5 ( username : realm : password )`. This can be generated for the first example above by running the command `echo -n scott:MyRealm:jb0ss | md5` from the command line.

#### Embedded Users

The user to password mappings are specified in the `application.properties` file by properties keys of the form `quarkus.security.users.embedded.users.<user>=<password>`. The following Example of passwords illustrates the syntax with 4 user-to-password mappings:

Example of passwords

      1
    2
    3
    4

      quarkus.security.users.embedded.users.scott=jb0ss (1)
    quarkus.security.users.embedded.users.stuart=test (2)
    quarkus.security.users.embedded.users.jdoe=p4ssw0rd
    quarkus.security.users.embedded.users.noadmin=n0Adm1n

1 | User `scott` has password `jb0ss`
2 | User `stuart` has password `test`

#### Embedded Roles

The user to role mappings are specified in the `application.properties` file by properties keys of the form `quarkus.security.users.embedded.roles.<user>=role1[,role2[,role3[,…​]]]`. The following Example of roles illustrates the syntax with 4 user-to-role mappings:

Example of roles

      1
    2
    3
    4

      quarkus.security.users.embedded.roles.scott=Admin,admin,Tester,user (1)
    quarkus.security.users.embedded.roles.stuart=admin,user (2)
    quarkus.security.users.embedded.roles.jdoe=NoRolesUser
    quarkus.security.users.embedded.roles.noadmin=user

1 | User `scott` has roles `Admin`, `admin`, `Tester`, and `user`
2 | User `stuart` has roles `admin` and `user`

## References

- Quarkus Security overview