Realm (Apache Tomcat 10.1.48 API Documentation)
Description: declaration: package: org.apache.catalina, interface: Realm

# Interface Realm

All Superinterfaces:
  `Contained`

All Known Implementing Classes:
  `AuthenticatedUserRealm, CombinedRealm, DataSourceRealm, JAASMemoryLoginModule, JAASRealm, JNDIRealm, LockOutRealm, MemoryRealm, NullRealm, RealmBase, UserDatabaseRealm`

public interface Realm extends Contained
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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addPropertyChangeListener(PropertyChangeListener listener)`
  Add a property change listener to this component.
  `Principal`
  `authenticate(String username)`
  Try to authenticate with the specified username.
  `Principal`
  `authenticate(String username, String credentials)`
  Try to authenticate using the specified username and credentials.
  `Principal`
  `authenticate(String username, String digest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2)`
  Deprecated.
  Unused.
  `default Principal`
  `authenticate(String username, String digest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2, String algorithm)`
  Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
  `Principal`
  `authenticate(X509Certificate[] certs)`
  Try to authenticate using a chain of `X509Certificate`s.
  `Principal`
  `authenticate(GSSContext gssContext, boolean storeCreds)`
  Try to authenticate using a `GSSContext`.
  `Principal`
  `authenticate(GSSName gssName, GSSCredential gssCredential)`
  Try to authenticate using a `GSSName`.
  `void`
  `backgroundProcess()`
  Execute a periodic task, such as reloading, etc.
  `SecurityConstraint[]`
  `findSecurityConstraints(Request request, Context context)`
  Find the SecurityConstraints configured to guard the request URI for this request.
  `CredentialHandler`
  `getCredentialHandler()`
  `boolean`
  `hasResourcePermission(Request request, Response response, SecurityConstraint[] constraint, Context context)`
  Perform access control based on the specified authorization constraint.
  `boolean`
  `hasRole(Wrapper wrapper, Principal principal, String role)`
  Check if the specified Principal has the specified security role, within the context of this Realm.
  `boolean`
  `hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraint)`
  Enforce any user data constraint required by the security constraint guarding this request URI.
  `default boolean`
  `isAvailable()`
  Return the availability of the realm for authentication.
  `void`
  `removePropertyChangeListener(PropertyChangeListener listener)`
  Remove a property change listener from this component.
  `void`
  `setCredentialHandler(CredentialHandler credentialHandler)`
  Set the CredentialHandler to be used by this Realm.

  ### Methods inherited from interface Contained

  `getContainer, setContainer`

- ## Method Details

  - ### getCredentialHandler

    CredentialHandler getCredentialHandler()
    Returns:
      the CredentialHandler configured for this Realm.

  - ### setCredentialHandler

    void setCredentialHandler(CredentialHandler credentialHandler)
    Set the CredentialHandler to be used by this Realm.
    Parameters:
      `credentialHandler` - the `CredentialHandler` to use

  - ### addPropertyChangeListener

    void addPropertyChangeListener(PropertyChangeListener listener)
    Add a property change listener to this component.
    Parameters:
      `listener` - The listener to add

  - ### authenticate

    Principal authenticate(String username)
    Try to authenticate with the specified username.
    Parameters:
      `username` - Username of the Principal to look up
    Returns:
      the associated principal, or `null` if none is associated.

  - ### authenticate

    Principal authenticate(String username, String credentials)
    Try to authenticate using the specified username and credentials.
    Parameters:
      `username` - Username of the Principal to look up
      `credentials` - Password or other credentials to use in authenticating this username
    Returns:
      the associated principal, or `null` if there is none

  - ### authenticate

    @Deprecated Principal authenticate(String username, String digest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2)
    Deprecated.
    Unused. Use `authenticate(String, String, String, String, String, String, String, String, String)`. Will be removed in Tomcat 11.
    Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).
    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
      `nc` - the nonce counter
      `cnonce` - the client chosen nonce
      `qop` - the "quality of protection" (`nc` and `cnonce` will only be used, if `qop` is not `null`).
      `realm` - Realm name
      `digestA2` - Second digest calculated as digest(Method + ":" + uri)
    Returns:
      the associated principal, or `null` if there is none.

  - ### authenticate

    default Principal authenticate(String username, String digest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2, String algorithm)
    Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.

    The default implementation calls `authenticate(String, String, String, String, String, String, String, String)` for backwards compatibility which effectively forces the use of MD5 regardless of the algorithm specified in the call to this method.

    Implementations are expected to override the default implementation and take account of the algorithm parameter.

    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
      `nc` - the nonce counter
      `cnonce` - the client chosen nonce
      `qop` - the "quality of protection" (`nc` and `cnonce` will only be used, if `qop` is not `null`).
      `realm` - Realm name
      `digestA2` - Second digest calculated as digest(Method + ":" + uri)
      `algorithm` - The message digest algorithm to use
    Returns:
      the associated principal, or `null` if there is none.

  - ### authenticate

    Principal authenticate(GSSContext gssContext, boolean storeCreds)
    Try to authenticate using a `GSSContext`.
    Parameters:
      `gssContext` - The gssContext processed by the `Authenticator`.
      `storeCreds` - Should the realm attempt to store the delegated credentials in the returned Principal?
    Returns:
      the associated principal, or `null` if there is none

  - ### authenticate

    Principal authenticate(GSSName gssName, GSSCredential gssCredential)
    Try to authenticate using a `GSSName`.
    Parameters:
      `gssName` - The `GSSName` of the principal to look up
      `gssCredential` - The `GSSCredential` of the principal, may be `null`
    Returns:
      the associated principal, or `null` if there is none

  - ### authenticate

    Principal authenticate(X509Certificate[] certs)
    Try to authenticate using a chain of `X509Certificate`s.
    Parameters:
      `certs` - Array of client certificates, with the first one in the array being the certificate of the client itself.
    Returns:
      the associated principal, or `null` if there is none

  - ### backgroundProcess

    void backgroundProcess()
    Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.

  - ### findSecurityConstraints

    SecurityConstraint[] findSecurityConstraints(Request request, Context context)
    Find the SecurityConstraints configured to guard the request URI for this request.
    Parameters:
      `request` - Request we are processing
      `context` - Context the Request is mapped to
    Returns:
      the configured `SecurityConstraint`, or `null` if there is none

  - ### hasResourcePermission

    boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraint, Context context) throws IOException
    Perform access control based on the specified authorization constraint.
    Parameters:
      `request` - Request we are processing
      `response` - Response we are creating
      `constraint` - Security constraint we are enforcing
      `context` - The Context to which client of this class is attached.
    Returns:
      `true` if this constraint is satisfied and processing should continue, or `false` otherwise
    Throws:
      `IOException` - if an input/output error occurs

  - ### hasRole

    boolean hasRole(Wrapper wrapper, Principal principal, String role)
    Check if the specified Principal has the specified security role, within the context of this Realm.
    Parameters:
      `wrapper` - wrapper context for evaluating role
      `principal` - Principal for whom the role is to be checked
      `role` - Security role to be checked
    Returns:
      `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.

  - ### hasUserDataPermission

    boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraint) throws IOException
    Enforce any user data constraint required by the security constraint guarding this request URI.
    Parameters:
      `request` - Request we are processing
      `response` - Response we are creating
      `constraint` - Security constraint being checked
    Returns:
      `true` if this constraint was not violated and processing should continue, or `false` if we have created a response already.
    Throws:
      `IOException` - if an input/output error occurs

  - ### removePropertyChangeListener

    void removePropertyChangeListener(PropertyChangeListener listener)
    Remove a property change listener from this component.
    Parameters:
      `listener` - The listener to remove

  - ### isAvailable

    default boolean isAvailable()
    Return the availability of the realm for authentication.
    Returns:
      `true` if the realm is able to perform authentication