Package org.restlet.ext.crypto

Class CookieAuthenticator

  • All Implemented Interfaces:
    Uniform
    public class CookieAuthenticator
extends ChallengeAuthenticator
    Challenge authenticator based on browser cookies. This is useful when the web application requires a finer grained control on the login and logout process and can't rely solely on standard schemes such as ChallengeScheme.HTTP_BASIC.

    Login can be automatically handled by intercepting HTTP POST calls to the getLoginPath() URI. The request entity should contain an HTML form with two fields, the first one named getIdentifierFormName() and the second one named getSecretFormName().

    Logout can be automatically handled as well by intercepting HTTP GET or POST calls to the getLogoutPath() URI.

    After login or logout, the user's browser can be redirected to the URI provided in a query parameter named by getRedirectQueryName().

    When the credentials are missing or stale, the challenge(Response, boolean) method is invoked by the parent class, and its default behavior is to redirect the user's browser to the getLoginFormPath() URI, adding the URI of the target resource as a query parameter of name getRedirectQueryName().

    Note that credentials, both identifier and secret, are stored in a cookie in an encrypted manner. The default encryption algorithm is AES but can be changed with setEncryptAlgorithm(String). It is also strongly recommended to

    • Field Detail

      • cookieName

        private volatile java.lang.String cookieName
        The name of the cookie that stores log info.

      • encryptAlgorithm

        private volatile java.lang.String encryptAlgorithm
        The name of the algorithm used to encrypt the log info cookie value.

      • encryptSecretKey

        private volatile byte[] encryptSecretKey
        The secret key for the algorithm used to encrypt the log info cookie value.

      • identifierFormName

        private volatile java.lang.String identifierFormName
        The name of the HTML login form field containing the identifier.

      • interceptingLogin

        private volatile boolean interceptingLogin
        Indicates if the login requests should be intercepted.

      • interceptingLogout

        private volatile boolean interceptingLogout
        Indicates if the logout requests should be intercepted.

      • loginFormPath

        private volatile java.lang.String loginFormPath
        The URI path of the HTML login form to use to challenge the user.

      • loginPath

        private volatile java.lang.String loginPath
        The login URI path to intercept.

      • logoutPath

        private volatile java.lang.String logoutPath
        The logout URI path to intercept.

      • maxCookieAge

        private volatile int maxCookieAge
        The maximum age of the log info cookie.

      • redirectQueryName

        private volatile java.lang.String redirectQueryName
        The name of the query parameter containing the URI to redirect the browser to after login or logout.

      • secretFormName

        private volatile java.lang.String secretFormName
        The name of the HTML login form field containing the secret.

    • Constructor Detail

      • CookieAuthenticator

        public CookieAuthenticator​(Context context,
                           boolean optional,
                           java.lang.String realm,
                           byte[] encryptSecretKey)
        Constructor. Use the ChallengeScheme.HTTP_COOKIE pseudo-scheme.
        Parameters:
        context - The parent context.
        optional - Indicates if this authenticator is optional so alternative authenticators down the chain can be attempted.
        realm - The name of the security realm.
        encryptSecretKey - The secret key used to encrypt the cookie value.

      • CookieAuthenticator

        public CookieAuthenticator​(Context context,
                           java.lang.String realm,
                           byte[] encryptSecretKey)
        Constructor for mandatory cookie authenticators.
        Parameters:
        context - The parent context.
        realm - The name of the security realm.
        encryptSecretKey - The secret key used to encrypt the cookie value.

    • Method Detail

      • attemptRedirect

        protected void attemptRedirect​(Request request,
                               Response response)
        Attempts to redirect the user's browser to the URI provided in a query parameter named by getRedirectQueryName().
        Parameters:
        request - The current request.
        response - The current response.

      • authenticate

        protected boolean authenticate​(Request request,
                               Response response)
        Restores credentials from the cookie named getCookieName() if available. The usual processing is the followed.
        Overrides:
        authenticate in class ChallengeAuthenticator
        Parameters:
        request - The request sent.
        response - The response to update.
        Returns:
        True if the authentication succeeded.

      • authenticated

        protected int authenticated​(Request request,
                            Response response)
        Sets or updates the credentials cookie.
        Overrides:
        authenticated in class Authenticator
        Parameters:
        request - The request sent.
        response - The response to update.
        Returns:
        The filter continuation code.

      • challenge

        public void challenge​(Response response,
                      boolean stale)
        This method should be overridden to return a login form representation.
        By default, it redirects the user's browser to the getLoginFormPath() URI, adding the URI of the target resource as a query parameter of name getRedirectQueryName().
        In case the getLoginFormPath() is not set, it calls the parent's method.
        Overrides:
        challenge in class ChallengeAuthenticator
        Parameters:
        response - The response to update.
        stale - Indicates if the new challenge is due to a stale response.

      • formatCredentials

        public java.lang.String formatCredentials​(ChallengeResponse challenge)
                                   throws java.security.GeneralSecurityException
        Formats the raws credentials to store in the cookie.
        Parameters:
        challenge - The challenge response to format.
        Returns:
        The raw credentials.
        Throws:
        java.security.GeneralSecurityException

      • getCookieName

        public java.lang.String getCookieName()
        Returns the cookie name to use for the authentication credentials. By default, it is is "Credentials".
        Returns:
        The cookie name to use for the authentication credentials.

      • getCredentialsCookie

        protected CookieSetting getCredentialsCookie​(Request request,
                                             Response response)
        Returns the credentials cookie setting. It first try to find an existing cookie. If necessary, it creates a new one.
        Parameters:
        request - The current request.
        response - The current response.
        Returns:
        The credentials cookie setting.

      • getEncryptAlgorithm

        public java.lang.String getEncryptAlgorithm()
        Returns the name of the algorithm used to encrypt the log info cookie value. By default, it returns "AES".
        Returns:
        The name of the algorithm used to encrypt the log info cookie value.

      • getEncryptSecretKey

        public byte[] getEncryptSecretKey()
        Returns the secret key for the algorithm used to encrypt the log info cookie value.
        Returns:
        The secret key for the algorithm used to encrypt the log info cookie value.

      • getIdentifierFormName

        public java.lang.String getIdentifierFormName()
        Returns the name of the HTML login form field containing the identifier. Returns "login" by default.
        Returns:
        The name of the HTML login form field containing the identifier.

      • getLoginFormPath

        public java.lang.String getLoginFormPath()
        Returns the URI path of the HTML login form to use to challenge the user.
        Returns:
        The URI path of the HTML login form to use to challenge the user.

      • getLoginPath

        public java.lang.String getLoginPath()
        Returns the login URI path to intercept.
        Returns:
        The login URI path to intercept.

      • getLogoutPath

        public java.lang.String getLogoutPath()
        Returns the logout URI path to intercept.
        Returns:
        The logout URI path to intercept.

      • getMaxCookieAge

        public int getMaxCookieAge()
        Returns the maximum age of the log info cookie. By default, it uses -1 to make the cookie only last until the end of the current browser session.
        Returns:
        The maximum age of the log info cookie.
        See Also:
        CookieSetting.getMaxAge()

      • getRedirectQueryName

        public java.lang.String getRedirectQueryName()
        Returns the name of the query parameter containing the URI to redirect the browser to after login or logout. By default, it uses "targetUri".
        Returns:
        The name of the query parameter containing the URI to redirect the browser to after login or logout.

      • getSecretFormName

        public java.lang.String getSecretFormName()
        Returns the name of the HTML login form field containing the secret. Returns "password" by default.
        Returns:
        The name of the HTML login form field containing the secret.

      • isInterceptingLogin

        public boolean isInterceptingLogin()
        Indicates if the login requests should be intercepted.
        Returns:
        True if the login requests should be intercepted.

      • isInterceptingLogout

        public boolean isInterceptingLogout()
        Indicates if the logout requests should be intercepted.
        Returns:
        True if the logout requests should be intercepted.

      • isLoggingIn

        protected boolean isLoggingIn​(Request request,
                              Response response)
        Indicates if the request is an attempt to log in and should be intercepted.
        Parameters:
        request - The current request.
        response - The current response.
        Returns:
        True if the request is an attempt to log in and should be intercepted.

      • isLoggingOut

        protected boolean isLoggingOut​(Request request,
                               Response response)
        Indicates if the request is an attempt to log out and should be intercepted.
        Parameters:
        request - The current request.
        response - The current response.
        Returns:
        True if the request is an attempt to log out and should be intercepted.

      • login

        protected void login​(Request request,
                     Response response)
        Processes the login request.
        Parameters:
        request - The current request.
        response - The current response.

      • logout

        protected int logout​(Request request,
                     Response response)
        Processes the logout request.
        Parameters:
        request - The current request.
        response - The current response.

      • parseCredentials

        protected ChallengeResponse parseCredentials​(java.lang.String cookieValue)
        Decodes the credentials stored in a cookie into a proper ChallengeResponse object.
        Parameters:
        cookieValue - The credentials to decode from cookie value.
        Returns:
        The credentials as a proper challenge response.

      • setCookieName

        public void setCookieName​(java.lang.String cookieName)
        Sets the cookie name to use for the authentication credentials.
        Parameters:
        cookieName - The cookie name to use for the authentication credentials.

      • setEncryptAlgorithm

        public void setEncryptAlgorithm​(java.lang.String secretAlgorithm)
        Sets the name of the algorithm used to encrypt the log info cookie value.
        Parameters:
        secretAlgorithm - The name of the algorithm used to encrypt the log info cookie value.

      • setEncryptSecretKey

        public void setEncryptSecretKey​(byte[] secretKey)
        Sets the secret key for the algorithm used to encrypt the log info cookie value.
        Parameters:
        secretKey - The secret key for the algorithm used to encrypt the log info cookie value.

      • setIdentifierFormName

        public void setIdentifierFormName​(java.lang.String loginInputName)
        Sets the name of the HTML login form field containing the identifier.
        Parameters:
        loginInputName - The name of the HTML login form field containing the identifier.

      • setInterceptingLogin

        public void setInterceptingLogin​(boolean intercepting)
        Indicates if the login requests should be intercepted.
        Parameters:
        intercepting - True if the login requests should be intercepted.

      • setInterceptingLogout

        public void setInterceptingLogout​(boolean intercepting)
        Indicates if the logout requests should be intercepted.
        Parameters:
        intercepting - True if the logout requests should be intercepted.

      • setLoginFormPath

        public void setLoginFormPath​(java.lang.String loginFormPath)
        Sets the URI path of the HTML login form to use to challenge the user.
        Parameters:
        loginFormPath - The URI path of the HTML login form to use to challenge the user.

      • setLoginPath

        public void setLoginPath​(java.lang.String loginPath)
        Sets the login URI path to intercept.
        Parameters:
        loginPath - The login URI path to intercept.

      • setLogoutPath

        public void setLogoutPath​(java.lang.String logoutPath)
        Sets the logout URI path to intercept.
        Parameters:
        logoutPath - The logout URI path to intercept.

      • setMaxCookieAge

        public void setMaxCookieAge​(int timeout)
        Sets the maximum age of the log info cookie.
        Parameters:
        timeout - The maximum age of the log info cookie.
        See Also:
        CookieSetting.setMaxAge(int)

      • setRedirectQueryName

        public void setRedirectQueryName​(java.lang.String redirectQueryName)
        Sets the name of the query parameter containing the URI to redirect the browser to after login or logout.
        Parameters:
        redirectQueryName - The name of the query parameter containing the URI to redirect the browser to after login or logout.

      • setSecretFormName

        public void setSecretFormName​(java.lang.String passwordInputName)
        Sets the name of the HTML login form field containing the secret.
        Parameters:
        passwordInputName - The name of the HTML login form field containing the secret.