Setting Up LDAP
Setting up the LDAP feature in Socialcast is a multi-step process:
- Install Ruby/RubyGems.
- Install and configure the Socialcast gem.
- Customize the default configuration file.
- Test the script.
- Prevent users from updating the LDAP fields.
- Run the script.
In order to run the Socialcast LDAP script, you must install both Ruby and RubyGems on a machine behind your firewall that has access to the LDAP databases. This machine can be virtual or physical. Before you begin the installation, make sure your Socialcast community is already set up.
Ruby for Windows Environments
For a Windows environment, you must install Ruby 1.9.3 and the Ruby Development Kit.
- Download the most current RubyInstaller from rubyinstaller.org. Run the executable and follow the instructions to install both Ruby and RubyGems.
- Download the Ruby Development Kit from rubyinstaller.org. Run the Ruby Development Kit executable. When prompted, create a directory called
c:DevKit and extract the files there.
- From the Windows Start Menu, select the Open Command Prompt with Ruby option and run the following commands in the command prompt window:
ruby dk.rb init
ruby dk.rb install
Ruby for *nix Environments
In a *nix environment, you can use Ruby 1.9.3 and above. We recommend you use the package manager supplied by your particular operating system to do the installation. Make sure the package manager installs RubyGems as well as Ruby. You do not need to install the Ruby Development Kit.
Ruby/RubyGems Documentation: Go to the source for detailed information about installing Ruby and RubyGems in various environments: Ruby Downloads and Installing RubyGems.
Install and Configure the Socialcast Gem
Once Ruby and RubyGems are in place, you can install and configure the Socialcast gem.
- From a command line, install the gem:Windows environment:
gem install socialcast –-platform=ruby*nix environment:
gem install socialcast
- Specify the name of your Socialcast domain (for example,
socialcast authenticate --domain demo.socialcast.com
- The gem will prompt you for a Socialcast username and password. Use the credentials for a community administrator. You may want to create a special Socialcast user account with admin-level privileges to handle service and support tasks such as this so you don’t need to rely on an admin account belonging to an actual person.SSO Communities: If you’re using SSO, do not use your SSO credentials when prompted. Instead, you must use the community administrator username and an API password that you can set in the administrator’s profile. To create the API password, log into the community as the administrator and go to Settings > Password.
- Generate a default configuration file:
socialcast provision –-setupThe gem will create a configuration file called
ldap.yml and place it in the current directory.
Customize the Default Configuration File
The configuration file (
) contains five sections of information that control the behavior of the LDAP script.
||Specifies the location and credentials for one or more LDAP databases. You can also define a search filter for each database to restrict the users that are included in the import XML file.
||Maps the LDAP field names to the corresponding Socialcast fields.
||Maps each LDAP group to one or more Socialcast roles. Using this information the script can assign Socialcast roles to a new user based on their LDAP group.
||Enables other script functions such as a test mode.
||Controls the HTTP connection to the Socialcast server.
You must edit this file to include information specific to your LDAP installation. For a detailed explanation of every setting in the configuration file, read Editing the Configuration File
Test the Script
Once you’ve edited the configuration file, you can use the test mode to verify that the LDAP script generates an XML file with the correct data. In test mode the script connects to the LDAP databases, creates an import XML file, and uploads the file to the Socialcast server. However, Socialcast does not create, delete, or modify any user information. Socialcast does send a report via email to the administrator whose credentials you provided when installing the Socialcast gem. This report contains a count of the number of user accounts that would have been created or modified as well as a list of the user accounts that would have been deleted.
- Enable the LDAP test mode by setting the
test attribute in the configuration file to
true and the
delete_users_file attribute to
- From the command line, execute the LDAP script. You must supply the path and file name for the configuration file (
socialcast provision --config /path/ldap.yml
- Uncompress and examine the XML file (
users.xml.gz) that the script creates. In particular, you should verify that the search filter you defined is capturing the correct user records. Also, make sure that the field names map properly to the fields in Socialcast. If you don’t see any records at all, you might need to fix the base domain name value.
- Review the report Socialcast sends you via email to ensure that the changes that would have been made are correct.
- Turn off test mode in the configuration file (
test: false and
delete_users_file: true) when you’re satisfied with the script results.
Prevent Users from Updating LDAP Fields
By default Socialcast allows community members to edit their user account information. If you use LDAP to automatically update this information, you should disable the edit function for the fields that LDAP populates. Otherwise, users may update their information in Socialcast one day, but find the original values in place the next time LDAP mirrors the central database.
From within the Socialcast application, go to Admin Settings > Setup > Provisioning and find the LDAP Provisioned Fields section of the page. Check the box next to the fields you have mapped and then click the Save button. Refer to Provisioning
for more details on the provisioning settings available for your community.
Run the Script
To run the LDAP script, enter the following command in a command prompt window:
socialcast provision --config /path/ldap.yml
First Time Execution
The first time you run the LDAP script, Socialcast will create new user accounts for all LDAP users returned by the search filters you defined in the configuration file. You can instruct Socialcast to send emails to the new users (
), welcoming them to the community and providing them with a link to an account set-up screen (see right).
Socialcast populates the name fields using the LDAP information. If you mapped the title field in the configuration file, Socialcast also populates this field. Any pre-populated fields are read-only. The user must supply a password before continuing. (For Single Sign On systems, the password field will also be read-only.)
Non-SSO Installations If your system does not use Single Sign On (SSO), you must set skip_emails to false. Otherwise, new users will not receive a link to the account set-up screen and they won’t be able to access the community.
Schedule Script Execution
To make the most of the LDAP feature in Socialcast, we recommend that you run the script on a regular basis. Depending on the number of users in your community and the frequency of changes to user information, you may want to run the script every day, once a week, or once a month. Use a scheduling application such as Windows Task Scheduler or cron (a *nix tool) to set up a recurring task that executes the LDAP script.