How to setup Authentication in OpenWonderland

Prerequisites

A running Open Wonderland server

• Binary Download [1]

• Built Source [2]

By default both binary version and source comes with a module called security-session-noauth, to set up authentication in wonderland server the first step is to replace that module with a authentication support one in this case security-session-auth. The mechanism for doing this vary depending on if you are using binary build or building from source. In both cases you need to replace noauth module with auth module.

In Binary Download

First download a copy of 'security-session-auth' jar file. Now by using module management UI in Open Wonderland server in "http:// example.com:8080//wonderland-web-front/admin?pageURL=/wonderland-web-modules/editor" page remove the module named "security-session-noauth" and replace it by uploading "security-session-auth" module that you downloaded from Open Wonderland Module warehouse. As long as running the same binary version everything will work, but if you download a newer version of binary version you need to do everything above again. Now you can skip the configuration part.

In Source Build

In source build you need to disable the security-session-noauth module and add the security-session-auth module to the list of default modules list. You need to do this by editing build.xml files in the appropriate directories. This assumes you have a directory structure with "wonderland" and "wonderland-modules" as siblings:

        <top-dir>
        <top-dir>/wonderland
        <top-dir>/wonderland-modules
        <top-dir>/wonderland-modules/stable
        <top-dir>/wonderland-modules/unstable

The first step is to disable security-session-noauth from building. You do this in <top-dir>/wonderland/modules/tools/build.xml, by commenting out the line as shown below:

   <filelist dir="${current.dir}" id="all.projects">
       <file name="darkstar/build.xml"/>
       <file name="security-group/build.xml"/>
       <file name="security-session-common/build.xml"/>
       '
       <file name="presence-manager/build.xml"/>

The next step is to add security-session-auth to the default packaged jars. You do this in <top-dir>/wonderland-modules/stable/build.xml, by adding the security-session-auth line below:

   <target name="-modules-stable-dist-copy-selected" unless="modules.include.all">
       <copy todir="dist">
           <filelist dir=".">
               <file name="orientationworld/dist/orientationworld.jar"/>
               <file name="pdfviewer/dist/pdfviewer.jar"/>
               <file name="telepointer/dist/telepointer.jar"/>
               <file name="whiteboard/dist/whiteboard.jar"/>
               <file name="image-viewer/dist/imageviewer.jar"/>
               <file name="audiorecorder-module/dist/audiorecorder.jar"/>
               <file name="stickynote/dist/stickynote.jar"/>
               <file name="security-session-auth/dist/security-session-auth.jar"/>

Finally, before you rebuild you need to make sure there are no cached copies of security-session-noauth.jar hanging around. First delete security-session-noauth.jar file in directory ~/wonderland/modules/dist.

Ant

If you are using ant for compiling your source then from the top directory do the following:

     % cd wonderland/modules/tools/security-session-noauth
     % ant clean

NetBeans IDE

If you are using NetBenas IDE for developing then by using open project tool in NetBeans open the security-session-noauth module as a project and use clean tool for deleting cached copies of security-session-noauth module.

Now you can continue to Configuring Authentication section.

Configuring Authentication

Now that the modules are set up correctly, restart the Open Wonderland server ("java -jar -server(on MacOS) Wonderland.jar" in binary or "ant run-server" in a source build). From this point forward, the instructions should be basically the same for binary distributions and source builds.

• Connect to the web UI, and select "Server Admin". Login using the default username, admin, and the default password, also admin. Since this isn't very secure, your first task is to change the password. Once you have logged in, select Manage Users from the list of pages on the left. This will bring up a list of default users.

• These are the default user accounts used by the services in the system like the Darkstar server, the web server and the shared application server. Select the edit link next to each user to bring up an editor for that user. Change the password, and then click update user. While you are here, this would also be a good time to add some accounts for the users who will log in.

Configure services

Next up, you have to tell the various services like the Darkstar server about these new password you just set. For each password that you set above, create a password file somewhere in the filesystem of your server. This file should consist of a single line with the password you used. The files can be put anywhere, but since they contain an actual password, make sure they are protected for read access. The best place to put password files would be ~/.wonderland-server/0.5-dev/ directory that all the other server data is kept. If server machine is Windows based that you can just open a text file and write your password into it and then change its extension to .password.If server machine is a Mac or Linux based basically do the followings:

     % cd ~/.wonderland-server/0.5-dev
     % echo "yourpasswordhere" > wonderland.password
     % chmod 400 wonderland.password
     % pwd
     /Users/youruser account/.wonderland-server/0.5-dev

Now your password file should be in ~/.wonderland-server/0.5-dev/wonderland.password. Head back to the web UI and click on the manage servers link. For each service, you'll need to set a password by clicking the edit link next to that service. Each service uses a different property to set the password file. Set the appropriate property for the service to the full path to the password file you created above. For the Darkstar server, click the edit link next to Darkstar server under the properties and add the password property, it should be look like:

          Properties
          wonderland.web.server.url              http://example.com:8080/
          sgs.port                               1139
          sgs.password.file                      /Users/ihalilaltun/.wonderland-server/0.5-dev/wonderland.password
          
          [Add] [Property] [Restore Defaults] [Save] [Cancel]

After adding the password property do not forget to change the Darkstar server user password. By doing it go to Manage users link in UI and edit the Darkstar user. Change the password that you created for darkstar server it has to be the same password in wonderland.password file.

Configuring admin password

The final step is to configure the admin password in the web server itself. You do this by editing the my.run.properties file. If your are using source then it is in your ~/wonderland directory and it is probably named my.run.properties.example, you need to delete the extension example, if you are using binary download you need to create a file named my.run.properties in the same directory of Wonderland.jar and then add the following property to my.run.properties file:

     In MacOs or Linux:
     wonderland.webserver.password.file=/Users/yourusername/.wonderland-server/0.5-dev/wonderland.password

     In Windows:
     wonderland.webserver.password.file=C:/Documents and Settings/yourusername/.wonderland-server/0.5-dev/wonderland.password

Now restart the Wonderland web server one more time, and you should be up and running with security. As before, when you login in to the server using the "Server Admin" link, you should be prompted for a password. Use the password you configured for the admin user above. When you log in, you should now see that all the services are properly running.

If everything has worked as expected, when users log in, they should be prompted for a password.User can log in using the accounts set up by the administrator in the user manager.

Enabling guest login

Now that security is turned on, the sensitive areas of Wonderland like the web administration UI are protected, but every user requires a password to connect. With security enabled, you can turn on guest login to allow users to log in without an account. These logins can be made with any user name, as long as it is not already in use by another authentication mechanism (so guests cannot pretend to be users defined in the user manager).

To enable guest login, simple add the following property to the my.run.properties file:

     wonderland.security.allow.guest.login=true

Restart the Wonderland web server, and guest login will be enabled. When users go to log in, they will now have the choice to use an authenticated or unauthenticated login. For further authentication methods please see Wonderblog

Prepared by Ibrahim Halil Altun