LuckPerms Integration

Relevant source files

The following files were used as context for generating this wiki page:

• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/LuckPermsIntegration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/AuthorizedContext.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/Awaiting2FAContext.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
• Plugin/src/main/resources/paper-plugin.yml
• Plugin/src/main/resources/plugin.yml

The LuckPerms integration for NexAuth provides a dynamic permission context system based on a player's authentication status. When the LuckPerms plugin is detected on the server, NexAuth automatically registers custom context calculators. This allows server administrators to create permission rules that apply only when a player is fully authenticated, awaiting 2FA, or not yet logged in, enabling fine-grained control over player capabilities during the authentication process.

This integration is enabled by default if LuckPerms is present on the server. It does not require any specific configuration within NexAuth's config.yml to function.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:310-314, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/LuckPermsIntegration.java

Architecture and Initialization

The integration is managed by the LuckPermsIntegration class. Its lifecycle is tied directly to the main AuthenticNexAuth plugin class.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:312, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/LuckPermsIntegration.java

Initialization Flow

On plugin startup, the AuthenticNexAuth.enable() method checks for the presence of the "luckperms" plugin. If detected, it instantiates LuckPermsIntegration. The constructor of LuckPermsIntegration then retrieves the LuckPerms ContextManager and registers two custom context calculators: AuthorizedContext and Awaiting2FAContext.

The following diagram illustrates the initialization sequence.

Class Structure

The integration consists of a main controller class and two ContextCalculator implementations. AuthenticNexAuth holds a reference to LuckPermsIntegration to manage its lifecycle.

This class diagram shows the relationship between the key components.

Disabling the Integration

When the NexAuth plugin is disabled, it calls the LuckPermsIntegration.disable() method. This method safely unregisters both AuthorizedContext and Awaiting2FAContext from the LuckPerms ContextManager to prevent memory leaks and unexpected behavior.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:828-830, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/LuckPermsIntegration.java:25-29

Provided Contexts

The integration adds two boolean contexts to LuckPerms, which can be used in permission nodes to grant or deny permissions based on the player's current authentication state.

nexauth-authorized

This context tracks whether a player has successfully completed the entire authentication process (including 2FA if required).

Property	Value	Description
Context Key	nexauth-authorized	The key used in LuckPerms permissions.
Possible Values	true / false	A string representation of the boolean state.
Implementation	AuthorizedContext.java	The class responsible for calculating this context.

The value is determined by calling plugin.getAuthorizationProvider().isAuthorized(player).

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/AuthorizedContext.java:19-27

nexauth-awaiting-2fa

This context is active when a player has successfully entered their password but is now required to provide a Two-Factor Authentication (2FA) code.

Property	Value	Description
Context Key	nexauth-awaiting-2fa	The key used in LuckPerms permissions.
Possible Values	true / false	A string representation of the boolean state.
Implementation	Awaiting2FAContext.java	The class responsible for calculating this context.

The value is determined by checking if the player's UUID is present in the awaiting2fa set within the AuthenticAuthorizationProvider.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/integration/luckperms/Awaiting2FAContext.java:19-27

Usage Example

With these contexts, you can define permissions in LuckPerms that are only active under specific conditions.

• Give players access to lobby commands only after they are fully logged in:
  /lp group default permission set essentials.spawn true context:nexauth-authorized=true

• Prevent an unauthenticated player from using any commands except for /login and /register:
  /lp group default permission set -bukkit.command.* true context:nexauth-authorized=false
  (Note: NexAuth's internal command handling already restricts commands, but this adds a layer of security at the permissions level).

• Allow a player to use the /2faconfirm command only when they are prompted for a 2FA code:
  /lp group default permission set nexauth.command.2faconfirm true context:nexauth-awaiting-2fa=true

The following sequence diagram shows how LuckPerms interacts with NexAuth to check a player's context.