Realm (Payara Project 4.1.2.174 API)

All Known Implementing Classes:

JAASRealm, RealmAdapter, RealmBase
```
@Contract
 @PerLookup
public interface Realm
```
A Realm is a read-only facade for an underlying security realm used to authenticate individual users, and identify the security roles associated with those users. Realms can be attached at any Container level, but will typically only be attached to a Context, or higher level, Container.

Version:

$Revision: 1.6 $ $Date: 2007/04/18 17:27:22 $

Author:

Craig R. McClanahan

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`AUTHENTICATE_NEEDED` Flag indicating authentication is needed for current request.
`static int`	`AUTHENTICATE_NOT_NEEDED` Flag indicating authentication is not needed for current request.
`static int`	`AUTHENTICATED_NOT_AUTHORIZED` Flag indicating the user has been authenticated but been denied access to the requested resource.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addPropertyChangeListener(PropertyChangeListener listener)` Add a property change listener to this component.
`Principal`	`authenticate(javax.servlet.http.HttpServletRequest hreq)` Does digest authentication and returns the Principal associated with the username in the HTTP header.
`Principal`	`authenticate(String username, char[] credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
`Principal`	`authenticate(String username, char[] digest, String nonce, String nc, String cnonce, String qop, String realm, char[] md5a2)` Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return `null`.
`Principal`	`authenticate(X509Certificate[] certs)` Return the Principal associated with the specified chain of X509 client certificates.
`SecurityConstraint[]`	`findSecurityConstraints(HttpRequest request, Context context)` Return the SecurityConstraints configured to guard the request URI for this request, or `null` if there is no such constraint.
`SecurityConstraint[]`	`findSecurityConstraints(String uri, String method, Context context)` Gets the security constraints configured by the given context for the given request URI and method.
`String`	`getAlternateAuthType(HttpRequest req)` Return an alternate auth type from the request if available.
`Principal`	`getAlternatePrincipal(HttpRequest req)` Return an alternate principal from the request if available.
`Container`	`getContainer()` Return the Container with which this Realm has been associated.
`String`	`getInfo()` Return descriptive information about this Realm implementation and the corresponding version number, in the format `<description>/<version>`.
`String`	`getRealmName()` Returns the name of the associated realm.
`boolean`	`hasResourcePermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraint, Context context)` Perform access control based on the specified authorization constraint.
`boolean`	`hasRole(HttpRequest request, HttpResponse response, Principal principal, String role)` Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.
`boolean`	`hasRole(Principal principal, String role)` Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.
`boolean`	`hasUserDataPermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraint)` Enforce any user data constraint required by the security constraint guarding this request URI.
`boolean`	`hasUserDataPermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraints, String uri, String method)` Checks if the given request URI and method are the target of any user-data-constraint with a transport-guarantee of CONFIDENTIAL, and whether any such constraint is already satisfied.
`boolean`	`invokeAuthenticateDelegate(HttpRequest request, HttpResponse response, Context context, Authenticator authenticator, boolean calledFromAuthenticate)` Authenticates the user making this request, based on the specified login configuration.
`boolean`	`invokePostAuthenticateDelegate(HttpRequest request, HttpResponse response, Context context)` Post authentication for given request and response.
`boolean`	`isSecurityExtensionEnabled(javax.servlet.ServletContext servletContext)` Returns whether the specified ServletContext indicates that security extension is enabled.
`void`	`logout(HttpRequest hreq)` Logs out.
`int`	`preAuthenticateCheck(HttpRequest request, HttpResponse response, SecurityConstraint[] constraints, boolean disableProxyCaching, boolean securePagesWithPragma, boolean ssoEnabled)` Checks whether or not authentication is needed.
`void`	`removePropertyChangeListener(PropertyChangeListener listener)` Remove a property change listener from this component.
`void`	`setContainer(Container container)` Set the Container with which this Realm has been associated.
`void`	`setRealmName(String name, String authMethod)` Set the name of the associated realm.

- Field Detail
  - AUTHENTICATE_NEEDED
```
static final int AUTHENTICATE_NEEDED
```
    Flag indicating authentication is needed for current request. Used by preAuthenticateCheck method.
    
    See Also:
    
    Constant Field Values
  - AUTHENTICATE_NOT_NEEDED
```
static final int AUTHENTICATE_NOT_NEEDED
```
    Flag indicating authentication is not needed for current request. Used by preAuthenticateCheck method.
    
    See Also:
    
    Constant Field Values
  - AUTHENTICATED_NOT_AUTHORIZED
```
static final int AUTHENTICATED_NOT_AUTHORIZED
```
    Flag indicating the user has been authenticated but been denied access to the requested resource.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getContainer
```
Container getContainer()
```
    Return the Container with which this Realm has been associated.
  - setContainer
```
void setContainer(Container container)
```
    Set the Container with which this Realm has been associated.
    
    Parameters:
    
    container - The associated Container
  - getInfo
```
String getInfo()
```
    Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
  - addPropertyChangeListener
```
void addPropertyChangeListener(PropertyChangeListener listener)
```
    Add a property change listener to this component.
    
    Parameters:
    
    listener - The listener to add
  - authenticate
```
Principal authenticate(String username,
                       char[] credentials)
```
    Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
    
    Parameters:
    
    username - Username of the Principal to look up
    
    credentials - Password or other credentials to use in authenticating this username
  - authenticate
```
Principal authenticate(String username,
                       char[] digest,
                       String nonce,
                       String nc,
                       String cnonce,
                       String qop,
                       String realm,
                       char[] md5a2)
```
    Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return null.
    
    Parameters:
    
    username - Username of the Principal to look up
    
    digest - Digest which has been submitted by the client
    
    nonce - Unique (or supposedly unique) token which has been used for this request
    
    realm - Realm name
    
    md5a2 - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
  - authenticate
```
Principal authenticate(X509Certificate[] certs)
```
    Return the Principal associated with the specified chain of X509 client certificates. If there is none, return null.
    
    Parameters:
    
    certs - Array of client certificates, with the first one in the array being the certificate of the client itself.
  - findSecurityConstraints
```
SecurityConstraint[] findSecurityConstraints(HttpRequest request,
                                             Context context)
```
    Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.
    
    Parameters:
    
    request - Request we are processing
  - findSecurityConstraints
```
SecurityConstraint[] findSecurityConstraints(String uri,
                                             String method,
                                             Context context)
```
    Gets the security constraints configured by the given context for the given request URI and method.
    
    Parameters:
    
    uri - the request URI
    
    method - the request method
    
    context - the context
    
    Returns:
    
    the security constraints configured by the given context for the given request URI and method, or null
  - hasResourcePermission
```
boolean hasResourcePermission(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraint,
                              Context context)
                       throws IOException
```
    Perform access control based on the specified authorization constraint. Return true if this constraint is satisfied and processing should continue, or false otherwise.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    constraint - Security constraint we are enforcing
    
    context - Context to which client of this class is attached.
    
    Throws:
    
    IOException - if an input/output error occurs
  - hasRole
```
boolean hasRole(Principal principal,
                String role)
```
    Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
    
    Parameters:
    
    principal - Principal for whom the role is to be checked
    
    role - Security role to be checked
  - hasRole
```
boolean hasRole(HttpRequest request,
                HttpResponse response,
                Principal principal,
                String role)
```
    Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    principal - Principal for whom the role is to be checked
    
    role - Security role to be checked
  - preAuthenticateCheck
```
int preAuthenticateCheck(HttpRequest request,
                         HttpResponse response,
                         SecurityConstraint[] constraints,
                         boolean disableProxyCaching,
                         boolean securePagesWithPragma,
                         boolean ssoEnabled)
                  throws IOException
```
    Checks whether or not authentication is needed. Returns an int, one of AUTHENTICATE_NOT_NEEDED, AUTHENTICATE_NEEDED, or AUTHENTICATED_NOT_AUTHORIZED.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    constraints - Security constraint we are enforcing
    
    disableProxyCaching - whether or not to disable proxy caching for protected resources.
    
    securePagesWithPragma - true if we add headers which are incompatible with downloading office documents in IE under SSL but which fix a caching problem in Mozill
    
    ssoEnabled - true if sso is enabled
    
    Throws:
    
    IOException - if an input/output error occurs
  - invokeAuthenticateDelegate
```
boolean invokeAuthenticateDelegate(HttpRequest request,
                                   HttpResponse response,
                                   Context context,
                                   Authenticator authenticator,
                                   boolean calledFromAuthenticate)
                            throws IOException
```
    Authenticates the user making this request, based on the specified login configuration. Return true if any specified requirements have been satisfied, or false if we have created a response challenge already.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    context - The Context to which client of this class is attached.
    
    authenticator - the current authenticator.
    
    calledFromAuthenticate - true if the call originates from HttpServletRequest.authenticate
    
    Throws:
    
    IOException - if an input/output error occurs
  - invokePostAuthenticateDelegate
```
boolean invokePostAuthenticateDelegate(HttpRequest request,
                                       HttpResponse response,
                                       Context context)
                                throws IOException
```
    Post authentication for given request and response.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    context - The Context to which client of this class is attached.
    
    Throws:
    
    IOException - if an input/output error occurs
  - hasUserDataPermission
```
boolean hasUserDataPermission(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraint)
                       throws IOException
```
    Enforce any user data constraint required by the security constraint guarding this request URI. Return true if this constraint was not violated and processing should continue, or false if we have created a response already.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    constraint - Security constraint being checked
    
    Throws:
    
    IOException - if an input/output error occurs
  - hasUserDataPermission
```
boolean hasUserDataPermission(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraints,
                              String uri,
                              String method)
                       throws IOException
```
    Checks if the given request URI and method are the target of any user-data-constraint with a transport-guarantee of CONFIDENTIAL, and whether any such constraint is already satisfied. If uri and method are null, then the URI and method of the given request are checked. If a user-data-constraint exists that is not satisfied, then the given request will be redirected to HTTPS.
    
    Parameters:
    
    request - the request that may be redirected
    
    response - the response that may be redirected
    
    constraints - the security constraints to check against
    
    uri - the request URI (minus the context path) to check
    
    method - the request method to check
    
    Returns:
    
    true if the request URI and method are not the target of any unsatisfied user-data-constraint with a transport-guarantee of CONFIDENTIAL, and false if they are (in which case the given request will have been redirected to HTTPS)
    
    Throws:
    
    IOException
  - removePropertyChangeListener
```
void removePropertyChangeListener(PropertyChangeListener listener)
```
    Remove a property change listener from this component.
    
    Parameters:
    
    listener - The listener to remove
  - getAlternatePrincipal
```
Principal getAlternatePrincipal(HttpRequest req)
```
    Return an alternate principal from the request if available.
    
    Parameters:
    
    req - The request object.
    
    Returns:
    
    Alternate principal or null.
  - getAlternateAuthType
```
String getAlternateAuthType(HttpRequest req)
```
    Return an alternate auth type from the request if available.
    
    Parameters:
    
    req - The request object.
    
    Returns:
    
    Alternate auth type or null.
  - setRealmName
```
void setRealmName(String name,
                  String authMethod)
```
    Set the name of the associated realm.
    
    Parameters:
    
    name - the name of the realm.
  - getRealmName
```
String getRealmName()
```
    Returns the name of the associated realm.
    
    Returns:
    
    realm name or null if not set.
  - authenticate
```
Principal authenticate(javax.servlet.http.HttpServletRequest hreq)
```
    Does digest authentication and returns the Principal associated with the username in the HTTP header.
    
    Parameters:
    
    hreq - HTTP servlet request.
  - isSecurityExtensionEnabled
```
boolean isSecurityExtensionEnabled(javax.servlet.ServletContext servletContext)
```
    Returns whether the specified ServletContext indicates that security extension is enabled.
    
    Parameters:
    
    servletContext - the ServletContext
    
    Returns:
    
    true if security extension is enabled; false otherwise
  - logout
```
void logout(HttpRequest hreq)
```
    Logs out.
    
    Parameters:
    
    hreq - the HttpRequest

Interface Realm

Field Summary

Method Summary

Field Detail

AUTHENTICATE_NEEDED

AUTHENTICATE_NOT_NEEDED

AUTHENTICATED_NOT_AUTHORIZED

Method Detail

getContainer

setContainer

getInfo

addPropertyChangeListener

authenticate

authenticate

authenticate

findSecurityConstraints

findSecurityConstraints

hasResourcePermission

hasRole

hasRole

preAuthenticateCheck

invokeAuthenticateDelegate

invokePostAuthenticateDelegate

hasUserDataPermission

hasUserDataPermission

removePropertyChangeListener

getAlternatePrincipal

getAlternateAuthType

setRealmName

getRealmName

authenticate

isSecurityExtensionEnabled

logout