Package org.apache.wiki.auth.authorize

## Class WebContainerAuthorizer

- java.lang.Object
- - org.apache.wiki.auth.authorize.WebContainerAuthorizer

All Implemented Interfaces:
  `WebAuthorizer`, `Authorizer`

    public class WebContainerAuthorizer
    extends java.lang.Object
    implements WebAuthorizer

Authorizes users by delegating role membership checks to the servlet container. In addition to implementing methods for the `Authorizer` interface, this class also provides a convenience method `isContainerAuthorized()` that queries the web application descriptor to determine if the container manages authorization.

Since:
  2.3

### Nested Class Summary

Nested Classes
`class` `WebContainerAuthorizer.LocalEntityResolver` XML entity resolver that redirects resolution requests by JDOM, JAXP and other XML parsers to locally-cached copies of the resources.

### Field Summary

Fields
`protected boolean` `m_containerAuthorized` Lazily-initialized boolean flag indicating whether the web container protects JSPWiki resources.
`protected Role[]` `m_containerRoles` A lazily-initialized array of Roles that the container knows about.
`protected Engine` `m_engine`

### Constructor Summary

Constructors
`WebContainerAuthorizer()` Constructs a new instance of the WebContainerAuthorizer class.

### Method Summary

All Methods Instance Methods Concrete Methods
`java.security.Principal` `findRole​(java.lang.String role)` Looks up and returns a Role Principal matching a given String.
`java.security.Principal[]` `getRoles()` Returns an array of role Principals this Authorizer knows about.
`protected Role[]` `getRoles​(org.jdom2.Document webxml)` Protected method that extracts the roles from JSPWiki's web application deployment descriptor.
`protected org.jdom2.Document` `getWebXml()` Returns an `Document` representing JSPWiki's web application deployment descriptor.
`void` `initialize​(Engine engine, java.util.Properties props)` Initializes the authorizer for.
`boolean` `isConstrained​(java.lang.String url, Role role)` Protected method that identifies whether a particular webapp URL is constrained to a particular Role.
`boolean` `isContainerAuthorized()` Returns `true` if the web container is configured to protect certain JSPWiki resources by requiring authentication.
`boolean` `isUserInRole​(javax.servlet.http.HttpServletRequest request, java.security.Principal role)` Determines whether a user associated with an HTTP request possesses a particular role.
`boolean` `isUserInRole​(Session session, java.security.Principal role)` Determines whether the Subject associated with a Session is in a particular role.

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

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

### Field Detail

#### m_engine

    protected Engine m_engine

#### m_containerRoles

    protected Role[] m_containerRoles

A lazily-initialized array of Roles that the container knows about. These are parsed from JSPWiki's `web.xml` web application deployment descriptor. If this file cannot be read for any reason, the role list will be empty. This is a hack designed to get around the fact that we have no direct way of querying the web container about which roles it manages.

#### m_containerAuthorized

    protected boolean m_containerAuthorized

Lazily-initialized boolean flag indicating whether the web container protects JSPWiki resources.

### Constructor Detail

#### WebContainerAuthorizer

    public WebContainerAuthorizer()

Constructs a new instance of the WebContainerAuthorizer class.

### Method Detail

#### initialize

    public void initialize​(Engine engine,
                           java.util.Properties props)

Initializes the authorizer for.

Specified by:
  `initialize` in interface `Authorizer`
Parameters:
  `engine` - the current wiki engine
  `props` - the wiki engine initialization properties

#### isUserInRole

    public boolean isUserInRole​(javax.servlet.http.HttpServletRequest request,
                                java.security.Principal role)

Determines whether a user associated with an HTTP request possesses a particular role. This method simply delegates to `HttpServletRequest.isUserInRole(String)` by converting the Principal's name to a String.

Specified by:
  `isUserInRole` in interface `WebAuthorizer`
Parameters:
  `request` - the HTTP request
  `role` - the role to check
Returns:
  `true` if the user is considered to be in the role, `false` otherwise

#### isUserInRole

    public boolean isUserInRole​(Session session,
                                java.security.Principal role)

Determines whether the Subject associated with a Session is in a particular role. This method takes two parameters: the Session containing the subject and the desired role ( which may be a Role or a Group). If either parameter is `null`, this method must return `false`. This method simply examines the Session subject to see if it possesses the desired Principal. We assume that the method `WikiServletFilter.doFilter(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)` previously executed, and that it has set the Session subject correctly by logging in the user with the various login modules, in particular `WebContainerLoginModule`}. This is definitely a hack, but it eliminates the need for Session to keep dangling references to the last WikiContext hanging around, just so we can look up the HttpServletRequest.

Specified by:
  `isUserInRole` in interface `Authorizer`
Parameters:
  `session` - the current Session
  `role` - the role to check
Returns:
  `true` if the user is considered to be in the role, `false` otherwise
See Also:
  `Authorizer.isUserInRole(org.apache.wiki.api.core.Session, java.security.Principal)`

#### findRole

    public java.security.Principal findRole​(java.lang.String role)

Looks up and returns a Role Principal matching a given String. If the Role does not match one of the container Roles identified during initialization, this method returns `null`.

Specified by:
  `findRole` in interface `Authorizer`
Parameters:
  `role` - the name of the Role to retrieve
Returns:
  a Role Principal, or `null`
See Also:
  `Authorizer.initialize(Engine, Properties)`

#### isConstrained

    public boolean isConstrained​(java.lang.String url,
                                 Role role)

Protected method that identifies whether a particular webapp URL is constrained to a particular Role. The resource is considered constrained if:

- the web application deployment descriptor contains a `security-constraint` with a child `web-resource-collection/url-pattern` element matching the URL, and:
- this constraint also contains an `auth-constraint/role-name` element equal to the supplied Role's `getName()` method. If the supplied Role is Role.ALL, it matches all roles

Parameters:
  `url` - the web resource
  `role` - the role
Returns:
  `true` if the resource is constrained to the role, `false` otherwise

#### isContainerAuthorized

    public boolean isContainerAuthorized()

Returns `true` if the web container is configured to protect certain JSPWiki resources by requiring authentication. Specifically, this method parses JSPWiki's web application descriptor (`web.xml`) and identifies whether the string representation of `Role.AUTHENTICATED` is required to access `/Delete.jsp` and `LoginRedirect.jsp`. If the administrator has uncommented the large `<security-constraint>` section of `web.xml`, this will be true. This is admittedly an indirect way to go about it, but it should be an accurate test for default installations, and also in 99% of customized installations.

Returns:
  `true` if the container protects resources, `false` otherwise

#### getRoles

    public java.security.Principal[] getRoles()

Returns an array of role Principals this Authorizer knows about. This method will return an array of Role objects corresponding to the logical roles enumerated in the `web.xml`. This method actually returns a defensive copy of an internally stored array.

Specified by:
  `getRoles` in interface `Authorizer`
Returns:
  an array of Principals representing the roles

#### getRoles

    protected Role[] getRoles​(org.jdom2.Document webxml)

Protected method that extracts the roles from JSPWiki's web application deployment descriptor. Each Role is constructed by using the String representation of the Role, for example `new Role("Administrator")`.

Parameters:
  `webxml` - the web application deployment descriptor
Returns:
  an array of Role objects

#### getWebXml

    protected org.jdom2.Document getWebXml()
                                    throws org.jdom2.JDOMException,
                                           java.io.IOException

Returns an `Document` representing JSPWiki's web application deployment descriptor. The document is obtained by calling the servlet context's `getResource()` method and requesting `/WEB-INF/web.xml`. For non-servlet applications, this method calls this class' `ClassLoader.getResource(java.lang.String)` and requesting `WEB-INF/web.xml`.

Returns:
  the descriptor
Throws:
  `java.io.IOException` - if the deployment descriptor cannot be found or opened
  `org.jdom2.JDOMException` - if the deployment descriptor cannot be parsed correctly