Cookie Notice

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.


View cookie preferences