Class ServiceIdentities

java.lang.Object

com.kingsrook.qqq.backend.core.serviceidentity.ServiceIdentities

public final class ServiceIdentities
extends Object

Run background work as a service principal (docs/SERVICE-IDENTITY.md).

 ServiceIdentities.run("scheduler", () -> ...);                    // as the principal
 ServiceIdentities.runOnBehalfOf("scheduler", userId, () -> ...);  // as the user, via the principal
 

The instance's authentication module supplies the session: OAuth2 obtains a real access token and builds a bearer session; local modules mint a QServiceSession with the principal's declared local permissions. A missing, unconfigured or refused principal throws - there is never a fallback to the system user. Call per unit of work (a report, a delivery, a chunk), so the work always holds a fresh session.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CLIENT_CHANNEL
static final String	PRINCIPAL_ID_PREFIX
static final String	SCHEDULER	//////////////////////////////////////////////////////////////////////////
static final String	VALUE_ON_BEHALF_OF
static final String	VALUE_PRINCIPAL

Method Summary

Modifier and Type	Method	Description
static String	attributionName(QSession session)	Audit/log name: service:{name}, or {user} via service:{name}; null for other sessions.
static <T> T	call(String principalName, UnsafeSupplier<T,? extends Exception> body)	Run work as the principal and return its result.
static boolean	isDeclared(QInstance qInstance, String principalName)	Whether the instance declares this principal (callers keep their previous behavior when it does not, so single-node defaults are unchanged).
static boolean	isMintedServiceSession(QSession session)	Whether this is a principal's own session minted in this JVM (an OAuth2 service bearer session or a local QServiceSession) - as opposed to a request's bearer token or a hand-made session.
static boolean	isSessionValid(QInstance qInstance, QAuthenticationModuleInterface module, QSession session)	Whether a session is valid for the module - the single place service and delegated sessions are judged (ActionHelper.validateSession): - a delegated session is valid while its parent is; - a QServiceSession only when the module mints local principals and this JVM minted it (never under OAuth2 or Auth0); - anything else is up to the module, unchanged.
static String	principalNameFromId(String principalId)	The principal name from a principal id (service:{name}), or null.
static String	principalOf(QSession session)	The principal a session runs as (service or delegated), or null.
static void	run(String principalName, UnsafeVoidVoidMethod<? extends Exception> body)	Run work as the principal; the caller's context is restored afterwards.
static void	runOnBehalfOf(String principalName, String userId, UnsafeVoidVoidMethod<? extends Exception> body)	Run work on behalf of a user, via the principal.
static QSession	session(QInstance qInstance, String principalName)	A fresh session for the principal.
static QSession	session(String principalName)	A fresh session for the principal, in the current instance.
static QSession	sessionOnBehalfOf(QInstance qInstance, String principalName, String userId)	A session for work the principal does on behalf of a user: the user's CURRENT access (rebuilt by the authentication module now, so a removed or deactivated user fails) - by default exactly that access (owner decision 2026-10-16, D2 amended), or intersected with the principal's when the principal is declared INTERSECT_WITH_PRINCIPAL - attributed to the principal and the user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PRINCIPAL_ID_PREFIX

public static final String PRINCIPAL_ID_PREFIX

See Also:

• Constant Field Values

VALUE_PRINCIPAL

public static final String VALUE_PRINCIPAL

See Also:

• Constant Field Values

VALUE_ON_BEHALF_OF

public static final String VALUE_ON_BEHALF_OF

See Also:

• Constant Field Values

CLIENT_CHANNEL

public static final String CLIENT_CHANNEL

See Also:

• Constant Field Values

SCHEDULER

public static final String SCHEDULER

//////////////////////////////////////////////////////////////////////////

See Also:

• Constant Field Values

Method Details

isDeclared

public static boolean isDeclared(QInstance qInstance,
 String principalName)

Whether the instance declares this principal (callers keep their previous behavior when it does not, so single-node defaults are unchanged).

principalNameFromId

public static String principalNameFromId(String principalId)

The principal name from a principal id (service:{name}), or null.

session

public static QSession session(String principalName)
                        throws QException

A fresh session for the principal, in the current instance.

Throws:

QException

session

public static QSession session(QInstance qInstance,
 String principalName)
                        throws QException

A fresh session for the principal.

Throws:

QException

run

public static void run(String principalName,
 UnsafeVoidVoidMethod<? extends Exception> body)
                throws QException

Run work as the principal; the caller's context is restored afterwards.

Throws:

QException

call

public static <T> T call(String principalName,
 UnsafeSupplier<T,? extends Exception> body)
                  throws QException

Run work as the principal and return its result.

Throws:

QException

sessionOnBehalfOf

public static QSession sessionOnBehalfOf(QInstance qInstance,
 String principalName,
 String userId)
                                  throws QException

A session for work the principal does on behalf of a user: the user's CURRENT access (rebuilt by the authentication module now, so a removed or deactivated user fails) - by default exactly that access (owner decision 2026-10-16, D2 amended), or intersected with the principal's when the principal is declared INTERSECT_WITH_PRINCIPAL - attributed to the principal and the user. Valid only while the principal's own session is.

Throws:

QException

runOnBehalfOf

public static void runOnBehalfOf(String principalName,
 String userId,
 UnsafeVoidVoidMethod<? extends Exception> body)
                          throws QException

Run work on behalf of a user, via the principal.

Throws:

QException

isSessionValid

public static boolean isSessionValid(QInstance qInstance,
 QAuthenticationModuleInterface module,
 QSession session)

Whether a session is valid for the module - the single place service and delegated sessions are judged (ActionHelper.validateSession): - a delegated session is valid while its parent is; - a QServiceSession only when the module mints local principals and this JVM minted it (never under OAuth2 or Auth0); - anything else is up to the module, unchanged.

isMintedServiceSession

public static boolean isMintedServiceSession(QSession session)

Whether this is a principal's own session minted in this JVM (an OAuth2 service bearer session or a local QServiceSession) - as opposed to a request's bearer token or a hand-made session. Delegated sessions are not.

principalOf

public static String principalOf(QSession session)

The principal a session runs as (service or delegated), or null.

attributionName

public static String attributionName(QSession session)

Audit/log name: service:{name}, or {user} via service:{name}; null for other sessions.