Package se.curity.identityserver.sdk.service

Interface AccountManager

public interface AccountManager
An AccountManager can be used to control user accounts.

It supports creating, updating and retrieving accounts.

It may also support registration and associating devices with user accounts.

Since:
2.1.0

  • Method Details

    • getId

      String getId()
      Gets the ID of this account manager as named in configuration.
      Returns:
      The name/ID of this account manager
      Since:
      3.0.0

    • supportsRegistration

      default boolean supportsRegistration()
      Whether or not this AccountManager supports registration of new accounts.

      If this method returns false, it's an error to call the createAccount(AccountAttributes) method.

      Returns:
      true if registration is supported, false otherwise.

    • isSetPasswordAfterActivation

      default boolean isSetPasswordAfterActivation()

    • useUsernameAsEmail

      default boolean useUsernameAsEmail()
      Whether or not the username of the account should be considered the primary email.
      Returns:
      true if the username should be used as the primary email address; false otherwise.
      Since:
      4.0.0

    • initializeActivation

      ActivationResult initializeActivation(AccountAttributes accountAttributes, Map<String,Object> model)
      Start an activation flow.

      This method triggers an activation flow that in many cases is out of band. The result will indicate if the activation is pending (out of band) or is done immediately.

      The model will be available in the template used to send the activation message. There are a few special meaning keys that need to be used in the model depending on the context used. If the Account Manager is used in an EventListener or in a non-authentication context, the model must contain the template to use. This is done by setting the path to the template on the `template` keyword.

      The other parameter needed in the model is the activation URL `_activationUrl`. If used in a standalone environment this url is not derived by the system. It should be the full URL to the path of the Authenticator that will resolve the activation. This depends on the type of activation. But for html-form authenticator with id htmlAuth1 used for activation the two parameters would look like this: 

        
     model.put("template", "authenticator/html-form/email/verify-account/email");
     model.put("locale": "sv-SE");
     model.put("_activationUrl": "https://example.com/authn/anonymous/htmlAuth1/activate");

      Thirdly, the locale can be overridden by adding the "locale" to the model as well. This is useful in contexts where the user's locale is not part of any request and must be given explicitly.

      Parameters:
      accountAttributes - The account to activate
      model - A map of model parameters that will be passed to the Activator for usage in the transport such as in the body of an Email or SMS
      Returns:
      a result containing the current state of the activation

    • activateAccount

      ActivationResult activateAccount(String token)
      Returns an ActivationResult indicating the status of the activation.

      This method is called as the second step in an activation flow, typically out of band. The process has the following flow:

      1. initializeActivation is called when the user creates an account.
      2. activateAccount is called when the user confirms the account, typically by clicking an email link or if an administrator performs a task that activate the account.
      Parameters:
      token - the token representing the account to activate
      Returns:
      an ActivationResult with the status of the activation

    • getByUserName

      @Nullable @Nullable AccountAttributes getByUserName(String userName)
      Get a user account by userName.
      Parameters:
      userName - of the account
      Returns:
      the account if it exists, null otherwise.

    • getByEmail

      @Nullable @Nullable AccountAttributes getByEmail(String email)
      Get a user account by email address.
      Parameters:
      email - email address of the account
      Returns:
      the account if it exists, null otherwise.

    • getByPhone

      @Nullable @Nullable AccountAttributes getByPhone(String phone)
      Get a user account by phone number.
      Parameters:
      phone - phone number of the account
      Returns:
      the account if it exists, null otherwise.

    • createAccount

      void createAccount(AccountAttributes account)
      Create a new account.
      Parameters:
      account - to be created

    • deleteAccount

      void deleteAccount(AccountAttributes account)
      Delete a user account.
      Parameters:
      account - to be deleted
      Since:
      4.0.0

    • updateAccount

      boolean updateAccount(AccountAttributes account)
      Update the given account.
      Parameters:
      account - to be updated
      Returns:
      true if the update succeeded, false otherwise.

    • ensureNonDuplicateAccount

      Optional<ErrorMessage> ensureNonDuplicateAccount(@Nullable String userName, @Nullable String primaryEmail)
      Given (optionally) an email address and a username, determine (using either or neither of those) whether the user account exists or not.

      Implementors might require at least one of the parameters to be non-null, but that is not required.

      Parameters:
      userName - optional userName
      primaryEmail - optional primaryEmail
      Returns:
      empty if the account is unique, an error otherwise.

    • getDevicesByUserName

      Collection<Device> getDevicesByUserName(String userName)
      Get all devices for the account with the given userName.
      Parameters:
      userName - the userName of the account
      Returns:
      all devices for the account

    • addDeviceForUser

      void addDeviceForUser(String username, String deviceId, @Nullable String deviceAlias, @Nullable String deviceNumber, @Nullable String formFactor, @Nullable String type, @Nullable Instant expiresAt)
      Add a device for a user account.
      Parameters:
      username - of the account
      deviceId - ID of the device (given by the device itself)
      deviceAlias - alias for the device
      deviceNumber - a device number
      formFactor - the form-factor for this device
      type - type of device
      expiresAt - when the device usage should expire
      Throws:
      ExternalServiceException - if there's an error adding the device

    • addDeviceForUser

      void addDeviceForUser(String username, DeviceAttributes attributes)
      Add a device for a user account.
      Parameters:
      username - of the account
      attributes - of the device which will be created and subsequently added to the user account

    • deleteDevice

      void deleteDevice(AccountAttributes account, Device device)
      Delete a device linked to an account.
      Parameters:
      account - of the device to be deleted
      device - device to be deleted
      Throws:
      ExternalServiceException - if there's an error adding the device
      Since:
      4.0.0

    • link

      void link(SubjectAttributes localSubject, AccountDomain foreignDomain, SubjectAttributes foreignSubject, boolean overwriteExistingLink) throws LinkConflictException, AccountNotFoundException
      Link the linkee (foreignSubject in foreignDomain) to the linker (localSubject). This requires the linker to be present in the current AccountManager.

      A lookup for an account matching the provided localSubject will be performed.

      Parameters:
      localSubject - The local subject is of an account that must belong to this account manager
      foreignDomain - The foreign is the domain that does NOT belong to this manager
      foreignSubject - The subject that should be linked to the local account of this manager
      overwriteExistingLink - Set to true if existing links matching foreign subject and -domain should be overwritten
      Throws:
      LinkConflictException - if a link to foreignSubject in foreignDomain already exists and overwriteExistingLink is false
      AccountNotFoundException - if no account could be found for localSubject and none should be auto-created
      Since:
      3.0.0

    • link

      void link(AccountAttributes localAccount, AccountDomain foreignDomain, SubjectAttributes foreignSubject, boolean overwriteExistingLink) throws LinkConflictException
      Link the linkee (foreignSubject in foreignDomain) to the linker (localAccount). This requires the linker to be present in the current AccountManager.

      Note: No verification will be performed that localAccount exists in the current AccountManager.

      Parameters:
      localAccount - The local account must belong to this account manager
      foreignDomain - The foreign is the domain that does NOT belong to this manager
      foreignSubject - The subject that should be linked to the local account of this manager
      overwriteExistingLink - Set to true if existing links matching foreign subject and -domain should be overwritten
      Throws:
      LinkConflictException - if a link to foreignSubject in foreignDomain already exists and overwriteExistingLink is false
      Since:
      3.0.0

    • resolveLink

      @Nullable @Nullable AccountAttributes resolveLink(AccountDomain foreignDomain, SubjectAttributes foreignSubject)
      Resolves a link given a foreign domain and ID.
      Parameters:
      foreignDomain - The domain of the linked account, like "facebook"
      foreignSubject - The ID of the account in the foreign domain
      Returns:
      The attributes the local account, or null if no link could be resolved
      Since:
      3.0.0

    • listLinks

      Collection<LinkedAccount> listLinks(SubjectAttributes localSubject) throws AccountNotFoundException
      Lists all links belonging to a local subject.
      Parameters:
      localSubject - The subject (username) of the local account
      Returns:
      A collection of linked accounts, or empty if none were found
      Throws:
      AccountNotFoundException - if the localSubject is not found in the accounts
      Since:
      3.0.0

    • listLinks

      Collection<LinkedAccount> listLinks(AccountAttributes localAccount)
      Lists all links belonging to a local account (which should be globally unique).
      Parameters:
      localAccount - The account attributes (ID) of the local account
      Returns:
      A collection of linked accounts, or empty if none were found
      Since:
      3.0.0

    • deleteLink

      boolean deleteLink(AccountAttributes localAccount, AccountDomain foreignDomain, SubjectAttributes foreignSubject)
      Deletes a specific link from the given account.
      Parameters:
      localAccount - The account attributes (ID) of the local account
      foreignDomain - The domain of the linked account, like "facebook"
      foreignSubject - The subject of the account in the foreign domain
      Returns:
      true if a link was found and deleted, false if not found
      Since:
      3.0.0

    • deleteLinks

      int deleteLinks(AccountAttributes localAccount)
      Deletes all linked accounts attached to a local account.
      Parameters:
      localAccount - The account attributes (ID) of the local account
      Returns:
      The number of links deleted by this operation
      Since:
      3.0.0