This documentation relates to last stable version of Cipango.
visit the last unstable documentation home.

Authentication using declarative security

Introduction

This tutorial describes how to configure security realms to provide authentication and access control to SIP applications running in Cipango. A realm has a unique name, and is composed of a set of users. Each user has authentication information (for example, a password) and a set of roles associated with him/herself.

Declarative security is available in Cipango as of version 2.1.1

Sip Application configuration

In this tutorial, we'll who how to add SIP Digest authentication to the MyServlet servlet when receiving REGISTER and INVITE requests.
To add declarative security, add the following declarations in your sip.xml file:

sip.xml
<?xml version="1.0" encoding="UTF-8"?>
<sip-app  xmlns="http://www.jcp.org/xml/ns/sipservlet"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.jcp.org/xml/ns/sipservlet http://www.jcp.org/xml/ns/sipservlet/sip-app_1_1.xsd"
          version="1.1">

  <!-- Ensure that all REGISTER and INVITE requests processed by servlet MyServlet are authentified -->
  <security-constraint>
    <resource-collection>
      <resource-name>Protected Resource</resource-name>
      <servlet-name>MyServlet</servlet-name>
      <sip-method>INVITE</sip-method>
      <sip-method>REGISTER</sip-method>
    </resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>

  <!--  Use realm name cipango.org and digest for authentication -->
  <login-config>
    <auth-method>DIGEST</auth-method>
    <realm-name>cipango.org</realm-name>
  </login-config>

  [...]

</sip-app>

Next step is to declare users and their credentials. To do so, we add the following jetty-web.xml configuration file to our application (in the same directory as sip.xml). In this file we configure a LoginService which is responsible for user management.

jetty-web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<Configure class="org.cipango.sipapp.SipAppContext">
  <Get name="sipSecurityHandler">
    <Set name="loginService">
      <New class="org.eclipse.jetty.security.HashLoginService">
            <Set name="name">cipango.org</Set>
            <Set name="config"><SystemProperty name="jetty.home" default="."/>/etc/realm.properties</Set>
      </New>
    </Set>
  </Get>

</Configure>

Final step is then to populate the realm.properties located in the etc directory of your cipango installation with all desired users and passwords. Each line in the file contains a username, a password, and 0 or more role assignments. For instance, to grant access to alice and bob with passwords foo and bar, add the following lines:

realm.properties
alice: foo
bob: bar

You may now send REGISTER and INVITE requests to your servlet. These requests are authenticated and access is granted only to users alice or bob.