====== EOS User Authentication via Active Directory ======

This page describes how to synchronize Orbit Users and User Groups with Microsoft Active Directory.

===== Concepts =====

  * [[https://en.wikipedia.org/wiki/Single_sign-on|Wikipedia, Single sign-on]]
  * [[https://en.wikipedia.org/wiki/Active_Directory|Wikipedia, Active Directory]]

In order to synchronize Orbit and a corporate Active Directory, the proper settings for the Orbit Enterprise Service must be defined. \\

=== Users and User groups ===

It is up to the customer to decide which user groups will be able to access the Orbit software, and which users will be assigned to each usergroup. Before customizing Orbit, these usergroups must be created in the Active Directory. \\

 Active directory existing user groups must be replicated in the EOS. From several groups existing in a corporate Active Directory, only the ones replicated in the EOS will be able to access the Server or the Orbit Clients. \\

At least two groups from the Active Directory must exist in Orbit also:
  * Administrators - only users belonging to this Active Directory group will be able to access the EOS
  * Users - users from this usergroup will be able to access in the Orbit Clients the workspaces created for them by the administrators.

To create and manage Usergroups in orbit see: [[180:server:console:users|]]

These two usergroups are mandatory. For different tasks, several other user groups may be created, permissions can be granted for each of them, see: [[180:server:eos:roles_permissions|]]

=== Workspaces ===

Different workspaces must be created for all usergroups created in the User and Usergroups tab. Accessibility to these workspaces must be assigned to the prior created usergroups. 

To create and manage the Workspaces see: [[180:server:console:workspaces|]]

When synchronizing Orbit with Active Directory, one usergroup can access only one workspace, and one workspace can be associated with only one usergroup.

The result of the AD synchronization will be the following:
  * The EOS will be accessible only to administrators, only the AD user name will be needed for login
  * The clients installed on different computers will start without login, only if a person from the AD usergroup is logged on that PC

===== Configurations =====

Configurations for using Active Directory requires a well prepared EOS Console Users & User Groups and Workspace setup. \\
After completing the EOS Console configurations, Stop the Orbit EOS Service, edit the described configuration files and Restart the Orbit EOS Service to take advantage of the updated Active Directory configurations, see [[180:server:eos:service|]].

=== EOS Console ===

  - Create a new usergroup in EOS, for the EOS administrators, name should be identical to an usergroup from the Active Directory
  - Create one or several usergroups in EOS, that will have access to the Orbit Clients, name should be identical to  usergroups from the Active Directory
  - Create new workspaces for all Usergroups created in the previous steps.

the file "\server\program\services\system_user\usergroups.ini" should look like: 

<code>
#
# Usergroups
#
GROUPS=
 GROUP=
  NAME=GRP_APPL_GRIP_BEHEER             
  DISPLAYNAME=GRP_APPL_GRIP_BEHEER       
  USERS=
 GROUP=
  NAME=GRP_APPL_GRIP_TEST                
  DISPLAYNAME=GRP_APPL_GRIP_TEST
  USERS=
#<EOF>#
</code>

== NAME ==
Name of the administrator group ( first one) or name of a user group , preexistent in your AD. Name is formed from prefix and name ( eg : GRP_APPL_GRIP- prefix, TEST - name)

=== LDAP  ===

Configure the Lightweight Directory Access Protocol: \\
''<Orbit Server Installation>/server/program/config/active_directory.<AD_Name>.ini''

  * <AD_Name> : the name of the Active Directory 

== Example ==

<code>
INITIAL_CONTEXT_FACTORY         com.sun.jndi.ldap.LdapCtxFactory
PROVIDER_URL                    ldap://IpAddress:Port
SECURITY_AUTHENTICATION         simple
SECURITY_PRINCIPAL              MyDomain\\Administrator
SECURITY_CREDENTIALS            Password
LIST_USERS_SEARCH_BASE          DC=<MyDomain>,DC=<LOCAL>
LIST_USERS_SEARCH_FILTER        (&(objectClass=user)(objectCategory=person))
LIST_COMPUTERS_SEARCH_BASE      DC=<MyDomain>,DC=<LOCAL>
LIST_COMPUTERS_SEARCH_FILTER    (&(objectClass=user)(objectCategory=computer))
LIST_GROUPS_SEARCH_BASE         DC=<MyDomain>,DC=<LOCAL>
LIST_GROUPS_SEARCH_FILTER       (objectCategory=group)
</code>

== PROVIDER_URL ==

URL of LDAP service
389 default port 

== SECURITY_AUTHENTICATION ==

Access mechanism, options : 

  * ''none'' : an anonymous login
  * ''simple'' : a standard 'plaintext' login (default)
  * ''GSSAPI'' : SASL mechanism (not yet supported)

== SECURITY_PRINCIPAL ==

The name of a user with access to the AD, options : 

  * ''Administrator@mydomain.com'' : Windows 2000 and later
  * ''CN=Administrator,CN=Users,DC=mydomain,DC=com'' : AD syntax
  * leave blank for anonymous

== SECURITY_CREDENTIALS ==

Security credentials of user with access to the AD \\
  * Leave blank for anonymous

== LIST_USERS_SEARCH_BASE ==

Search-base for listing all users :
  * ''DC=MYDOMAIN,DC=COM''

== LIST_USERS_SEARCH_FILTER ==

Filter for listing all users
  * ''(&(objectClass=user)(objectCategory=person))''

== LIST_COMPUTERS_SEARCH_BASE == 

Search-base for listing all computers : 
  * ''DC=MYDOMAIN,DC=COM''

== LIST_COMPUTERS_SEARCH_FILTER ==

Filter for listing all computers
  * ''(&(objectClass=user)(objectCategory=computer))''

== LIST_GROUPS_SEARCH_BASE ==

Search-base for listing all user-groups
  * ''DC=MYDOMAIN,DC=COM''

== LIST_GROUPS_SEARCH_FILTER ==

Filter for listing all user-groups
  * ''(objectCategory=group)''

=== Orbit User Service ===

Configure the Orbit User Service: \\
''<Orbit Server Installation>/server/program/services/system_user/service.ini''

== Example == 

<code>
Services=
 Service=
  Name=UserService
  ClassName=com.orbitgis.services.user.UserService
  Configuration=
   StoreType=ActiveDirectory
   ActiveDirectoryName=active_directory.<AD_Name>
   ActiveDirectoryGroupPrefix=<AD_Prefix>
   AdministratorsGroupName=<AD_Name><AD_User_Group_Administrators>
</code>

== ActiveDirectoryName ==

Same name as the filename containing the LDAP configuration, see step 1

== ActiveDirectoryGroupPrefix ==


Prefix of the usergroup created in step 1

== AdministratorsGroupName ==

Name of the administrator usergroup from step 1

==== Desktop Client Login Configuration ====

Configure the Desktop Client Login: \\
''<Orbit Server Installation>/client/program/login.ini''

== Example ==

<code>
ServerLocation   dox://<Orbit_Server>:<Port_Dox>/
autologin	 true
UserName	 <USERNAME>
Password         
GroupName        
WorkspaceName    
Autologin        
</code>

== ServerLocation ==

Location of the Orbit Server installation, by default port 1100

== UserName ==

The use of <USERNAME> comes down to the windows login name will be used as a username. This name will be searched in the AD for the groups this user belongs. Next, there's a search for the first workspace that provides access to at least one of the groups to which the user belongs.