View source for Authentication (Halil)

== Prerequisites ==
A running Open Wonderland server

•	Binary Download [http://openwonderland.org/download/binary]

•	Built Source [http://code.google.com/p/openwonderland/wiki/DownloadBuildSource05]

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 [http://openwonderland.org/modules/module-warehouse/doc_details/190-authentication?cat=add_ons&lang=en '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:

    <!-- all projects -->
    <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="security-session-noauth/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:

    <!--
         copy only the selected modules to the dist directory.  This is the
         default action, unless the modules.include.all property is set
    -->
    <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 [http://blogs.openwonderland.org/2010/09/10/authenticating-wonderland-against-facebook Wonderblog]

Prepared by Ibrahim Halil Altun