Additional documentation here: https://github.com/SpiderOak/flow-ldap/blob/master/doc/usage.md
Semaphor-LDAP consists of a service/server application and a command line client. The server runs as a daemon in Unix and as a service in Windows. The client provides commands to configure the server and retrieve information about the users tracked by the Semaphor-LDAP server.
TERMINOLOGY
DIRECTORY MANAGEMENT ACCOUNT (DMA)
The Semaphor account that manages the Semaphor integration with AD or LDAP. The Semaphor-LDAP server runs this account. The DMA for a given domain is created using the Directory Management Key
obtained in the Setup LDAP
web process.
DIRECTORY MANAGEMENT KEY (DMK)
The DMK
is a secret token used to create the DMA
for your domain.
LDAP TEAM
The LDAP Team
is the Semaphor Team configured in the LDAP Setup
. It is the team managed by the Directory Management Account running in the Semaphor-LDAP server. All accounts under the domain are automatically added to this team.
ADMIN ACCOUNTS
Semaphor LDAP Team
admins are considered admins of the domain by the Semaphor-LDAP. These accounts are automatically added to the LOG channel.
PRESCRIBED CHANNELS
These are channels within the LDAP Team to which accounts are automatically added to. To turn a channel into a prescribed channel, an admin must make the DMA
an admin of such channel. Admin accounts are the only accounts allowed to add the DMA
to a channel.
LOG CHANNEL
Semaphor-LDAP will send ERROR messages to the log channel. Only admins will be added to such channel.
EXCLUDED ACCOUNTS
These accounts are excluded from the LDAP sync algorithm and therefore not handled by Semaphor-LDAP. Excluded accounts are specified as a comma-separated list in the excluded-accounts
configuration variable.
SEMAPHOR ACCOUNT STATES
A user Semaphor account under LDAP control can be in one of three states: - unlocked
: Under control of the DMA and fully operational. - ldap-locked
: Account is locked with only two possible actions: join LDAP or change username. - full-locked
: Account has been locked by the DMA because it is disabled on LDAP. The account cannot operate on the flow service whatsoever.
BANNED ACCOUNTS
Accounts banned from the LDAP Team
are not automatically added to the team by the bot. Likewise, accounts banned from prescribed channels are not automatically added to these channels by the bot. These accounts must be re-added to team/channels manually by team/channel admins.
SERVER/SERVICE APPLICATION
The service performs the following main operations: - LDAP account polling (via LDAP Group/OU listing). - Semaphor domain account management. - Provide an HTTP JSON-RPC API.
COMMAND LINE CLIENT APPLICATION
The client
mode communicates with the Semaphor-LDAP server via the HTTP JSON-RPC API. Currently, both the client and the server must run in the same host.
Use the --help
option to get a list of the available client commands:
SEMAPHOR-LDAP.EXE --HELP
SEMAPHOR-LDAP SERVER CONFIGURATION STEPS
Basically, the steps to integrate your LDAP server with Semaphor are: 1. Create a Team on Semaphor. 2. Upgrade the Team to Professional
. 3. Go to Manage Team
-> Claim Domains
. You are redirected to SpiderOak web. 4. On the web, click on Domains
-> Manage
and perform the Domain Claiming
web process. 5. Once a domain claim is validated for your team, go to Directory Management
-> Add Key
. A Directory Management Key
(aka DMK
) will be provided. 6. Install Semaphor-LDAP on your server. The installer will automatically register and start the Windows Service. The service binary semaphor-ldap-service.exe
, and the client binary semaphor-ldap.exe
will be installed (by default) on C:\Program Files\Semaphor-LDAP x64\
. 7. Using the command line client application, semaphor-ldap.exe
, configure the Semaphor-LDAP service with correct LDAP configuration to connect to your LDAP server. See Configuration Variables. 8. Create the Directory Management Account
(aka DMA
) for your domain with the create-account
client command using the provided DMK
. 9. Accept the DMA
as member of the LDAP Team, and also make it an admin of the team. 10. Wait for or trigger an ldap-sync
, which will create Semaphor accounts for all LDAP accounts. 11. Leave the Semaphor-LDAP service running in the background, it will perform the following operations: - Allow the creation of devices using LDAP credentials. - Join existing Semaphor accounts in the domain to LDAP. - Lock/Unlock Semaphor accounts by looking at the LDAP enabled state. - Automatically add accounts to the LDAP team and prescribed channels.
STEP BY STEP GUIDE
The command line client application, semaphor-ldap.exe
, must be executed in a console in Administrator mode.
Once the server is running we can check its current state via the check-status
command. On the first run you will probably see the following output:
CD C:\PROGRAM FILES\SEMAPHOR-LDAP X64\ SEMAPHOR-LDAP.EXE CHECK-STATUS CHECKING SEMAPHOR-LDAP SERVER STATUS... SERVER STATUS: - DB = OK - FLOW = ERROR: DMA IS NOT CONFIGURED YET - LDAP = ERROR: {'DESC': "CAN'T CONTACT LDAP SERVER"} - SYNC = OFF
- THE FIRSTFLOW = ERROR
MEANS YOU HAVEN'T CONFIGURED YOUR DIRECTORY MANAGEMENT ACCOUNT. - THE SECONDLDAP = ERROR
MEANS THE CURRENT CONFIGURATION FOR CONNECTING TO YOUR LDAP SERVER IS INVALID. -SYNC = OFF
MEANS THE LDAP-SYNC SCHEDULED RUN IS OFF.
Let's configure the LDAP values first, you can see the current configuration with the 'config-list' command:
SEMAPHOR-LDAP.EXE CONFIG-LIST GETTING CONFIG LIST... == LDAP CONFIG == - LDAP-USER = CN=USER,DC=DOMAIN,DC=COM # (1) - DIR-USERNAME-SOURCE = USERPRINCIPALNAME - GROUP-DN = OU=PEOPLE,DC=DOMAIN,DC=COM # (2) - SERVER-TYPE = AD - URI = LDAP://DOMAIN.COM # (3) - LDAP-PW = ** # (4) - BASE-DN =
- DIR-AUTH-SOURCE = - DIR-AUTH-USERNAME = - DIR-GUID-SOURCE = OBJECTGUID - DIR-MEMBER-SOURCE = MEMBER == SERVER CONFIG == - DB-BACKUP-MINUTES = 60 - LISTEN-PORT = 8080 - VERBOSE = NO - LDAP-SYNC-ON = NO - LDAP-SYNC-MINUTES = 60 - LOG-DEST = FILE - EXCLUDED-ACCOUNTS =
To configure LDAP you need to update the five config values marked above, to do that we have to use the config-set
command
By default, Semaphor-LDAP is not verbose, for the purpose of this configuration, we should set the verbose
mode to yes
:
SEMAPHOR-LDAP.EXE CONFIG-SET --KEY VERBOSE --VALUE YES
SEMAPHOR-LDAP.EXE CONFIG-SET --KEY URI --VALUE LDAP://EXAMPLE.COM:389 SETTING CONFIG 'URI'...
SEMAPHOR-LDAP.EXE CONFIG-SET --KEY LDAP-USER --VALUE USER@EXAMPLE.COM SETTING CONFIG 'LDAP-USER'...
SEMAPHOR-LDAP.EXE CONFIG-SET --KEY LDAP-PW PASSWORD: SETTING CONFIG 'LDAP-PW'...
SEMAPHOR-LDAP.EXE CONFIG-SET --KEY GROUP-DN --VALUE CN=MYGROUP,CN=USERS,DC=EXAMPLE,DC=COM SETTING CONFIG 'GROUP-DN'...
Now we should see an "OK" on the ldap status:
SEMAPHOR-LDAP.EXE CHECK-STATUS CHECKING SEMAPHOR-LDAP SERVER STATUS... SERVER STATUS: - DB = OK - FLOW = ERROR: DMA IS NOT CONFIGURED YET - LDAP = OK - SYNC = OFF
Before continuing with flow, we should list the users that will be controlled by Semaphor-LDAP server by using the group-userlist
command. This option will list the users that belong to the group specified in the group-dn
config variable.
SEMAPHOR-LDAP.EXE GROUP-USERLIST GETTING LIST OF ACCOUNTS FROM THE CONFIGURED LDAP GROUP... JOHN@EXAMPLE.COM, UID = FC6DD73A-EBE5-4AC2-8A54-B6FE89638E8F, LDAP-STATE = ENABLED ALICE@EXAMPLE.COM, UID = DEA2C6B5-6123-4E18-BE5B-92B33506C3A5, LDAP-STATE = ENABLED MARK@EXAMPLE.COM, UID = DEB32BA5-6223-3A1B-3E5B-93324506C3A5, LDAP-STATE = DISABLED [...]
IF EVERYTHING LOOKS GOOD, WE CAN CONTINUE WITH THE FLOW SETUP.
We can now create the Diretory Management Account
(aka DMA
) to manage the domain. To create a DMA
we need the Directory Management Key
(aka DMK
).
IMPORTANT: You must securely store the generated username and recovery-key.
SEMAPHOR-LDAP.EXE CREATE-ACCOUNT --DMK NNBTWOQMSTHOF27VTODWKZF63CLUVSS4A22QNK4WEHYQNS7BLTHQ CREATING DIRECTORY MANAGEMENT ACCOUNT... THE DMA ACCOUNT WAS CREATED, PLEASE SECURELY STORE THE FOLLOWING CREDENTIALS: - USERNAME = DMAPXZJN7QKPR - RECOVERY KEY = USKONS7UYKDFATRPFMGSUACPHAVKUFC3 A TEAM JOIN REQUEST WAS SENT TO THE LDAP TEAM = 7QXVLPNHOFJZJTIOL2GHV4YFDZDRQV54 BNNCYQ7OPLYBTGZO4ZCQ. TO FINISH THE SETUP PLEASE ACCEPT THE REQUEST AND MAKE THE DMA AN ADMIN.
Now you need to go to Semaphor and accept the DMA
Team Join Request to the LDAP Team and also make it an admin of the Team. After all this, we should see an "OK" on the flow status
SEMAPHOR-LDAP.EXE CHECK-STATUS CHECKING SEMAPHOR-LDAP SERVER STATUS... SERVER STATUS: - DB = OK - FLOW = OK - LDAP = OK - SYNC = OFF
With LDAP and the Flow service properly configured we can enable the LDAP sync
. The LDAP sync
will run every ldap-sync-minutes
minutes. It creates Semaphor accounts for the accounts listed in the given LDAP group. The LDAP sync will also lock/unlock Semaphor accounts by looking at the LDAP state.
SEMAPHOR-LDAP.EXE LDAP-SYNC-ENABLE SEMAPHOR-LDAP.EXE CHECK-STATUS CHECKING SEMAPHOR-LDAP SERVER STATUS... SERVER STATUS: - DB = OK - FLOW = OK - LDAP = OK - SYNC = ON
WITHSYNC = ON
WE CAN NOW PROCEED TO TRIGGER A MANUALLDAP-SYNC
We could wait for the first scheduled LDAP sync
run, but we can also trigger one manually:
SEMAPHOR-LDAP.EXE LDAP-SYNC-TRIGGER TRIGERRING AN LDAP SYNC...
WHEN THE LDAP-SYNC IS RUNNING, THEN THE CHECK-STATUS COMMAND WILL SHOW A 'OK, RUNNING...' IN 'SYNC':
SEMAPHOR-LDAP.EXE CHECK-STATUS CHECKING SEMAPHOR-LDAP SERVER STATUS... SERVER STATUS: - DB = OK - FLOW = OK - LDAP = OK - SYNC = ON, RUNNING...
THELDAP-SYNC
PROCESS MAY TAKE A WHILE (FROM MINUTES TO HOURS), DEPENDING ON THE NUMBER OF LDAP ACCOUNTS MEMBERS OF THE CONFIGUREDGROUP-DN
.
Before continuing, you should wait for the ldap-sync
process to finish, that is: sync
to be OK
(without the , running...
part). After the ldap-sync
finishes, all pre-existing Semaphor accounts on the domain will be locked and given the choice of joining LDAP or changing their username.
Accounts should be ready after the LDAP sync, we can check their state by using the db-userlist
command. - unlocked
are Semaphor accounts owned by Semaphor-LDAP. - ldap-locked
are Semaphor accounts that are locked and given the choice between join to LDAP or change username. - full-locked
are Semaphor accounts that cannot operate, they correspond to a disabled
LDAP state.
SEMAPHOR-LDAP.EXE DB-USERLIST RETRIEVING USERS FROM THE LOCAL DATABASE... JOHN@EXAMPLE.COM, UID = FC6DD73A-EBE5-4AC2-8A54-B6FE89638E8F, LDAP-STATE = DISABLED, SEMAPHOR-GUID = 73M5UDSR263J7F3RQJO4NIISN3WL4LXJU3YC6JNHM7VLFYFNJ63A, SEMAPHOR-LOCK-STATE = UNLOCKED ALICE@EXAMPLE.COM, UID = DEA2C6B5-6123-4E18-BE5B-92B33506C3A5, LDAP-STATE = ENABLED, SEMAPHOR-GUID = 46YIUGBAWFNOWRA53E6UXTJH5EQ5FIP3ONDGEQZCTTBH7UK6QMEA, SEMAPHOR-LOCK-STATE = LDAP-LOCKED ...
With the first ldap-sync
finished and the Semaphor-LDAP service up and running, we must retrieve the Semaphor Join LDAP URI and share it to employees so they can start using Enterprise Semaphor.
SEMAPHOR-LDAP.EXE DMA-FINGERPRINT GETTING DIRECTORY MANAGEMENT ACCOUNT FINGERPRINT... FINGERPRINT = LAA75OEDLBUV4H6IKNFJW5GBOGEBLPXA5MKLLXL7XJE6WQM5SXJA URI = SEMAPHOR://ENTERPRISE-SIGN-IN/LAA75OEDLBUV4H6IKNFJW5GBOGEBLPXA5MKLLXL7XJE6WQM5SXJA
WITH THE PROVIDED URI/FINGERPRINT, THEY WILL BE ABLE TO START USING SEMAPHOR USING THEIR LDAP CREDENTIALS.
You can redirect server logging to one of event
(on Windows), syslog
(on Linux) and file
by using the log-dest
command:
SEMAPHOR-LDAP.EXE LOG-DEST --TARGET EVENT SETTING LOG DESTINATION TO FILE...
BY DEFAULT, ON WINDOWS, SEMAPHOR-LDAP LOGS TO THEEVENT LOG
(EVENT
).
If you are done configuring Semaphor-LDAP, then you should turn off the verbose
mode:
SEMAPHOR-LDAP.EXE CONFIG-SET --KEY VERBOSE --VALUE NO
If you want to stop the semaphor-ldap service, use the semaphor-ldap-service.exe
executable:
SEMAPHOR-LDAP-SERVICE.EXE STOP
AND, AS WITH ANY WINDOWS SERVICE, YOU CAN ALSO {START,RESTART,REMOVE,INSTALL} THE SERVICE.
RESTORING DIRECTORY MANAGEMENT ACCOUNT
In case your server crashes and you are not able to recover the Semaphor-LDAP config directory, you can install Semaphor-LDAP on another device using the username
and recovery-key
. This command will restore your local DB (and in future relases your configuration).
SEMAPHOR-LDAP.EXE CREATE-DEVICE --USERNAME DMAPXZJN7QKPR --RECOVERY-KEY USKONS7UYKDFATRPFMGSUACPHAVKUFC3
TROUBLESHOOTING
See Troubleshooting.
WINDOWS
Unlike in Unix/OSX, in Windows, Semaphor-LDAP consists of two separate executables:
-
semaphor-ldap-service.exe
: This is the server executable that runs the Semaphor-LDAP server as a Windows Service. You can use the executable just like any Windows Service application:SEMAPHOR-LDAP-SERVICE.EXE {INSTALL,START,STOP,RESTART}
-
semaphor-ldap.exe
: This is the command line client executable. E.g. to execute acheck-status
:SEMAPHOR-LDAP.EXE CHECK-STATUS
IMPORTANT: Both binares must be executed with a console in Administrator mode.
LOCAL CONFIGURATION DIRECTORY
Server configuration and local DBs are located under:
- Windows:
C:\Windows\System32\config\systemprofile\AppData\Local\semaphor-ldap\
- Linux:
~/.config/semaphor-ldap/
- OSX:
~/Library/Application Support/semaphor-ldap/