Package org.apache.catalina
Interface Realm
-
- All Superinterfaces:
Contained
- All Known Subinterfaces:
GSSRealm
- All Known Implementing Classes:
CombinedRealm
,DataSourceRealm
,JAASMemoryLoginModule
,JAASRealm
,JDBCRealm
,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.- Author:
- Craig R. McClanahan
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add a property change listener to this component.java.security.Principal
authenticate(java.lang.String username)
Try to authenticate with the specified username.java.security.Principal
authenticate(java.lang.String username, java.lang.String credentials)
Try to authenticate using the specified username and credentials.java.security.Principal
authenticate(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String digestA2)
Deprecated.Unused.java.security.Principal
authenticate(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String digestA2, java.lang.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.java.security.Principal
authenticate(java.security.cert.X509Certificate[] certs)
Try to authenticate using a chain ofX509Certificate
s.java.security.Principal
authenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCreds)
Try to authenticate using aGSSContext
.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()
java.lang.String[]
getRoles(java.security.Principal principal)
Deprecated.This will be removed in Tomcat 10.boolean
hasResourcePermission(Request request, Response response, SecurityConstraint[] constraint, Context context)
Perform access control based on the specified authorization constraint.boolean
hasRole(Wrapper wrapper, java.security.Principal principal, java.lang.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.boolean
isAvailable()
Return the availability of the realm for authentication.void
removePropertyChangeListener(java.beans.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 org.apache.catalina.Contained
getContainer, setContainer
-
-
-
-
Method Detail
-
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
- theCredentialHandler
to use
-
addPropertyChangeListener
void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add a property change listener to this component.- Parameters:
listener
- The listener to add
-
authenticate
java.security.Principal authenticate(java.lang.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
java.security.Principal authenticate(java.lang.String username, java.lang.String credentials)
Try to authenticate using the specified username and credentials.- Parameters:
username
- Username of the Principal to look upcredentials
- Password or other credentials to use in authenticating this username- Returns:
- the associated principal, or
null
if there is none
-
authenticate
@Deprecated java.security.Principal authenticate(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String digestA2)
Deprecated.Unused. Useauthenticate(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 updigest
- Digest which has been submitted by the clientnonce
- Unique (or supposedly unique) token which has been used for this requestnc
- the nonce countercnonce
- the client chosen nonceqop
- the "quality of protection" (nc
andcnonce
will only be used, ifqop
is notnull
).realm
- Realm namedigestA2
- Second digest calculated as digest(Method + ":" + uri)- Returns:
- the associated principal, or
null
if there is none.
-
authenticate
java.security.Principal authenticate(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String digestA2, java.lang.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.- Parameters:
username
- Username of the Principal to look updigest
- Digest which has been submitted by the clientnonce
- Unique (or supposedly unique) token which has been used for this requestnc
- the nonce countercnonce
- the client chosen nonceqop
- the "quality of protection" (nc
andcnonce
will only be used, ifqop
is notnull
).realm
- Realm namedigestA2
- 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
java.security.Principal authenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCreds)
Try to authenticate using aGSSContext
.- Parameters:
gssContext
- The gssContext processed by theAuthenticator
.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
java.security.Principal authenticate(java.security.cert.X509Certificate[] certs)
Try to authenticate using a chain ofX509Certificate
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 processingcontext
- Context the Request is mapped to- Returns:
- the configured
SecurityConstraint
, ornull
if there is none
-
hasResourcePermission
boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraint, Context context) throws java.io.IOException
Perform access control based on the specified authorization constraint.- Parameters:
request
- Request we are processingresponse
- Response we are creatingconstraint
- Security constraint we are enforcingcontext
- The Context to which client of this class is attached.- Returns:
true
if this constraint is satisfied and processing should continue, orfalse
otherwise- Throws:
java.io.IOException
- if an input/output error occurs
-
hasRole
boolean hasRole(Wrapper wrapper, java.security.Principal principal, java.lang.String role)
Check if the specified Principal has the specified security role, within the context of this Realm.- Parameters:
wrapper
- wrapper context for evaluating roleprincipal
- Principal for whom the role is to be checkedrole
- Security role to be checked- Returns:
true
if the specified Principal has the specified security role, within the context of this Realm; otherwise returnfalse
.
-
hasUserDataPermission
boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraint) throws java.io.IOException
Enforce any user data constraint required by the security constraint guarding this request URI.- Parameters:
request
- Request we are processingresponse
- Response we are creatingconstraint
- Security constraint being checked- Returns:
true
if this constraint was not violated and processing should continue, orfalse
if we have created a response already.- Throws:
java.io.IOException
- if an input/output error occurs
-
removePropertyChangeListener
void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Remove a property change listener from this component.- Parameters:
listener
- The listener to remove
-
getRoles
@Deprecated java.lang.String[] getRoles(java.security.Principal principal)
Deprecated.This will be removed in Tomcat 10.Return roles associated with given principal- Parameters:
principal
- thePrincipal
to get the roles for.- Returns:
- principal roles
-
isAvailable
boolean isAvailable()
Return the availability of the realm for authentication.- Returns:
true
if the realm is able to perform authentication
-
-