Authenticator

Obsidian ships with three built-in authenticators: native (database), LDAP, and OAuth (OIDC). A custom authenticator can also be implemented by extending the authenticator interface. The active authenticator is selected by the com.carfey.suite.security.Authenticator property in the Obsidian configuration file (com.carfey.properties or YAML equivalent).

OAuthAuthenticator (OIDC SSO)

OAuthAuthenticator enables Single Sign-On via any OIDC-compliant identity provider. It implements OAuth 2.0 Authorization Code + PKCE (S256). Full configuration reference: Advanced Configuration — OAuth / OIDC Authentication Properties.

How browser login works

When OAuthAuthenticator is active, the Obsidian login page shows a single "Sign in with <displayName>" button instead of a username/password form. Clicking the button redirects the user to the identity provider's login page. After successful authentication at the IdP, the browser is redirected back to Obsidian with an authorization code. Obsidian exchanges the code for tokens at the IdP token endpoint and validates the id_token signature, issuer, audience, expiry, and nonce.

No Obsidian database user record is created or required. Identity and roles come entirely from the validated token.

User identity and display

Obsidian uses the sub claim of the id_token as the stable internal user ID (stored in audit logs and session state). The sub claim is IdP-guaranteed unique and is never reassigned. A separate claim.displayName property (default: preferred_username) controls what name appears in the Obsidian UI nav bar. Changing claim.displayName does not affect audit logging.

Roles from IdP groups

After the code exchange, Obsidian reads a configured groups claim from the id_token (or access token, or userinfo endpoint). Each group value is mapped to an Obsidian role via indexed role.<idx>.group / role.<idx>.roleName properties. At least one mapping to the Admin role is required. A user whose groups do not match any mapping authenticates successfully but has no access to role-gated actions (same behavior as a DB/LDAP user with no assigned roles).

Valid Obsidian roles: Admin, API, Write, LimitedRead, Operator, Author, and folder-based roles following the <folder>-(Write|Author|Operator) convention (e.g. Maintenance-Author).

REST API Bearer authentication

REST clients can authenticate to Obsidian's REST API using a signed JWT access token in the Authorization: Bearer <token> header. Obsidian validates the token locally using cached JWKS keys. The userinfo endpoint is not called on the Bearer path. The client must have the API Obsidian role.

Logout modes

Two logout modes are supported:

• local (default) — Obsidian invalidates its own session. The IdP session remains active (useful for SSO environments where other applications share the IdP session).
• rp — RP-initiated logout. Obsidian redirects the browser to the IdP's end_session_endpoint, which terminates the IdP session. Requires the IdP to expose end_session_endpoint in its discovery document.

v1 limitations

• Opaque (non-JWT) access tokens are not supported on the REST/Bearer path.
• No jti replay protection (mitigate with short token lifetimes at the IdP).
• Microsoft Entra multi-tenant apps are not supported.
• No post-login IdP session validity check (mitigate with a short session timeout in web.xml).
• Dynamic role map (dynamicRole.prefix/suffix) requires a server restart when new root job folders are added.
• Installer UI supports up to 10 static group→role pairs; the runtime supports unlimited.

Developing an Authenticator

Obsidian uses any valid implementation of the com.carfey.suite.security.Authenticator or com.carfey.suite.security.remember.Authenticator interface.

Implementation of a Custom Authenticator

com.carfey.suite.security.User authenticate(String username, String pass) throws com.carfey.suite.security.Authenticator.AuthenticationFailedException

As of Obsidian 6.1.1, you may optionally implement REST authentication distinctly. Defaults to standard authentication when not implemented. com.carfey.suite.security.User authenticateREST(String username, String pass) throws com.carfey.suite.security.Authenticator.AuthenticationFailedException

This method authenticates and returns a user with roles defined. Given a user name and a password either return a valid com.carfey.suite.security.User object or throw a com.carfey.suite.security.Authenticator.AuthenticationFailedException.

If authentication is successful, the com.carfey.suite.security.User returned must have all its role memberships defined. This is done using the com.carfey.suite.security.Role class. The assignment of Roles to a User can be done using any of the public constructors/setters or logical combination thereof defined below.

public boolean supportsRememberMe()

from com.carfey.suite.security.remember.Authenticator available as of Obsidian 3.5.0.

This method, from com.carfey.suite.security.remember.Authenticator, indicates whether the Authenticator supports Obsidian's remember me feature available in the Web Admin login. This is primarily used to ensure the remember me feature is not exposed in environments where the user could be disabled, made inactive or otherwise invalidated while allowing a lookup to succeed - as may be the case in directory authentication implementations such as LDAP.

Users

public User(String userId)

public User(String userId, Set<Role> roles, String firstName, String lastName, String email, boolean active*)

public User(String userId, List<Role> roles, String firstName, String lastName, String email, boolean active*)

public void setRoles(Set<Role> roles)

public void setRoles(List<Role> roles)

* Note: If you wish to implement active user enabling/disabling, you must do so in your Authenticator throwing com.carfey.suite.security.Authenticator.AuthenticationFailedException when inactive users attempt to login.

Roles

There are convenience constants that you should use in defining your role memberships. They can be found at com.carfey.ops.Constant. The constants are ADMIN_ROLE, WRITE_ROLE, LIMITED_READ_ROLE and API_ROLE. As of 5.0.0, you can also use OPERATOR_ROLE and AUTHOR_ROLE. Default rights are assumed for any authenticated user. Therefore, if someone authenticates that should not have access, throw a com.carfey.suite.security.Authenticator.AuthenticationFailedException.

When assigning the user's com.carfey.suite.security.Roles, use the constructor public Role(String roleId, String roleName) using the appropriate constant for both the roleId and roleName. Role meanings are defined in User Rights.

Putting it All Together

Finance attempts to log in to Obsidian, gives valid credentials but should not be accessing Obsidian.

import static com.carfey.ops.Constant.*;

import com.carfey.suite.security.Authenticator.AuthenticationFailedException;
import com.carfey.suite.security.Role;
import com.carfey.suite.security.User;


public User authenticate(String username, String pass) throws AuthenticationFailedException {
    //usernameis "financeGuy"
    //pass is "mystrongpass"
    //credentials are valid, but user does not have any rights to Obsidian

    throw new AuthenticationFailedException(String.format("User [%s] is not authorized to use Obsidian Scheduler.", username));
}

Fred logs in using his username fredScheduler and his password badpass. You determine that his password is invalid.

import static com.carfey.ops.Constant.*;

import com.carfey.suite.security.Authenticator.AuthenticationFailedException;
import com.carfey.suite.security.Role;
import com.carfey.suite.security.User;


public User authenticate(String username, String pass) throws AuthenticationFailedException {
    //usernameis "fredScheduler"
    //pass is "badpass"
    //credentials are invalid

    throw new AuthenticationFailedException(String.format("User [%s] could not be authenticated.", username));
}

Fred logs in using his username fredScheduler and his password mystrongpassword. You determine that his password is valid and matches with the user and he has WRITE_ROLE rights.

public User authenticate(String username, String pass) throws AuthenticationFailedException {
    //usernameis "fredScheduler"
    //pass is "mystrongpassword"
    //credentials are valid, he has WRITE_ROLE

    User user = new User(username);
    user.setRoles(Arrays.asList(new Role(WRITE_ROLE, WRITE_ROLE)));
    return user;
}

Tina logs in using her username tinaOperator and her password mystrongpassword. You determine that her password is valid and matches with the user and she has Default rights.

public User authenticate(String username, String pass) throws AuthenticationFailedException {
    //usernameis "tinaOperator"
    //pass is "mystrongpassword"
    //credentials are valid, Tina has default access

    return new User(username);
}

The intern logs in using his username newGuy and his password mystrongpassword. You determine that his password is valid and matches with the user and he has LIMITED_READ_ROLE rights.

public User authenticate(String username, String pass) throws AuthenticationFailedException {
    //usernameis "newGuy"
    //pass is "mystrongpassword"
    //credentials are valid, the intern has LIMITED_READ_ROLE access

    User user = new User(username);
    user.setRoles(Arrays.asList(new Role(LIMITED_READ_ROLE, LIMITED_READ_ROLE)));
    return user;
}

The new hire logs in using her username newHire and her password is i am a new hire. You determine that her password is valid and matches with the user and she has OPERATOR_ROLE rights only for the job folder roots DevOps and FinOps.

private static final String DEV_OPS_OPERATOR = "DevOps-" + OPERATOR_ROLE;
private static final String FIN_OPS_OPERATOR = "FinOps-" + OPERATOR_ROLE;
public User authenticate(String username, String pass) throws AuthenticationFailedException {
    //usernameis "newHire"
    //pass is "i am a new hire"
    //credentials are valid, the new hire has OPERATOR_ROLE access for job folder roots DevOps and FinOps

   User user = new User(username);
   user.setRoles(Arrays.asList(new Role(DEV_OPS_OPERATOR, DEV_OPS_OPERATOR), new Role(FIN_OPS_OPERATOR, FIN_OPS_OPERATOR)));
   return user;
}

Customizing our LDAP Authenticator

com.carfey.suite.security.LdapAuthenticator is Obsidian's LDAP Authentication class that, when combined with its configurability that is documented here, meets most needs. But with the large variety of LDAP servers and potential implementations of dn strings, role and group definition and membership and even authentication methods supported, you may need to tweak its use somewhat. Rather than require you to write your own LDAP Authenticator, we have made efforts to make ours flexible enough to be specialized.

Specialization points

protected void buildUpContextEnvironment(String pass, String dn, Hashtable<String, String> environment)

Stores needed environment attributes for authentication using javax.naming.directory.InitialDirContext.

Currently stores:

Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory"
Context.PROVIDER_URL, {{ldap_url}} 
Context.SECURITY_AUTHENTICATION, "simple" //or overridden securityAuthentication by configuration com.carfey.suite.security.LdapAuthenticator.securityAuthentication 
Context.SECURITY_PRINCIPAL, {{user_dn}} 
Context.SECURITY_CREDENTIALS, {{user_pass}}

protected boolean isMemberOfGroup(DirContext authContext, String groupName, String dn) throws NamingException

Checks the authenticated DirContext for group membership. Used to determine Default rights to Obsidian, in addition to its defined rights roles. Currently queries "uniquemember","uniqueMember","member","roleOccupant", "memberOf" and "MemberOf" attributes for any match on the dn.

Deploying your Authenticator

Once your authenticator class is written, you need to deploy the compiled class and any dependent libraries to your admin web application instances as JAR files. These should be placed under the /WEB-INF/lib directory of either the Obsidian web application directory or WAR file.