OAuth2 OpenID Authentication in Semaphore 5.6 and Later
- Last Updated: May 13, 2026
- 3 minute read
- Semaphore
- Documentation
Overview
This guide demonstrates how to configure and use Quarkus OpenID Connect (OIDC) Extension to protect the Studio application using Bearer Token Authorization where Bearer Tokens are issued by OpenID Connect and OAuth 2.0 compliant Authorization Servers. Bearer Token Authorization is the process of authorizing HTTP requests based on the existence and validity of a Bearer Token which provides valuable information to determine the subject of the call as well as whether an HTTP resource can be accessed.
Configuration
In order to enable the OpenID Connect Extension (OIDC), make sure the `studio.auth.oidc.enabled` property inside `${studio_dir}/config/studio-authentication.properties` is enabled. This type of authorization has a higher priority than `FORM` authentication. However, this setting doesn’t affect the UI login page. To change it, the `${studio_dir}/config/deployment-setup.json` file must be updated as follows (in case of Okta authentication):
{
"cloud": false,
"oauth": [
{ "provider": "Okta",
"buttonText": "Login with Okta",
"buttonColor": "#3080B0",
"buttonIconUrl": "data:image/svg+xml,%3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' fill='white' viewBox='0 0 400 134.7' %3E%3Cpath d='M50.3,33.8C22.5,33.8,0,56.3,0,84.1s22.5,50.3,50.3,50.3s50.3-22.5,50.3-50.3S78.1,33.8,50.3,33.8z M50.3,109.3c-13.9,0-25.2-11.3-25.2-25.2s11.3-25.2,25.2-25.2s25.2,11.3,25.2,25.2S64.2,109.3,50.3,109.3z'/%3E%3Cpath d='M138.7,101c0-4,4.8-5.9,7.6-3.1c12.6,12.8,33.4,34.8,33.5,34.9c0.3,0.3,0.6,0.8,1.8,1.2 c0.5,0.2,1.3,0.2,2.2,0.2l22.7,0c4.1,0,5.3-4.7,3.4-7.1l-37.6-38.5l-2-2c-4.3-5.1-3.8-7.1,1.1-12.3L201.2,41c1.9-2.4,0.7-7-3.5-7 h-20.6c-0.8,0-1.4,0-2,0.2c-1.2,0.4-1.7,0.8-2,1.2c-0.1,0.1-16.6,17.9-26.8,28.8c-2.8,3-7.8,1-7.8-3.1l0-57.1c0-2.9-2.4-4-4.3-4 h-16.8c-2.9,0-4.3,1.9-4.3,3.6v126.6c0,2.9,2.4,3.7,4.4,3.7h16.8c2.6,0,4.3-1.9,4.3-3.8v-1.3V101z'/%3E%3Cpath d='M275.9,129.6l-1.8-16.8c-0.2-2.3-2.4-3.9-4.7-3.5c-1.3,0.2-2.6,0.3-3.9,0.3c-13.4,0-24.3-10.5-25.1-23.8 c0-0.4,0-0.9,0-1.4V63.8c0-2.7,2-4.9,4.7-4.9l22.5,0c1.6,0,4-1.4,4-4.3V38.7c0-3.1-2-4.7-3.8-4.7h-22.7c-2.6,0-4.7-1.9-4.8-4.5 l0-25.5c0-1.6-1.2-4-4.3-4h-16.7c-2.1,0-4.1,1.3-4.1,3.9c0,0,0,81.5,0,81.9c0.7,27.2,23,48.9,50.3,48.9c2.3,0,4.5-0.2,6.7-0.5 C274.6,133.9,276.2,131.9,275.9,129.6z'/%3E%3Cpath d='M397.1,108.5c-14.2,0-16.4-5.1-16.4-24.2c0-0.1,0-0.1,0-0.2l0-45.9c0-1.6-1.2-4.3-4.4-4.3h-16.8 c-2.1,0-4.4,1.7-4.4,4.3l0,2.1c-7.3-4.2-15.8-6.6-24.8-6.6c-27.8,0-50.3,22.5-50.3,50.3c0,27.8,22.5,50.3,50.3,50.3 c12.5,0,23.9-4.6,32.7-12.1c4.7,7.2,12.3,12,24.2,12.1c2,0,12.8,0.4,12.8-4.7v-17.9C400,110.2,398.8,108.5,397.1,108.5z M330.4,109.3c-13.9,0-25.2-11.3-25.2-25.2c0-13.9,11.3-25.2,25.2-25.2c13.9,0,25.2,11.3,25.2,25.2 C355.5,98,344.2,109.3,330.4,109.3z'/%3E%3C/svg%3E%0A" }
]
}
or for Azure
{
"cloud": false,
"oauth": [
{
"provider": "azure",
"buttonText": "Microsoft work account",
"buttonColor": "#0067b8",
"buttonIconUrl": "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='white' viewBox='3 3 20 24'%3E%3Cpath d='M3,12V6.75L9,5.43V11.91L3,12M20,3V11.75L10,11.9V5.21L20,3M3,13L9,13.09V19.9L3,18.75V13M20,13.25V22L10,20.09V13.1L20,13.25Z'%3E%3C/path%3E%3C/svg%3E"
}
]
}
The OpenID Connect extension exposes many configuration properties all of which you can find here. Sometimes, the configuration might be very complex, technical, and hard to understand. That’s why, the OIDC extension introduced a `quarkus.oidc.provider` configuration property that refers to well-known OIDC and OAuth2 providers (i.e. Github, Google, Microsoft, Facebook, etc.) with some pre-defined settings. The full documentation on how to configure the application against those well-known providers is here.
Okta
Here is the example configuration for Okta provider.
studio.auth.mechanism=OIDC
com.smartlogic.studio.auth.oidc=true
quarkus.oidc.auth-server-url=[[YOUR_SERVER_URL]]
quarkus.oidc.client-id=[[YOUR_CLIENT_ID]]
quarkus.oidc.credentials.secret=[[YOUR_SECRET_VALUE]]
quarkus.oidc.authentication.scopes=openid email profile groups
quarkus.oidc.authentication.redirect-path=/j_oauth_callback
Azure
studio.auth.mechanism=OIDC
quarkus.oidc.provider=microsoft
quarkus.oidc.client-id=[[CLIENT_ID]]
quarkus.oidc.credentials.secret=[[YOUR_SECRET]]
quarkus.oidc.auth-server-url=https://login.microsoftonline.com/[[YOUR MS ONLINE GUID]]/v2.0
quarkus.oidc.authentication.redirect-path=/j_oauth_callback
quarkus.oidc.authentication.restore-path-after-redirect=true
If you want to use something other than the default (upn or preferred_username) from the OAuth server, you can set the property
quarkus.oidc.token.principal-claim
to the name of the returned property that you wish to use.
To have the session automatically extend beyond the original lifetime of the generated token, add to the studio-authentication.properties file, the following
quarkus.oidc.token.refresh-expired=true
quarkus.oidc.token.refresh-token-time-skew=5M
quarkus.oidc.authentication.scopes=openid profile email offline_access
quarkus.oidc.token-state-manager.split-tokens=true
If you are using a proxy in front of studio, then to ensure that the correct paths are used in the OAuth redirect, add the following parameters to your studio-authentication.properties file
quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-x-forwarded=true
quarkus.http.proxy.enable-forwarded-host=true
quarkus.http.proxy.enable-forwarded-prefix=true
Upgrading from 5.4.x
If you are upgrading from a Semaphore 5.4.x instance that is configured to use OAuth, then you will have a jaspic-providers.xml that looks like this
<jaspic-providers xmlns="http://tomcat.apache.org/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tomcat.apache.org/xml jaspic-providers.xsd" version="1.0">
<provider name="azure-oauth" className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider" layer="HttpServlet" appContext="Catalina/localhost ">
<property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1" value="com.smartlogic.security.OAuthServerAuthModule"/>
<property name="oauth.clientid" value="<<CLIENT ID>>"/>
<property name="oauth.clientsecret" value="<<CLIENT SECRET>>"/>
<property name="oauth.endpoint" value="<<OAUTH SERVER URL>>/oauth2/v2.0"/>
<property name="oauth.callback_uri" value="<<CALLBACK URL>>"/>
<property name="oauth.callback_relative_path" value="/j_oauth_callback"/>
<property name="oauth.scope" value="openid profile email"/>
<property name="ignore_missing_login_context" value="true"/>
<property name="login_request_param" value="oauth.loginProvider=azure"/>
<property name="default_groups" value="SemaphoreUsers"/>
<property name="oauth.userinfo_uri" value="<<USER INFO URL>>"/>
</provider>
</jaspic-providers>
This can be converted into the Quarkus config using cut-and-paste and the template
studio.auth.mechanism=OIDC
studio.auth.oidc.enabled=true
quarkus.oidc.provider=microsoft
quarkus.oidc.client-id=<<CLIENT ID>>
quarkus.oidc.credentials.secret=<<CLIENT SECRET>>
quarkus.oidc.auth-server-url=<<OAUTH SERVER URL>>/v2.0
quarkus.oidc.authentication.redirect-path=/j_oauth_callback
quarkus.oidc.authentication.restore-path-after-redirect=true
Note, the default group for users now goes into the auth/auth-override.properties file.
Role Mapping
Not all providers return group (role) information by default. This option needs to be manually enabled by adding a customer claim when configuring the authentication server.
Azure
For role assignment, the Azure Active Directory groups assigned to a user are returned on login, however, these are the group IDs, not the names. You can use this to assign Semaphore roles however you must define a custom mapping in the “auth/auth-override.properties” file using the appropriate group (object) ID from the directory, for example:
roles.mapping.110c17b5-5b7d-42cf-9fdf-f34c645899a4=SemaphoreSuperAdministrators