Package org.apache.sling.auth.core

# Class AuthUtil

java.lang.Object
org.apache.sling.auth.core.AuthUtil

public final class AuthUtil extends Object
The `AuthUtil` provides utility functions for implementations of `JakartaAuthenticationHandler` services and users of the Sling authentication infrastructure.

This utility class can neither be extended from nor can it be instantiated.

Since:
  1.1 (bundle version 1.0.8)

## Method Summary

Modifier and Type
Method
Description
`static boolean`
`checkReferer(jakarta.servlet.http.HttpServletRequest request, String loginForm)`
Check if the request is for this authentication handler.
`static boolean`
`checkReferer(javax.servlet.http.HttpServletRequest request, String loginForm)`
Deprecated.
Use `checkReferer(HttpServletRequest, String)`
`static String`
`getAttributeOrParameter(jakarta.servlet.http.HttpServletRequest request, String name, String defaultValue)`
Returns the value of the named request attribute or parameter as a string as follows: If there is a request attribute of that name, which is a non-empty string, it is returned. If there is a non-empty request parameter of that name, this parameter is returned.
`static String`
`getAttributeOrParameter(javax.servlet.http.HttpServletRequest request, String name, String defaultValue)`
Deprecated.
Use `getAttributeOrParameter(HttpServletRequest, String, String)`
`static String`
`getLoginResource(jakarta.servlet.http.HttpServletRequest request, String defaultLoginResource)`
Returns any resource target to redirect to after successful authentication.
`static String`
`getLoginResource(javax.servlet.http.HttpServletRequest request, String defaultLoginResource)`
Deprecated.
Use `getLoginResource(HttpServletRequest, String)`
`static boolean`
`isAjaxRequest(jakarta.servlet.http.HttpServletRequest request)`
Returns `true` if the request is to be considered an AJAX request placed using the `XMLHttpRequest` browser host object.
`static boolean`
`isAjaxRequest(javax.servlet.http.HttpServletRequest request)`
Deprecated.
Use `isAjaxRequest(HttpServletRequest)`
`static boolean`
`isBrowserRequest(jakarta.servlet.http.HttpServletRequest request)`
Returns `true` if the given request can be assumed to be sent by a client browser such as Firefix, Internet Explorer, etc.
`static boolean`
`isBrowserRequest(javax.servlet.http.HttpServletRequest request)`
Deprecated.
Use `isBrowserRequest(HttpServletRequest)`
`static boolean`
`isRedirectValid(jakarta.servlet.http.HttpServletRequest request, String target)`
Returns `true` if the given redirect `target` is valid according to the following list of requirements: The `target` is neither `null` nor an empty string The `target` is not an URL which is identified by the character sequence `://` separating the scheme from the host The `target` is normalized such that it contains no consecutive slashes and no path segment contains a single or double dot The `target` must be prefixed with the servlet context path If a `ResourceResolver` is available as a request attribute the `target` (without the servlet context path prefix) must resolve to an existing resource If a `ResourceResolver` is not available as a request attribute the `target` must be an absolute path starting with a slash character does not contain any of the characters `<`, `>`, `'`, or `"` in plain or URL encoding
`static boolean`
`isRedirectValid(javax.servlet.http.HttpServletRequest request, String target)`
Deprecated.
Use `isRedirectValid(HttpServletRequest, String)`
`static boolean`
`isValidateRequest(jakarta.servlet.http.HttpServletRequest request)`
Returns `true` if the the client just asks for validation of submitted username/password credentials.
`static boolean`
`isValidateRequest(javax.servlet.http.HttpServletRequest request)`
Deprecated.
Use `isValidateRequest(HttpServletRequest)`
`static void`
`sendInvalid(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)`
Sends a 403/FORBIDDEN response optionally stating the reason for this response code in the `AuthConstants.X_REASON` header.
`static void`
`sendInvalid(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `sendInvalid(HttpServletRequest, HttpServletResponse)`
`static void`
`sendRedirect(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, String target, Map<String,String> params)`
Redirects to the given target path appending any parameters provided in the parameter map.
`static void`
`sendRedirect(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String target, Map<String,String> params)`
Deprecated.
Use `sendRedirect(HttpServletRequest, HttpServletResponse, String, Map)`
`static void`
`sendValid(jakarta.servlet.http.HttpServletResponse response)`
Sends a 200/OK response to a credential validation request.
`static void`
`sendValid(javax.servlet.http.HttpServletResponse response)`
Deprecated.
Use `sendValid(HttpServletResponse)`
`static String`
`setLoginResourceAttribute(jakarta.servlet.http.HttpServletRequest request, String defaultValue)`
Ensures and returns the `Authenticator.LOGIN_RESOURCE` request attribute is set to a non-null, non-empty string.
`static String`
`setLoginResourceAttribute(javax.servlet.http.HttpServletRequest request, String defaultValue)`
Deprecated.
Use `setLoginResourceAttribute(HttpServletRequest, String)`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Method Details

### getAttributeOrParameter

public static String getAttributeOrParameter(jakarta.servlet.http.HttpServletRequest request, String name, String defaultValue)
Returns the value of the named request attribute or parameter as a string as follows:

1. If there is a request attribute of that name, which is a non-empty string, it is returned.
2. If there is a non-empty request parameter of that name, this parameter is returned.
3. Otherwise the `defaultValue` is returned.

Parameters:
  `request` - The request from which to return the attribute or request parameter
  `name` - The name of the attribute/parameter
  `defaultValue` - The default value to use if neither a non-empty string attribute or a non-empty parameter exists in the request.
Returns:
  The attribute, parameter or `defaultValue` as defined above.
Since:
  1.6.0

### getAttributeOrParameter

@Deprecated public static String getAttributeOrParameter(javax.servlet.http.HttpServletRequest request, String name, String defaultValue)
Deprecated.
Use `getAttributeOrParameter(HttpServletRequest, String, String)`
Returns the value of the named request attribute or parameter as a string as follows:

1. If there is a request attribute of that name, which is a non-empty string, it is returned.
2. If there is a non-empty request parameter of that name, this parameter is returned.
3. Otherwise the `defaultValue` is returned.

Parameters:
  `request` - The request from which to return the attribute or request parameter
  `name` - The name of the attribute/parameter
  `defaultValue` - The default value to use if neither a non-empty string attribute or a non-empty parameter exists in the request.
Returns:
  The attribute, parameter or `defaultValue` as defined above.

### getLoginResource

public static String getLoginResource(jakarta.servlet.http.HttpServletRequest request, String defaultLoginResource)
Returns any resource target to redirect to after successful authentication. This method either returns a non-empty string or the `defaultLoginResource` parameter. First the `resource` request attribute is checked. If it is a non-empty string, it is returned. Second the `resource` request parameter is checked and returned if it is a non-empty string.

Parameters:
  `request` - The request providing the attribute or parameter
  `defaultLoginResource` - The default login resource value
Returns:
  The non-empty redirection target or `defaultLoginResource`.
Since:
  1.6.0

### getLoginResource

@Deprecated public static String getLoginResource(javax.servlet.http.HttpServletRequest request, String defaultLoginResource)
Deprecated.
Use `getLoginResource(HttpServletRequest, String)`
Returns any resource target to redirect to after successful authentication. This method either returns a non-empty string or the `defaultLoginResource` parameter. First the `resource` request attribute is checked. If it is a non-empty string, it is returned. Second the `resource` request parameter is checked and returned if it is a non-empty string.

Parameters:
  `request` - The request providing the attribute or parameter
  `defaultLoginResource` - The default login resource value
Returns:
  The non-empty redirection target or `defaultLoginResource`.

### setLoginResourceAttribute

public static String setLoginResourceAttribute(jakarta.servlet.http.HttpServletRequest request, String defaultValue)
Ensures and returns the `Authenticator.LOGIN_RESOURCE` request attribute is set to a non-null, non-empty string. If the attribute is not currently set, this method sets it as follows:

1. If the `Authenticator.LOGIN_RESOURCE` request parameter is set to a non-empty string, that parameter is set
2. Otherwise if the `defaultValue` is a non-empty string the default value is used
3. Otherwise the attribute is set to "/"

Parameters:
  `request` - The request to check for the resource attribute
  `defaultValue` - The default value to use if the attribute is not set and the request parameter is not set. This parameter is ignored if it is `null` or an empty string.
Returns:
  returns the value of resource request attribute
Since:
  1.6.0

### setLoginResourceAttribute

@Deprecated public static String setLoginResourceAttribute(javax.servlet.http.HttpServletRequest request, String defaultValue)
Deprecated.
Use `setLoginResourceAttribute(HttpServletRequest, String)`
Ensures and returns the `Authenticator.LOGIN_RESOURCE` request attribute is set to a non-null, non-empty string. If the attribute is not currently set, this method sets it as follows:

1. If the `Authenticator.LOGIN_RESOURCE` request parameter is set to a non-empty string, that parameter is set
2. Otherwise if the `defaultValue` is a non-empty string the default value is used
3. Otherwise the attribute is set to "/"

Parameters:
  `request` - The request to check for the resource attribute
  `defaultValue` - The default value to use if the attribute is not set and the request parameter is not set. This parameter is ignored if it is `null` or an empty string.
Returns:
  returns the value of resource request attribute

### sendRedirect

public static void sendRedirect(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, String target, Map<String,String> params) throws IOException
Redirects to the given target path appending any parameters provided in the parameter map.

This method implements the following functionality:

- If the `params` map does not contain a (non- `null`) value for the `resource` entry, such an entry is generated from the request URI and the (optional) query string of the given `request`.
- The parameters from the `params` map or at least a single `resource` parameter are added to the target path for the redirect. Each parameter value is encoded using the `java.net.URLEncoder` with UTF-8 encoding to make it safe for requests

After checking the redirect target and creating the target URL from the parameter map, the response buffer is reset and the `HttpServletResponse.sendRedirect` is called. Any headers already set before calling this method are preserved.

Parameters:
  `request` - The request object used to get the current request URI and request query string if the `params` map does not have the `resource` parameter set.
  `response` - The response used to send the redirect to the client.
  `target` - The redirect target to validate. This path must be prefixed with the request's servlet context path. If this parameter is not a valid target request as per the `isRedirectValid(HttpServletRequest, String)` method the target is modified to be the root of the request's context.
  `params` - The map of parameters to be added to the target path. This may be `null`.
Throws:
  `IOException` - If an error occurs sending the redirect request
  `IllegalStateException` - If the response was committed or if a partial URL is given and cannot be converted into a valid URL
  `InternalError` - If the UTF-8 character encoding is not supported by the platform. This should not be caught, because it is a real problem if the encoding required by the specification is missing.
Since:
  1.6.0

### sendRedirect

@Deprecated public static void sendRedirect(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String target, Map<String,String> params) throws IOException
Deprecated.
Use `sendRedirect(HttpServletRequest, HttpServletResponse, String, Map)`
Redirects to the given target path appending any parameters provided in the parameter map.

This method implements the following functionality:

- If the `params` map does not contain a (non- `null`) value for the `resource` entry, such an entry is generated from the request URI and the (optional) query string of the given `request`.
- The parameters from the `params` map or at least a single `resource` parameter are added to the target path for the redirect. Each parameter value is encoded using the `java.net.URLEncoder` with UTF-8 encoding to make it safe for requests

After checking the redirect target and creating the target URL from the parameter map, the response buffer is reset and the `HttpServletResponse.sendRedirect` is called. Any headers already set before calling this method are preserved.

Parameters:
  `request` - The request object used to get the current request URI and request query string if the `params` map does not have the `resource` parameter set.
  `response` - The response used to send the redirect to the client.
  `target` - The redirect target to validate. This path must be prefixed with the request's servlet context path. If this parameter is not a valid target request as per the `isRedirectValid(javax.servlet.http.HttpServletRequest, String)` method the target is modified to be the root of the request's context.
  `params` - The map of parameters to be added to the target path. This may be `null`.
Throws:
  `IOException` - If an error occurs sending the redirect request
  `IllegalStateException` - If the response was committed or if a partial URL is given and cannot be converted into a valid URL
  `InternalError` - If the UTF-8 character encoding is not supported by the platform. This should not be caught, because it is a real problem if the encoding required by the specification is missing.

### isValidateRequest

public static boolean isValidateRequest(jakarta.servlet.http.HttpServletRequest request)
Returns `true` if the the client just asks for validation of submitted username/password credentials.

This implementation returns `true` if the request parameter `AuthConstants.PAR_J_VALIDATE` is set to `true` (case-insensitve). If the request parameter is not set or to any value other than `true` this method returns `false`.

Parameters:
  `request` - The request to provide the parameter to check
Returns:
  `true` if the `AuthConstants.PAR_J_VALIDATE` parameter is set to `true`.
Since:
  1.6.0

### isValidateRequest

@Deprecated public static boolean isValidateRequest(javax.servlet.http.HttpServletRequest request)
Deprecated.
Use `isValidateRequest(HttpServletRequest)`
Returns `true` if the the client just asks for validation of submitted username/password credentials.

This implementation returns `true` if the request parameter `AuthConstants.PAR_J_VALIDATE` is set to `true` (case-insensitve). If the request parameter is not set or to any value other than `true` this method returns `false`.

Parameters:
  `request` - The request to provide the parameter to check
Returns:
  `true` if the `AuthConstants.PAR_J_VALIDATE` parameter is set to `true`.

### sendValid

public static void sendValid(jakarta.servlet.http.HttpServletResponse response)
Sends a 200/OK response to a credential validation request.

This method just overwrites the response status to 200/OK, sends no content (content length header set to zero) and prevents caching on clients and proxies. Any other response headers set before calling this methods are preserved and sent along with the response.

Parameters:
  `response` - The response object
Throws:
  `IllegalStateException` - if the response has already been committed
Since:
  1.6.0

### sendValid

@Deprecated public static void sendValid(javax.servlet.http.HttpServletResponse response)
Deprecated.
Use `sendValid(HttpServletResponse)`
Sends a 200/OK response to a credential validation request.

This method just overwrites the response status to 200/OK, sends no content (content length header set to zero) and prevents caching on clients and proxies. Any other response headers set before calling this methods are preserved and sent along with the response.

Parameters:
  `response` - The response object
Throws:
  `IllegalStateException` - if the response has already been committed

### sendInvalid

public static void sendInvalid(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
Sends a 403/FORBIDDEN response optionally stating the reason for this response code in the `AuthConstants.X_REASON` header. The value for the `AuthConstants.X_REASON` header is taken from `JakartaAuthenticationHandler.FAILURE_REASON` request attribute if set.

This method just overwrites the response status to 403/FORBIDDEN, adds the `AuthConstants.X_REASON` header and sends the reason as result back. Any other response headers set before calling this methods are preserved and sent along with the response.

Parameters:
  `request` - The request object
  `response` - The response object
Throws:
  `IllegalStateException` - if the response has already been committed
Since:
  1.6.0

### sendInvalid

@Deprecated public static void sendInvalid(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Deprecated.
Use `sendInvalid(HttpServletRequest, HttpServletResponse)`
Sends a 403/FORBIDDEN response optionally stating the reason for this response code in the `AuthConstants.X_REASON` header. The value for the `AuthConstants.X_REASON` header is taken from `JakartaAuthenticationHandler.FAILURE_REASON` request attribute if set.

This method just overwrites the response status to 403/FORBIDDEN, adds the `AuthConstants.X_REASON` header and sends the reason as result back. Any other response headers set before calling this methods are preserved and sent along with the response.

Parameters:
  `request` - The request object
  `response` - The response object
Throws:
  `IllegalStateException` - if the response has already been committed

### checkReferer

public static boolean checkReferer(jakarta.servlet.http.HttpServletRequest request, String loginForm)
Check if the request is for this authentication handler.

Parameters:
  `request` - the current request
  `loginForm` - Path to the login form
Returns:
  true if the referrer matches this handler, or false otherwise
Since:
  1.6.0

### checkReferer

@Deprecated public static boolean checkReferer(javax.servlet.http.HttpServletRequest request, String loginForm)
Deprecated.
Use `checkReferer(HttpServletRequest, String)`
Check if the request is for this authentication handler.

Parameters:
  `request` - the current request
  `loginForm` - Path to the login form
Returns:
  true if the referrer matches this handler, or false otherwise

### isRedirectValid

public static boolean isRedirectValid(jakarta.servlet.http.HttpServletRequest request, String target)
Returns `true` if the given redirect `target` is valid according to the following list of requirements:

- The `target` is neither `null` nor an empty string
- The `target` is not an URL which is identified by the character sequence `://` separating the scheme from the host
- The `target` is normalized such that it contains no consecutive slashes and no path segment contains a single or double dot
- The `target` must be prefixed with the servlet context path
- If a `ResourceResolver` is available as a request attribute the `target` (without the servlet context path prefix) must resolve to an existing resource
- If a `ResourceResolver` is not available as a request attribute the `target` must be an absolute path starting with a slash character does not contain any of the characters `<`, `>`, `'`, or `"` in plain or URL encoding

If any of the conditions does not hold, the method returns `false` and logs a warning level message with the org.apache.sling.auth.core.AuthUtil logger.

Parameters:
  `request` - Providing the `ResourceResolver` attribute and the context to resolve the resource from the `target`. This may be `null` which causes the target to not be validated with a `ResoureResolver`
  `target` - The redirect target to validate. This path must be prefixed with the request's servlet context path.
Returns:
  `true` if the redirect target can be considered valid
Since:
  1.6.0

### isRedirectValid

@Deprecated public static boolean isRedirectValid(javax.servlet.http.HttpServletRequest request, String target)
Deprecated.
Use `isRedirectValid(HttpServletRequest, String)`
Returns `true` if the given redirect `target` is valid according to the following list of requirements:

- The `target` is neither `null` nor an empty string
- The `target` is not an URL which is identified by the character sequence `://` separating the scheme from the host
- The `target` is normalized such that it contains no consecutive slashes and no path segment contains a single or double dot
- The `target` must be prefixed with the servlet context path
- If a `ResourceResolver` is available as a request attribute the `target` (without the servlet context path prefix) must resolve to an existing resource
- If a `ResourceResolver` is not available as a request attribute the `target` must be an absolute path starting with a slash character does not contain any of the characters `<`, `>`, `'`, or `"` in plain or URL encoding

If any of the conditions does not hold, the method returns `false` and logs a warning level message with the org.apache.sling.auth.core.AuthUtil logger.

Parameters:
  `request` - Providing the `ResourceResolver` attribute and the context to resolve the resource from the `target`. This may be `null` which causes the target to not be validated with a `ResoureResolver`
  `target` - The redirect target to validate. This path must be prefixed with the request's servlet context path.
Returns:
  `true` if the redirect target can be considered valid

### isBrowserRequest

public static boolean isBrowserRequest(jakarta.servlet.http.HttpServletRequest request)
Returns `true` if the given request can be assumed to be sent by a client browser such as Firefix, Internet Explorer, etc.

This method inspects the `User-Agent` header and returns `true` if the header contains the string Mozilla (known to be contained in Firefox, Internet Explorer, WebKit-based browsers User-Agent) or Opera (known to be contained in the Opera User-Agent).

Parameters:
  `request` - The request to inspect
Returns:
  `true` if the request is assumed to be sent by a browser.
Since:
  1.6.0

### isBrowserRequest

@Deprecated public static boolean isBrowserRequest(javax.servlet.http.HttpServletRequest request)
Deprecated.
Use `isBrowserRequest(HttpServletRequest)`
Returns `true` if the given request can be assumed to be sent by a client browser such as Firefix, Internet Explorer, etc.

This method inspects the `User-Agent` header and returns `true` if the header contains the string Mozilla (known to be contained in Firefox, Internet Explorer, WebKit-based browsers User-Agent) or Opera (known to be contained in the Opera User-Agent).

Parameters:
  `request` - The request to inspect
Returns:
  `true` if the request is assumed to be sent by a browser.

### isAjaxRequest

public static boolean isAjaxRequest(jakarta.servlet.http.HttpServletRequest request)
Returns `true` if the request is to be considered an AJAX request placed using the `XMLHttpRequest` browser host object. Currently a request is considered an AJAX request if the client sends the X-Requested-With request header set to `XMLHttpRequest` .

Parameters:
  `request` - The current request
Returns:
  `true` if the request can be considered an AJAX request.
Since:
  1.6.0

### isAjaxRequest

@Deprecated public static boolean isAjaxRequest(javax.servlet.http.HttpServletRequest request)
Deprecated.
Use `isAjaxRequest(HttpServletRequest)`
Returns `true` if the request is to be considered an AJAX request placed using the `XMLHttpRequest` browser host object. Currently a request is considered an AJAX request if the client sends the X-Requested-With request header set to `XMLHttpRequest` .

Parameters:
  `request` - The current request
Returns:
  `true` if the request can be considered an AJAX request.