Class AbstractRememberMeManager

java.lang.Object
org.apache.shiro.mgt.AbstractRememberMeManager
All Implemented Interfaces:
RememberMeManager
public abstract class AbstractRememberMeManager extends Object implements RememberMeManager
Abstract implementation of the RememberMeManager interface that handles serialization and encryption of the remembered user identity.

The remembered identity storage location and details are left to subclasses.

Default encryption key

This implementation uses an AesCipherService for strong encryption by default. It also uses a default generated symmetric key to both encrypt and decrypt data. As AES is a symmetric cipher, the same key is used to both encrypt and decrypt data, BUT NOTE:

Because Shiro is an open-source project, if anyone knew that you were using Shiro's default key, they could download/view the source, and with enough effort, reconstruct the key and decode encrypted data at will.

Of course, this key is only really used to encrypt the remembered PrincipalCollection which is typically a user id or username. So if you do not consider that sensitive information, and you think the default key still makes things 'sufficiently difficult', then you can ignore this issue.

However, if you do feel this constitutes sensitive information, it is recommended that you provide your own key via the setCipherKey method to a key known only to your application, guaranteeing that no third party can decrypt your data. You can generate your own key by calling the CipherService's generateNewKey method and using that result as the cipherKey configuration attribute.

Since:
0.9

  • Constructor Details

  • Method Details

    • getSerializer

      public org.apache.shiro.lang.io.Serializer<PrincipalCollection> getSerializer()
      Returns the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

      Unless overridden by the setSerializer(org.apache.shiro.lang.io.Serializer<org.apache.shiro.subject.PrincipalCollection>) method, the default instance is a DefaultSerializer.

      Returns:
      the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

    • setSerializer

      public void setSerializer(org.apache.shiro.lang.io.Serializer<PrincipalCollection> serializer)
      Sets the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

      Unless overridden by this method, the default instance is a DefaultSerializer.

      Parameters:
      serializer - the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

    • getCipherService

      public org.apache.shiro.crypto.cipher.CipherService getCipherService()
      Returns the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.

      Unless overridden by the setCipherService(org.apache.shiro.crypto.cipher.CipherService) method, the default instance is an AesCipherService.

      Returns:
      the Cipher to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data

    • setCipherService

      public void setCipherService(org.apache.shiro.crypto.cipher.CipherService cipherService)
      Sets the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.

      If the CipherService is a symmetric CipherService (using the same key for both encryption and decryption), you should set your key via the setCipherKey(byte[]) method.

      If the CipherService is an asymmetric CipherService (different keys for encryption and decryption, such as public/private key pairs), you should set your encryption and decryption key via the respective setEncryptionCipherKey(byte[]) and setDecryptionCipherKey(byte[]) methods.

      N.B. Unless overridden by this method, the default CipherService instance is an AesCipherService. This RememberMeManager implementation already has a configured symmetric key to use for encryption and decryption, but it is recommended to provide your own for added security. See the class-level JavaDoc for more information and why it might be good to provide your own.

      Parameters:
      cipherService - the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.

    • getEncryptionCipherKey

      public byte[] getEncryptionCipherKey()
      Returns the cipher key to use for encryption operations.
      Returns:
      the cipher key to use for encryption operations.
      See Also:

    • setEncryptionCipherKey

      public void setEncryptionCipherKey(byte[] encryptionCipherKey)
      Sets the encryption key to use for encryption operations.
      Parameters:
      encryptionCipherKey - the encryption key to use for encryption operations.
      See Also:

    • getDecryptionCipherKey

      public byte[] getDecryptionCipherKey()
      Returns the decryption cipher key to use for decryption operations.
      Returns:
      the cipher key to use for decryption operations.
      See Also:

    • setDecryptionCipherKey

      public void setDecryptionCipherKey(byte[] decryptionCipherKey)
      Sets the decryption key to use for decryption operations.
      Parameters:
      decryptionCipherKey - the decryption key to use for decryption operations.
      See Also:

    • getCipherKey

      public byte[] getCipherKey()
      Convenience method that returns the cipher key to use for both encryption and decryption.

      N.B. This method can only be called if the underlying cipherService is a symmetric CipherService which by definition uses the same key for both encryption and decryption. If using an asymmetric CipherService public/private key pair, you cannot use this method, and should instead use the getEncryptionCipherKey() and getDecryptionCipherKey() methods individually.

      The default AesCipherService instance is a symmetric cipher service, so this method can be used if you are using the default.

      Returns:
      the symmetric cipher key used for both encryption and decryption.

    • setCipherKey

      public void setCipherKey(byte[] cipherKey)
      Convenience method that sets the cipher key to use for both encryption and decryption.

      N.B. This method can only be called if the underlying cipherService is a symmetric CipherService?which by definition uses the same key for both encryption and decryption. If using an asymmetric CipherService?(such as a public/private key pair), you cannot use this method, and should instead use the setEncryptionCipherKey(byte[]) and setDecryptionCipherKey(byte[]) methods individually.

      The default AesCipherService instance is a symmetric CipherService, so this method can be used if you are using the default.

      Parameters:
      cipherKey - the symmetric cipher key to use for both encryption and decryption.

    • forgetIdentity

      protected abstract void forgetIdentity(Subject subject)
      Forgets (removes) any remembered identity data for the specified Subject instance.
      Parameters:
      subject - the subject instance for which identity data should be forgotten from the underlying persistence mechanism.

    • isRememberMe

      protected boolean isRememberMe(AuthenticationToken token)
      Determines whether or not remember me services should be performed for the specified token. This method returns true iff:
      1. The token is not null and
      2. The token is an instanceof RememberMeAuthenticationToken and
      3. token.isRememberMe() is true
      Parameters:
      token - the authentication token submitted during the successful authentication attempt.
      Returns:
      true if remember me services should be performed as a result of the successful authentication attempt.

    • onSuccessfulLogin

      public void onSuccessfulLogin(Subject subject, AuthenticationToken token, AuthenticationInfo info)
      Reacts to the successful login attempt by first always forgetting any previously stored identity. Then if the token is a RememberMe token, the associated identity will be remembered for later retrieval during a new user session.
      Specified by:
      onSuccessfulLogin in interface RememberMeManager
      Parameters:
      subject - the subject for which the principals are being remembered.
      token - the token that resulted in a successful authentication attempt.
      info - the authentication info resulting from the successful authentication attempt.

    • rememberIdentity

      public void rememberIdentity(Subject subject, AuthenticationToken token, AuthenticationInfo authcInfo)
      Remembers a subject-unique identity for retrieval later. This implementation first resolves the exact principals to remember. It then remembers the principals by calling rememberIdentity(org.apache.shiro.subject.Subject, org.apache.shiro.subject.PrincipalCollection).

      This implementation ignores the AuthenticationToken argument, but it is available to subclasses if necessary for custom logic.

      Parameters:
      subject - the subject for which the principals are being remembered.
      token - the token that resulted in a successful authentication attempt.
      authcInfo - the authentication info resulting from the successful authentication attempt.

    • getIdentityToRemember

      protected PrincipalCollection getIdentityToRemember(Subject subject, AuthenticationInfo info)
      Returns info.getPrincipals() and ignores the Subject argument.
      Parameters:
      subject - the subject for which the principals are being remembered.
      info - the authentication info resulting from the successful authentication attempt.
      Returns:
      the PrincipalCollection to remember.

    • rememberIdentity

      protected void rememberIdentity(Subject subject, PrincipalCollection accountPrincipals)
      Remembers the specified account principals by first converting them to a byte array and then remembers that byte array.
      Parameters:
      subject - the subject for which the principals are being remembered.
      accountPrincipals - the principals to remember for retrieval later.

    • convertPrincipalsToBytes

      protected byte[] convertPrincipalsToBytes(PrincipalCollection principals)
      Converts the given principal collection the byte array that will be persisted to be 'remembered' later.

      This implementation first serializes the principals to a byte array and then encrypts that byte array.

      Parameters:
      principals - the PrincipalCollection to convert to a byte array
      Returns:
      the representative byte array to be persisted for remember me functionality.

    • rememberSerializedIdentity

      protected abstract void rememberSerializedIdentity(Subject subject, byte[] serialized)
      Persists the identity bytes to a persistent store for retrieval later via the getRememberedSerializedIdentity(SubjectContext) method.
      Parameters:
      subject - the Subject for which the identity is being serialized.
      serialized - the serialized bytes to be persisted.

    • getRememberedPrincipals

      public PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext)
      Implements the interface method by first acquiring the remembered serialized byte array. Then it converts them and returns the re-constituted PrincipalCollection. If no remembered principals could be obtained, null is returned.

      If any exceptions are thrown, the onRememberedPrincipalFailure(RuntimeException, SubjectContext) method is called to allow any necessary post-processing (such as immediately removing any previously remembered values for safety).

      Specified by:
      getRememberedPrincipals in interface RememberMeManager
      Parameters:
      subjectContext - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance.
      Returns:
      the remembered principals or null if none could be acquired.

    • getRememberedSerializedIdentity

      protected abstract byte[] getRememberedSerializedIdentity(SubjectContext subjectContext)
      Based on the given subject context data, retrieves the previously persisted serialized identity, or null if there is no available data. The context map is usually populated by a Subject.Builder implementation. See the SubjectFactory class constants for Shiro's known map keys.
      Parameters:
      subjectContext - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance. To be used to assist with data lookup.
      Returns:
      the previously persisted serialized identity, or null if there is no available data for the Subject.

    • convertBytesToPrincipals

      protected PrincipalCollection convertBytesToPrincipals(byte[] bytes, SubjectContext subjectContext)
      If a cipherService is available, it will be used to first decrypt the byte array. Then the bytes are then deserialized and then returned.
      Parameters:
      bytes - the bytes to decrypt if necessary and then deserialize.
      subjectContext - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance.
      Returns:
      the deserialized and possibly decrypted principals

    • onRememberedPrincipalFailure

      protected PrincipalCollection onRememberedPrincipalFailure(RuntimeException e, SubjectContext context)
      Called when an exception is thrown while trying to retrieve principals. The default implementation logs a warning message and forgets ('unremembers') the problem identity by calling forgetIdentity(context) and then immediately re-throws the exception to allow the calling component to react accordingly.

      This method implementation never returns an object - it always rethrows, but can be overridden by subclasses for custom handling behavior.

      This most commonly would be called when an encryption key is updated and old principals are retrieved that have been encrypted with the previous key.

      Parameters:
      e - the exception that was thrown.
      context - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance.
      Returns:
      nothing - the original RuntimeException is propagated in all cases.

    • encrypt

      protected byte[] encrypt(byte[] serialized)
      Encrypts the byte array by using the configured cipherService.
      Parameters:
      serialized - the serialized object byte array to be encrypted
      Returns:
      an encrypted byte array returned by the configured () cipher.

    • decrypt

      protected byte[] decrypt(byte[] encrypted)
      Decrypts the byte array using the configured cipherService.
      Parameters:
      encrypted - the encrypted byte array to decrypt
      Returns:
      the decrypted byte array returned by the configured () cipher.

    • serialize

      protected byte[] serialize(PrincipalCollection principals)
      Serializes the given principals by serializing them to a byte array by using the serializer's serialize method.
      Parameters:
      principals - the principal collection to serialize to a byte array
      Returns:
      the serialized principal collection in the form of a byte array

    • deserialize

      protected PrincipalCollection deserialize(byte[] serializedIdentity)
      Deserializes the given byte array by using the serializer's deserialize method.
      Parameters:
      serializedIdentity - the previously serialized PrincipalCollection as a byte array
      Returns:
      the deserialized (reconstituted) PrincipalCollection

    • onFailedLogin

      public void onFailedLogin(Subject subject, AuthenticationToken token, AuthenticationException ae)
      Reacts to a failed login by immediately forgetting any previously remembered identity. This is an additional security feature to prevent any remnant identity data from being retained in case the authentication attempt is not being executed by the expected user.
      Specified by:
      onFailedLogin in interface RememberMeManager
      Parameters:
      subject - the subject which executed the failed login attempt
      token - the authentication token resulting in a failed login attempt - ignored by this implementation
      ae - the exception thrown as a result of the failed login attempt - ignored by this implementation

    • onLogout

      public void onLogout(Subject subject)
      Reacts to a subject logging out of the application and immediately forgets any previously stored identity and returns.
      Specified by:
      onLogout in interface RememberMeManager
      Parameters:
      subject - the subject logging out.