Configuring Seraph

There are two places you need to modify your web application to configure Seraph. See the concepts document for explanation of the various pieces of Seraph.

seraph-config.xml File

The core of Seraph is configured through a single config file, named seraph-config.xml. This is usually placed in your web application's WEB-INF/classes directory. Here is a commented sample:

<security-config>
  <parameters>
    <init-param>
      <!--
      the URL to redirect to when the user tries to access a protected resource (rather than clicking on
        an explicit login link). Most of the time, this will be the same value as 'link.login.url'.
      - if the URL is absolute (contains '://'), then redirect that URL (for SSO applications)
      - else the context path will be prepended to this URL

      If '${originalurl}' is present in the URL, it will be replaced with the context-relative URL that the user requested.
      This gives SSO login pages the chance to redirect to the original page
      -->
      <param-name>login.url</param-name>
      <param-value>/login.jsp?os_destination=${originalurl}</param-value>
      <!-- <param-value>http://example.com/SSOLogin?target=${originalurl}</param-value>-->
    </init-param>
    <init-param>
      <!--
      the URL to redirect to when the user explicitly clicks on a login link (rather than being redirected after
        trying to access a protected resource). Most of the time, this will be the same value as 'login.url'.
      - same properties as login.url above
      -->
      <param-name>link.login.url</param-name>
      <param-value>/secure/Dashboard.jspa?os_destination=${originalurl}</param-value>
      <!-- <param-value>http://mycompany.com/SSOLogin?target=${originalurl}</param-value>-->
    </init-param>
    <init-param>
      <!-- URL for logging out.
      - If relative, Seraph just redirects to this URL, which is responsible for calling Authenticator.logout().
      - If absolute (eg. SSO applications), Seraph calls Authenticator.logout() and redirects to the URL
      -->
      <param-name>logout.url</param-name>
      <param-value>/secure/Logout!default.jspa</param-value>
      <!-- <param-value>http://mycompany.com/SSOLogout</param-value>-->
    </init-param>

    <!-- The key that the original URL is stored with in the session -->
    <init-param>
      <param-name>original.url.key</param-name>
      <param-value>os_security_originalurl</param-value>
    </init-param>
    <init-param>
      <param-name>login.cookie.key</param-name>
      <param-value>seraph.os.cookie</param-value>
    </init-param>
    <!-- Specify 3 characters to make cookie encoding unique for your application, to prevent collisions
    if more than one Seraph-based app is used.
    <init-param>
      <param-name>cookie.encoding</param-name>
      <param-value>xYz</param-value>
    </init-param>
    -->
    <!-- Basic Authentication can be enabled by passing the authentication type as a configurable url parameter.
    With this example, you will need to pass http://mycompany.com/anypage?os_authType=basic in the url to enable Basic Authentication -->
    <init-param>
        <param-name>authentication.type</param-name>
        <param-value>os_authType</param-value>
    </init-param>
  </parameters>

  <!-- Determines what roles (permissions) a user has. -->
  <rolemapper class="com.atlassian.myapp.auth.MyRoleMapper"/>

  <!-- A controller is not required. If not specified, security will always be on
  <controller class="com.atlassian.myapp.setup.MyAppSecurityController" />
  -->

  <!-- Logs in users. Must be overridden for SSO apps -->
  <authenticator class="com.atlassian.seraph.auth.DefaultAuthenticator"/>


  <services>
    <!-- Specifies role requirements for accessing specified URL paths -->
    <service class="com.atlassian.seraph.service.PathService">
      <init-param>
        <param-name>config.file</param-name>
        <param-value>/seraph-paths.xml</param-value>
      </init-param>
    </service>

    <!-- Specifies role requirements to execute Webwork actions -->
    <service class="com.atlassian.seraph.service.WebworkService">
      <init-param>
        <param-name>action.extension</param-name>
        <param-value>jspa</param-value>
      </init-param>
    </service>
  </services>

  <interceptors>
    <!-- <interceptor class="com.atlassian.myapp.SomeLoginInterceptor"/> -->
  </interceptors>
</security-config>
            

Filters

There are two filters associated with Seraph, and a servlet, that must be added to your WEB-INF/web.xml file as follows:

<filter>
    <filter-name>login</filter-name>
    <filter-class>com.atlassian.seraph.filter.LoginFilter</filter-class>
</filter>

<filter>
    <filter-name>security</filter-name>
    <filter-class>com.atlassian.seraph.filter.SecurityFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>login</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>security</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<servlet>
    <servlet-name>logout</servlet-name>
    <servlet-class>com.atlassian.seraph.logout.LogoutServlet</servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>logout</servlet-name>
    <url-pattern>/logout</url-pattern>
</servlet-mapping>
Make sure to conform to the web.xml DTD when adding this.