Form-based authentication (Quarkus)
- Last Updated: May 13, 2026
- 3 minute read
- Semaphore
- Documentation
Studio, by itself, does not provide an authentication mechanism but rather relies on one configured appropriately in the Quarkus it includes. A good tutorial on Quarkus security and how to configure it can be found at https://quarkus.io/guides/security. Below we provide some sample configuration information that can be used.
Note: The following configuration information is specific to Quarkus and is provided to Progress customers as a courtesy. Progress accepts no responsibility for changes made to this configuration on the part of the Quarkus project.
Static list of users (studio-authentication.properties)
If you want to use a static set of users and groups for your Semaphore installation, you can define them in the file <Installation>/studio/conf/studio-authentication.properties.
For each user create a pair of entries
quarkus.security.users.embedded.users.<<User Name>>=<<Password>>
quarkus.security.users.embedded.roles.<<User Name>>=<<Comma separated list of roles>>
The first entry defines the user and their password. The second lists the roles with which they are associated. So to create a global “God” user with the password “admin”, the following lines should be present:
quarkus.security.users.embedded.users.God=admin
quarkus.security.users.embedded.roles.God=SemaphoreSuperAdministrators,SemaphoreAdministrators,SemaphoreRoots
A more restricted user would be set as:
quarkus.security.users.embedded.users.User=password1
quarkus.security.users.embedded.roles.User=SemaphoreUsers
If the “User Name” contains “.” characters (such as an email address) then enclose it in quotes, such as:
quarkus.security.users.embedded.users."support@marklogic.com"=password1
quarkus.security.users.embedded.roles."support@marklogic.com"=SemaphoreUsers
Once this file has been updated, you should restart the Studio service.
If you are upgrading from an earlier version of Studio, the users present in the file <Installation>/studio/conf/tomcat-users.xml should be recreated here.
Please note, this method of authentication is not recommended for use in production systems. Rather we would recommend using an external authentication/authorization system
If you are not using OIDC authentication (the recommended approach), then in the Studio log file an error will be recorded with the OIDC setup (the module is built in so as to support a wide range of authentication methods). This is harmless and should be ignored
Lightweight Directory Protocol (LDAP)
There was an issue with LDAP with Semaphore v5.6.0. If you need to use it please contact support. If possible we would recommend the use of OAuth2 or using the Semaphore 5.6.1 (or later) release.
If LDAP authentication is available then the Quarkus server behind Semaphore Studio can be configured to use it - their documentation for this is at security-ldap
You will need add the properly configured version of the following to the file <Installation>/studio/conf/studio-authentication.properties
studio.auth.mechanism=LDAP
quarkus.security.ldap.enabled=true
quarkus.security.ldap.dir-context.principal=uid=tool,ou=accounts,o=YourCompany,c=DE
quarkus.security.ldap.dir-context.password=PASSWORD
quarkus.security.ldap.dir-context.url=ldap://ldap.server.local
quarkus.security.ldap.identity-mapping.rdn-identifier=uid
quarkus.security.ldap.identity-mapping.search-base-dn=ou=users,ou=tool,o=YourCompany,c=DE
quarkus.security.ldap.identity-mapping.attribute-mappings."0".from=cn
quarkus.security.ldap.identity-mapping.attribute-mappings."0".to=groups
quarkus.security.ldap.identity-mapping.attribute-mappings."0".filter=(member={1})
quarkus.security.ldap.identity-mapping.attribute-mappings."0".filter-base-dn=ou=roles,ou=tool,o=YourCompany,c=DE
For details of these settings please consult security-ldap#configuration-reference
Note, if you need to present a $ character (for instance as part of a password) it should be repeated $.
Lightweight Directory Protocol over SSL (LDAPS)
In order to use LDAP over SSL (LDAPS) you need to obtain the certificate chain for the Certificate Authority that signed the LDAP server certificate, then import it into the keystore on the Semaphore Studio server by running the following command:
keytool.exe -import -trustcacerts -cacerts -storepass changeit -noprompt -alias ldap -file "path_to_crt"
You will also need to modify the file <Installation>/studio/conf/studio-authentication.properties to update the LDAP server URL
quarkus.security.ldap.dir-context.url=ldaps://ldap.server.local
Microsoft Active Directory
If using Microsoft Active Directory as your LDAP server, you will need to use a slightly modified configuration in the file <Installation>/studio/conf/studio-authentication.properties
studio.auth.mechanism=LDAP
quarkus.seurity.ldap.enabled=true
quarkus.security.ldap.dir-context.principal=CN=Administrator,DC=example,DC=com
quarkus.security.ldap.dir-context.password=PASSWORD
quarkus.security.ldap.dir-context.url=ldap://ad.example.com:389
quarkus.security.ldap.dir-context.referral-mode=follow
quarkus.security.ldap.identity-mapping.search-recursive=true
quarkus.security.ldap.identity-mapping.rdn-identifier=sAMAccountName
quarkus.security.ldap.identity-mapping.search-base-dn=OU=users,DC=example,DC=com
quarkus.security.ldap.identity-mapping.attribute-mappings."0".from=cn
quarkus.security.ldap.identity-mapping.attribute-mappings."0".to=groups
quarkus.security.ldap.identity-mapping.attribute-mappings."0".filter=(member:1.2.840.113556.1.4.1941:={1})
quarkus.security.ldap.identity-mapping.attribute-mappings."0".filter-base-dn=DC=example,DC=com