Authenticator - Revision history

Craig: Remove pre-4.x version references (4.0.0 is the oldest documented release)

2026-07-31T14:49:47Z

Remove pre-4.x version references (4.0.0 is the oldest documented release)

← Older revision		Revision as of 14:49, 31 July 2026
Line 127:		Line 127:
	'''<code>public boolean supportsRememberMe()</code>'''		'''<code>public boolean supportsRememberMe()</code>'''

	~~from~~ <code>com.carfey.suite.security.remember.Authenticator</code> available ~~as of~~ Obsidian 3.5.0.		From <code>com.carfey.suite.security.remember.Authenticator</code>, available from Obsidian 3.5.0 and '''removed in Obsidian 7.0.0'''.

	This method~~, from~~ <code>com.carfey.suite.security.remember.Authenticator</code>~~, 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.		This method indicated whether the Authenticator supported Obsidian's remember me feature in the Web Admin login. The Remember Me feature and the <code>com.carfey.suite.security.remember.Authenticator</code> interface were removed in Obsidian 7.0.0, so this method is no longer part of the authenticator contract.

	=== Users ===		=== Users ===

Craig at 23:33, 30 July 2026

2026-07-30T23:33:42Z

@@ Line 38: / Line 38: @@
 * 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.

Craig at 23:30, 30 July 2026

2026-07-30T23:30:00Z

← Older revision		Revision as of 23:30, 30 July 2026
Line 1:		Line 1:
	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).		Obsidian ships with four built-in authenticators: native (database), LDAP, OAuth (OIDC), and SAML 2.0. 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 (OIDC SSO) ==

Craig at 19:17, 9 July 2026

2026-07-09T19:17:22Z

← Older revision		Revision as of 19:17, 9 July 2026
Line 1:		Line 1:
	Obsidian ~~includes two authentication providers out~~-~~of-the-box~~: native ~~authentication~~, ~~which is managed in the database~~, and ~~LDAP-supported authentication~~. ~~But you~~ also ~~have~~ the ~~option to implement your own~~ authenticator ~~or even customize our LDAP~~ authenticator. ~~Below you~~'~~ll find directions on how to do both~~. ~~If you are having problems~~ or ~~have some questions~~, ~~feel free~~ to ~~reach out to us either through our Free Live Chat Support link~~ to the ~~left~~, or ~~by [[Contact_Carfey_Software\|contacting us]]~~. ~~Before you get started~~, ~~we recommend you are familiar~~ with the ~~[[Admin_User_Management#User_Rights~~\|~~Roles]] that~~ Obsidian ~~uses~~ for access ~~control~~.		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\|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 ==		== Developing an Authenticator ==

Craig at 18:15, 12 March 2025

2025-03-12T18:15:38Z

← Older revision		Revision as of 18:15, 12 March 2025
Line 6:		Line 6:
	=== Implementation of a Custom Authenticator ===		=== Implementation of a Custom Authenticator ===
	'''<code>com.carfey.suite.security.User authenticate(String username, String pass) throws com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>'''		'''<code>com.carfey.suite.security.User authenticate(String username, String pass) throws com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>'''

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

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

Craig: /* Putting it All Together */

2021-07-31T15:45:28Z

Putting it All Together

@@ Line 120: / Line 120: @@
+}
 </pre>
 == Customizing our LDAP Authenticator ==

Craig: /* Roles */

2021-07-31T15:35:25Z

Roles

← Older revision		Revision as of 15:35, 31 July 2021
Line 34:		Line 34:

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

	When assigning the user's <code>com.carfey.suite.security.Role</code>s, use the constructor <code>public Role(String roleId, String roleName)</code> using the appropriate constant for both the <code>roleId</code> and <code>roleName</code>. Role meanings are defined in [[Admin_User_Management#User_Rights \| User Rights]].		When assigning the user's <code>com.carfey.suite.security.Role</code>s, use the constructor <code>public Role(String roleId, String roleName)</code> using the appropriate constant for both the <code>roleId</code> and <code>roleName</code>. Role meanings are defined in [[Admin_User_Management#User_Rights \| User Rights]].

Craig: /* Specialization points */

2018-10-02T11:25:37Z

Specialization points

← Older revision		Revision as of 11:25, 2 October 2018
Line 141:		Line 141:
	====<code>protected boolean isMemberOfGroup(DirContext authContext, String groupName, String dn) throws NamingException</code>====		====<code>protected boolean isMemberOfGroup(DirContext authContext, String groupName, String dn) throws NamingException</code>====

	Checks the authenticated <code>DirContext</code> for group membership. Used to determine ''Default'' rights to Obsidian, in addition to its defined rights [[Admin_User_Management#User_Rights\|roles]]. Currently queries <code>"uniquemember"</code>,<code>"uniqueMember"</code>,<code>"member"</code>,<code>"roleOccupant"</code> and <code>"~~memberOf~~"</code> attributes for any match on the ''dn''.		Checks the authenticated <code>DirContext</code> for group membership. Used to determine ''Default'' rights to Obsidian, in addition to its defined rights [[Admin_User_Management#User_Rights\|roles]]. Currently queries <code>"uniquemember"</code>,<code>"uniqueMember"</code>,<code>"member"</code>,<code>"roleOccupant"</code>, <code>"memberOf"</code> and <code>"MemberOf"</code> attributes for any match on the ''dn''.

	== Deploying your Authenticator ==		== 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 <code>/WEB-INF/lib</code> directory of either the Obsidian web application directory or WAR file.		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 <code>/WEB-INF/lib</code> directory of either the Obsidian web application directory or WAR file.

Carfey at 00:32, 16 March 2018

2018-03-16T00:32:36Z

← Older revision		Revision as of 00:32, 16 March 2018
Line 142:		Line 142:

	Checks the authenticated <code>DirContext</code> for group membership. Used to determine ''Default'' rights to Obsidian, in addition to its defined rights [[Admin_User_Management#User_Rights\|roles]]. Currently queries <code>"uniquemember"</code>,<code>"uniqueMember"</code>,<code>"member"</code>,<code>"roleOccupant"</code> and <code>"memberOf"</code> attributes for any match on the ''dn''.		Checks the authenticated <code>DirContext</code> for group membership. Used to determine ''Default'' rights to Obsidian, in addition to its defined rights [[Admin_User_Management#User_Rights\|roles]]. Currently queries <code>"uniquemember"</code>,<code>"uniqueMember"</code>,<code>"member"</code>,<code>"roleOccupant"</code> and <code>"memberOf"</code> 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 <code>/WEB-INF/lib</code> directory of either the Obsidian web application directory or WAR file.

Craig: /* Roles */

2016-01-15T16:50:00Z

Roles

← Older revision		Revision as of 16:50, 15 January 2016
Line 36:		Line 36:
	There are convenience constants that you should use in defining your role memberships. They can be found at <code>com.carfey.ops.Constant</code>. The constants are <code>ADMIN_ROLE</code>, <code>WRITE_ROLE</code>, <code>LIMITED_READ_ROLE</code> and <code>API_ROLE</code>. ''Default'' rights are assumed for any authenticated user. Therefore, if someone authenticates that should not have access, throw a <code>com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>.		There are convenience constants that you should use in defining your role memberships. They can be found at <code>com.carfey.ops.Constant</code>. The constants are <code>ADMIN_ROLE</code>, <code>WRITE_ROLE</code>, <code>LIMITED_READ_ROLE</code> and <code>API_ROLE</code>. ''Default'' rights are assumed for any authenticated user. Therefore, if someone authenticates that should not have access, throw a <code>com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>.

	When assigning the user's <code>com.carfey.suite.security.Role</code>s, use the constructor <code>public Role(String roleId, String roleName)</code> using the appropriate constant for both the <code>roleId</code> and <code>roleName</code>.		When assigning the user's <code>com.carfey.suite.security.Role</code>s, use the constructor <code>public Role(String roleId, String roleName)</code> using the appropriate constant for both the <code>roleId</code> and <code>roleName</code>. Role meanings are defined in [[Admin_User_Management#User_Rights \| User Rights]].

	=== Putting it All Together ===		=== Putting it All Together ===