Securegrid API 1.0.0

API for Securegrid addons

    The API used to develop Securegrid addons.
    Contains javadocs inside the zip file.

    Sources of all 1st party addons can be downloaded (Look on my profile page under resources, when you download and addon its a ZIP - a source + the compiled JAR) and viewed, which i suggest in order to better understand how to create addons

    Your addon will have 3 main classes, the first main class, which extends SCGridExtension, the class that handles registration with your service which has to extend SCRegistrationService and the class that handles authentication with your service which has to extend SCAuthenticationService

    path to the main class has to be provided in a addon.yml file with the key main inside your jar

    first extend the SCGridExtension and override onEnable()
    inside onenable create a list of authors (can be empty) of type List<String>
    then create a SCRegistryPair as such:
    Code (Text):
    SCRegistryPair pair = SCRegistry.getRegistry.register(this, "Addon_Name", "1.0", authors, "myaddon");
    You'll then use the SCRegistryPair to create a new SCStorage object
    and using the storage.addToMessages(String key, String value) add messages for the next 4 keys: add, remove, disable, enable, if those are not present Securegrid will disable your service, you can also add: add_hover, remove_hover, disable_hover, enable_hover to add tooltips to those messages

    After that you'll use:
    Code (Text):
    SCRegistry.getRegistry.registerServices(SCRegistryPair, SCRegistrationService, SCAuthenticationService);
    to register your Registration and Authentication Services

    in the method register you do anything you need to prepare registration such as adding objects to collections and such, and calling
    Code (Text):
    requestChatInputRegistration(SCRegistryPair, UUID playersUUID, Integer numberOfStep);
    , you'd generally want at least one step to verify the credential before linking it to a player in the database

    inside method isRegistered you should implement a check that checks if the player has data linked with your service, example:
    Code (Text):
        public boolean isRegistered(UUID uuid) {
            return storage.getFromPlayerData(uuid, "id") != null;
    inside method cancelled, you should remove any cached data linked to the player, for example if you store some of their input in order to register them you should remove that data when this function is called. example:
    Code (Text):
        public void cancelled(UUID uuid) {
            if (registrationCache.containsKey(uuid)) {
    inside method remove, you should remove any data associated with the player from your API (for example remove an Authy user from the Authy application), note that access to player's data is still possible inside this method, and will be removed by the main plugin, so do not modify any data inside the database with this method

    In the method getDefaultPlayerData you should return a SCDefaultPlayerDataObject which containt: SCRegistryPair, UUID of the player which is passed to you in the method, a Bson Document, which has to containt all keys that you want to modify, access or compare to in the future, if those keys have any default values, you should provide them inside the Document, if not just set the value to null, and a List<String> called hashKeys, in which you should put and keys, values of which you want hashed, please note that when you modify a value (SCStroage.modifyPlayerData) that is inside the hashKeys, that value will be hashed by the plugin, when you compare (SCStorage.compareToPlayerData) to a hashed value, you need to provide the non-hashed value you are comparing to, as hashing is all handled by the plugin itself, trying to access a value (SCStorage.getFromPlayerData) which is hashed by the plugin will return null

    in handleRegistrationStepBeforeInput, you generally only send the correct chat message based on what registration step the player is using SCPlayer.sendMessage

    handleRegistrationStepAfterInput is used to verify if the input is valid based on the step and return a boolean indicating that, in the last step (if it succeds) you generally want to use SCStorage.modifyPlayerData to add any data you need later to verify their credentials or send them approval requests, you should send a message to the player telling them why something failed (if it did), however do not send any messages when true is retruned

    NOTE: Step numbers are provided starting from 0, so if your addon registeres 4 steps, the steps passed wil be 0, 1, 2 & 3

    Authentication service has 2 methods called authenticationRequested,
    one only passes the UUID of the player, while the other one also passes an input

    inside autenticationRequested(UUID player) you'd want to send the player any approval requests, for example this is the methods that calls the OneTouch reuqest inside the authy addon, and cache data linked to them to prevent approving an older request granting access, inside this, you should call sendAuthenticationResponse(UUID player, SCAuthenticationResponse response)

    In this ethod your free to pool for a result, as the async task responsible for it will be cancelled when player successfully authenticated, authentication was cancelled or the task will expire when the login timeout is reached

    SCAuthenticationResponse has 3 values, APPROVED - which indicates that authentication was approved, DENIED - which indicates that the authentication was explicitly denied, and issued the command set in the config, which (mostly likely) bans the player and EXPIRED which does nothing

    inside authenticationRequested(UUID player, String input), you should verify the input that the player passed, this are the things that are entered in chat such as TOTP codes (example: 524342) or Yubikey OTP codes, here you just return boolean value indicating if that key is valid, do not send any messages to the player and please silence any exceptions that indicate invalid inputs, because that is likely to happen (when for example when one enters a Yubikey OTP code that is 20+ characters long, that obvilously won't be accepted well by a function that is expecting a 6 digit number in form of a string)

    in authenticationCancelled you should just remove any cached data that is required to authenticate the player, this is only ever called when the player leaves the server before they authenticated

    getLoginOptionMessages should return a list of messages that tell the player how to authenticate with your service for example: Enter your TOTP code into chat or Approve the request sent to your phone