[no-glossary]

I was recently involved in a project where a Novell customer wanted to allow their customers to use their Facebook identity to access their content. Using Facebook credentials also allows them to take advantage of social networking to find even more customers. They could have integrated Facebook authentication into each and every web site they had, but this company had hundreds of web sites each branded for the local market that they served. Instead of doing this integration hundreds of times, they wanted to use Novell Access Manager (NAM) to provide authentication for all their sites. This way if they needed to make any changes or add another third-party authentication service (think Twitter, Google etc.) to their sites, they could do so in one single place instead of hundreds of web sites.

Essentially what happens here is that some Javascript is loaded into your browser from Facebook's site. You then include the Facebook Login button on your page using some of this Javascript, which, when then the user clicks it, will pop up a window to allow the user to login at Facebook's site. When Facebook authentication is successful, a secret is returned to the users page, along with their Facebook unique ID. This information is then sent to the NAM Identity Server (a.k.a Identity Provider – IDP) as part of the login form. The new Authentication Class installed on the NAM Identity Server(s) then verifies that the secret and UID point to a valid, current session.

At this point, the Authentication class will search in the directory for a user with a matching Facebook UID. If one is found, then this user is authenticated and the login process continues. If not, then depending on configuration a user will be auto-created, or the user will be prompted to login as an existing local user in order to link accounts. A future extension could be to redirect the user to a Novell Identity Manager self-registration workflow.

Configuring

1. Set up the Facebook Application

The first thing you will need to do is set up an Application on Facebook. So, go ahead and point your browser at http://www.facebook.com/developers and Login. On the developer page, click the button marked 'Set Up New Application'. You may need to verify your account at this point.

Now enter a name for your application.

Agree to the Facebook terms, and click 'Create Application'

Complete the CAPTCHA check, and click submit.

On the basic information page, feel free to put some information in – this will give a bit more detail to anyone who uses your connection method on what it does, where to get help, etc. The important information is on the "Web Site" tab.

• Application ID: This is generated by Facebook, and unique for your application. We will be using this during configuration of the Authentication class.
• Site URL: Here you will need to enter the address of the authentication method. It is of the form
  
  

  https://<server>:<port>/nidp/idff/sso?id=<AuthenticationContractID>

  where Authentication Contract ID will be defined in section 4.3. In our case it will be:

  https://ism-am-ids.ism.utopia.novell.com:8443/nidp/idff/sso?id=FBConnect

• Site Domain: This allows you to configure Facebook to authenticate users to the whole domain instead of just one site. We do, because the Identity Server is protected several DNS names. In our case it will be:
  
  

  ism.utopia.novell.com

Hit save changes

2. Deploy the code

Next get the code. The zip file attached to this AppNote.

Once you have the code, copy the zip file to the Identity Server. Your Identity Server can be on a Windows or SUSE Linux host. SUSE Linux is used throughout this article. SSH into the Identity Server, and unzip the zip file.

Now:

• copy all the .jar files to /opt/novell/nids/lib/webapp/WEB-INF/lib
• copy FBLinkAccount.jsp and FBLogin.jsp to /opt/novell/nids/lib/webapp/jsp
• copy jquery.js and xd_receiver.htm to /opt/novell/nids/lib/webapp

Now that you've deployed the files, you can restart the Identity Server, or just restart the tomcat service:

/etc/init.d/novell-tomcat5 restart

After restarting, the Facebook Authentication Class will be available for use in the NAM Administration Console which is covered later in this article.

3. Configure the LDAP User Store

You will need an attribute in your LDAP User Store used by Novell Access Manager, in which to store the users' Facebook UID. In this article/example Novell eDirectory is used. You can use any existing attribute that you're not using for anything else, but a better idea is to create an Auxiliary class to house a custom attribute purely for this purpose.

Probably the easiest way to do this is to import the following LDIF file:

#This LDIF file was generated by Novell's ICE and the LDIF destination handler.
version: 1

dn: cn=schema
changetype: modify
add:attributeTypes
attributeTypes: ( fbuid-oid NAME 'fbuid' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )

dn: cn=schema
changetype: modify
add:objectClasses
objectClasses: ( fbconnectaux-oid NAME 'fbconnectAux' AUXILIARY MAY fbuid X-N
 DS_NOT_CONTAINER '1' )

Use the following command line to import it:

ice -S LDIF -f fbConnect.ldif -D LDAP -s <server IP>;-p <server port> -d <admin user> -w <admin password>

This will create an auxiliary class called fbconnectAux, with one attribute fbuid.

4. Configure Access Manager

Now that the new code has been deployed, and the schema has been updated, we can go ahead and configure Access Manager. This part of the NAM configuration is the same as it is when using the out-of-the-box NAM authentication options. The authentication class, method, and contract are defined and linked.

Note: for this section I will be using virtual machine images from the Novell Demo System, so you will need to replace the URLs with those correct for your system, if different.

The Novell Demo System allows you to quickly easily demonstrate, or learn about, all of Novell's technologies by providing pre-built virtual machines, documentation and support forums. To learn more go to http://www.novell.com/demosystems.

4.1 Authentication Class

In a browser, go to your Access Manager Administration console:

https://ism-am-ids.ism.utopia.novell.com:8443/nps

Login as administrator, and go to your Identity server:

On the Local tab, go to the classes subtab

Click New

Enter a display name, for example "Facebook Connect Class"

For Java Class, select 'Other'

In Java Class Path, enter com.novell.kjames.nam.fbconnect.FBConnectAuthenticationClass

Click Next, then Finish

4.2 Authentication Method

Go to the methods subtab, then click new

Enter a display name, for example "Facebook Connect Method"

Select the Class that you created in the previous step

Leave 'Identifies User' checked

Move your user store from 'Available User stores' to User stores – In this case it is the Utopia "IDV" user store

Under properties, add the following properties: (*=Mandatory)

• *UserContainer – the container in the identity store in which to find or create users.
• AutoCreate – If true, the method will automatically create a local user tcorresponding to the facebook user, if it doesn't find a linked account
• FBConnectAuxClass – the auxiliary class containing the facebook uid attribute. This will be added to a user account when the account is linked to a facebook account. Default=fbconnectAux
• FBUidAttrName – the name of the attribute in which to store the facebook uid. This will be added to a user account when the account is linked to a facebook account. Default=fbuid

Click Finish

4.3 Authentication Contract

Go to the Contracts subtab, then click new

Enter a display name, for example 'Facebook Connect Contract'

Enter a URI, for example fbconnect/uri

Add the method from the previous step to the contract

Click next

Enter an ID, for example 'FBConnect'

For Text, enter a descriptive name, for example 'Facebook Connect'

For Image, select 'local image'

Specify a name for the icon, for example 'Facebook Connect'. This will appear in the list

For the description, enter some information

Browse to the location of fbicon.png from the zip file

Click OK

Click Finish

Click OK

Click Update or Update ALL, then OK

5. Protecting a Resource

Now that we have our authentication class, method, and contract configured, we apply it to a protected resource so we can see it work. You can add this to any NAM protected resource. In this article/example we again use the Novell Utopia Demo System.

Let's use the the demo app of Utopia:

Now, we go to the "demo" proxy service, and go to the Protected Resources tab

For the sake of simplicity, let's change the "All" protected resource so that anything on demo.ism.utopia.novell.com requires facebook authentication. Click on "All", then click on the dropdown next to Authentication Procedure and select "Facebook Connect Contract"

Click OK, then OK, then OK, then OK. This should take you to the "Access Gateways" page, which shows "Update" next to your Access Gateway. Click on Update, then click OK. Status will change to "Pending", then "Current".

6. Testing the Facebook Connect Class

In a browser, navigate to your chosen protected URL: in our case, http://demo.ism.utopia.novell.com. This will redirect you to the Facebook Connect authentication page:

Click on the "Connect with Facebook button". This will pop up a facebook authentication window
(NOTE: If you are already logged in to Facebook, this stage will be automatically skipped)

After entering your credentials and clicking login (or, if you're already logged in, after clicking the button in the previous step), if this is the first time you've authenticated via facebook you will see the following window:

This is Facebook making sure that you, the user, want to allow the application access to your basic information. The list of information that will be shared is shown: things such as name, profile picture etc. Hit 'Allow' to allow us to continue

Here, if you have set the AutoCreate flag to false (or left it out, which defaults to false), then it is necessary to link your facebook ID to a local account. You can either link an existing account, or create a new one. The two options are shown here

Option 1: (Link Accounts)	Option 2: (Create local Account)

In both cases, you are given the option to import your avatar. This will be copied into the userPhoto attribute in the directory.

Once you have either linked an existing, or created new account, you will be forwarded to your requested resource. During future logins this step will be performed automatically – you will only need to enter your Facebook credentials, and not the local ones.

Closing Notes

All of the code developed for this Authentication Class was done with the assistance of the Novell Access Manager resources from the Novell's Developer Kit. The URL is:

http://www.novell.com/developer/ndk/novell_access_manager_developer_tools_and_examples.html

This URL provides documentation and example code on

• Authentication Classes (what we've just been working through)
• LDAP Server Plug-ins (integrating LDAP servers other than eDirectory, Active Directory and Sun ONE with Novell Access Manager)
• Policy Extensions (modules that evaluate conditions or access data from external sources in order to determine enforcement or inject into an HTTP header, or perform actions when a condition evaluates to true)
• Identity Injection (accessing data sources not currently supported by Novell Access Manager in order to inject data into a header or query string that is sent to the Web Server)

This documentation describes the general operation of an Authentication Class, and follows on with a more detailed look at which Java methods need to be implemented, and then walks through a simple example, including localization. If you are interested in developing your own Authentication Classes (or any of the other components just mentioned), you should check it out.

[/no-glossary]