Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Merged branch "DOC0001296" into parent

The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry-standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network.

LDAP integration allows you to connect the instance to LDAP or AD server and using catalog service server with LDAP (for example, Active Directory) and user it as a source of the user data. It provides the ability to connect to a directory service storing the authentication data, such as usernames, passwords, user home directories used for keeping business and other data, etc. The global objective of the LDAP engine is importing users into the system. And through this, synchronization with various corporate services can be achieved, and one account can be used to authorize in all corporate services, such as email, website, VoIP, and so on.

Image RemovedImage Added

The RDN (relative distinguished name) is the attribute defining the search directory, like this: dc=instance,dc=com

In this client-server infrastructure scheme, the SimpleOne instance has to be a client connecting to the LDAP server.

The system synchronizes with the LDAP server in two ways:

  • via the Schedule Jobs (automatic) – scheduled script defining periods of synchronization (for example, every 3 hours). See the Scheduled Script article to learn more.
  • users can authorize with user.ldap_autoprovision property that enables automatic creation of users in the User table in case the user is created in LDAP but not created on the instance.

    Note

    When a user that has an account in the LDAP service catalog, but has not in the system, independently attempts to authorize, a user record is automatically created on the instance with a generated email in the format {random string of 10 characters}@simple.test.

    • If user accounts are created by importing via LDAP, set
    via the Autoprovision (triggered by logging in) – when user logs in, the system updates the requested data. Configure this way of synchronization via tip
    • the user.ldap_autoprovision property to false.
    • If autoprovision is necessary, then manually update the fields in the user record to the correct values.

    You can also use third-party authorization services on your instance. See the Single Sign-On article to learn more.

    The system synchronizes with the LDAP server only via the Schedule Jobs – scheduled script that defines periods of synchronization (for example, every 3 hours). See the Scheduled Script article to learn more. Thus, the data is not updated automatically at authorization or other operations.

    Establish an LDAP connection


    To establish the connection between your SimpleOne instance and the LDAP server, complete the following steps:

    1. Specify the LDAP server.
    2. Define the LDAP URL.
    3. (optional) Add a certificate to create a secure LDAP connection.
    4. Set up the LDAP Definitionsettings.
    5. Check settings.
    6. (Optionaloptional) Data import.

    Additional tools for setting up LDAP connection:

    Specify an LDAP server
    Anchor
    LDAP server
    LDAP server


    To configure an LDAP connection, complete the steps below:

    1. Navigate to System LDAP → LDAP Servers.
    2. Click New and fill in the fields.
    3. Click Save to or Save and exit to apply changes.
    4. Copy the current record ID.

    LDAP Server form fields

    FieldMandatoryDescription
    NameYEnter the server name.
    Root directoryY

    Enter the RDN of the search directory.

    Example: dc=instance,dc=ru

    ActiveNSelect this checkbox to make the server active.
    UsernameYSpecify the username authenticating the LDAP connection.
    PasswordNSpecify the server password.


    Info

    If the RDN attribute is not specified, then the LDAP server will attempt to reach the server root directory during the authorization process. If the user logging in is not authorized to access this directory, the authorization process will be interrupted.

    Define an LDAP URL
    Anchor
    LDAP url
    LDAP url

    Sometimes, customer infrastructure may contain more than one LDAP server, for example, as a standby (reserve) server. In this case, you may need to specify some particular server used for authorization by arranging the URL order. If you have more than one server, create a separate LDAP URL for each of them

    In order to successfully connect to the server, the server and the current SimpleOne instance must be available for connection. Apart from that, the port to which you try to connect must be open.

    The account used for connection must belong to the Domain User group. It means that the user must have the permission to read the catalog.

    To create a URL,complete the steps below:

    1. Navigate to System LDAP → LDAP URL.
    2. Click New and fill in the fields.
    3. Click Save or Save and Exit to apply the changes.
    LDAP Definition
    1. exit to apply the changes.

    LDAP URL form fields

    FieldMandatoryDescription
    URLY

    Enter the LDAP/LDAPS URL there. The SSL-certificate checks the domain, not IP-address, so the domain is used for connection.

    Example for LDAP:

    ldap://123.456.1.12:363

    Example for LDAPS:

    ldaps://dc02-ds1.simpleone.ru:636

    ActiveNSelect this checkbox to make the URL active.
    OrderNSpecify the order of this URL if there are more than one similar items. In this case, they will be processed in ascending order.
    Operational statusN

    State of the LDAP connection. Available options:

    • Ready to connect – backup server is set up and ready to be used.
    • Connected – connection is established.
    • Disconnected – the system does not synchronize with the server.
    • Error – something went wrong. Check LDAP Logs.
    ServerYSpecify the appropriate LDAP server.

    Add a certificate
    Anchor
    create an LDAP certificate
    create an LDAP certificate


    If you need to establish a secure LDAP connection over SSL or LDAPS via port 636, provide the SSL certificate. If you do not have a valid certificate, the LDAP connection will be insecure. In this case, use port 389 (TCP/UDP).

    To add an LDAP certificate, complete the steps below:

    1. Navigate to LDAP → Certificates.
    2. Click New to create a new record.
    3. Attach the SSL-certificate file.

      Info
      titleCertificate requirements
      • To work correctly, the certificate must be a root one (CA).
      • The supported PEM (Privacy Enhanced Mail) formats have the following extension: .pem, .crt, .cer.
      • Files must be Base64 encoded and start with "----- BEGIN CERTIFICATE -----" and end with "----- END CERTIFICATE -----".


    4. Specify the Name of the certificate and select the Active checkbox. You can also add Short description. The values for other fields are taken from the attached file.
    5. Click Save or Save and exit to apply the changes.

    Certificate form fields

    Field

    Mandatory

    Description

    NameYSpecify the record name to identify the certificate in the list.
    SubjectNThe certificate attributes. This field is automatically populated based on the provided certificate data. For more information about these attributes, see the RFC 5280 documentation.
    IssuerNThe certificate issuer. This field is automatically populated based on the provided certificate data. 
    File pathN


    Note

    This field is not used.


    Short descriptionNAdd a brief description for the record.
    ActiveNSelect this checkbox to activate the certificate.
    Valid fromNThe date from which this certificate is valid. This field is automatically populated based on the provided certificate data. 
    Valid toNThe date until which this certificate is valid. This field is automatically populated based on the provided certificate data. SimpleOne does not validate the value of this field but the connection will not be established if the certificate is expired.


    Tip

    You can see the list of added certificates from the LDAP Server record form. To do so, click Certificates list.

    LDAP settings 
    Anchor
    LDAP definition
    LDAP definition


    After you configured an LDAP server and an LDAP URL and performed all necessary customer infrastructure preparations, set up an LDAP definitionsetting.

    If you completed the steps above and performed all necessary customer infrastructure preparations, proceed to setting up an LDAP setting.

    To configure the LDAP definition, perform the following stepssetting, complete the steps below:

    1. Navigate to System LDAP → LDAP DefinitionSettings.
    2. Click New and fill in the fields.
    3. Click Save or Save and Exitexit to apply the changes.

    Excerpt Include
    LDAP Import Source
    LDAP Import Source
    nopaneltrue

    You can check the LDAP structure by clicking the Browse LDAP on the corresponding LDAP Server record.

    Image Modified

    Check settings 
    Anchor
    check LDAP connection
    check LDAP connection


    Make sure Ensure that the connection is set up by performing the following steps:

    1. Navigate to System LDAP → LDAP Servers.
    2. Open the record you need.
      1. Click Test connection to check the first URL connection defined by the order.
      If the connection is fine, the Successfully connected message appears.
      1. Click Test all connections to check all defined connections.
      If the connections are fine, the All connections are checked message appears.

    If an error is thrownoccurs, check LDAP Log records.

    LDAP

    Import

    import
    Anchor
    LDAP import
    LDAP import


    Import all necessary data from your LDAP server to the instance. 

    To complete the data import using LDAP, set up the following system elements:

    • LDAP DefinitionSettings – specifies filters for retrieving data from a defined LDAP table.
    • Import Source – loads row data for further processing and transformation.

    The scheme below illustrates the process of data import from an LDAP server.

    Image RemovedImage Added

    See the Importing using LDAP Import Source article to learn more.


    Example of the integration with AD


    The "out-of-the-box" solution contains an example of the connect with an connection to the Active Directory (AD) service. 

    Check out the examples mentioned below before setting up the LDAP import on an instance. The settings of the examples are protected from changes. In the hamburger menu of each record, click Make a copy to copy the example setting and change their values.

    The following records are created and configured:

    • the Demo_Active_Directory LDAP Server with the LDAP URL example. In your copy, specify the parameters of the server.
    • the SimpleOneCourses1 and SimpleOneCourses2 LDAP Settings. Use one of these definitions as an example to create a working connection with an the AD service.

      Expand
      titleThe description of the field values


      FieldValueDescription
      Filter


      Section


      Column
      width50%


      Panel
      titleSimpleOneCourses1

      (&

       (objectClass=person)

      (sn=*)

      )



      Column
      width50%


      Panel
      titleSimpleOneCourses2

      (&

       (objectClass=person,top)

      (sn=*)

      )




      The defined filter selects user records with any username to import from the AD service. 
      Query FieldsAMAccountNameThe field that is used for connecting with the AD and querying the records.
      Attribute Listsamaccountname,sn,givenname,distinguishedname,msDS-cloudExtensionAttribute6,telephonenumber, mobile,mail,manager,company,useraccountcontrol,thumbnailphotoThe attributes the LDAP query returns.



    • the LDAP Users Import Source. Use one import source for the same LDAP settings.
    • the Daily Import SimpleOne Employees and Daily Import SimpleOne Employees 2 scheduled imports. The AD data is imported daily at a specific time. Use one of the imports as an example to create your scheduled import.
    • the Daily Deletion of Obsolete Import Sets scheduled script. The script deletes inactive import sets. When an import set is deleted, a cascading delete deletion occurs for the Import Set column of the Import Set Row table.

    To connect and import the users from the AD service, complete the following steps:

    1. Create a local pack in the Simple application for the LDAP import settings.
    2. Create copies of records mentioned above and set up the LDAP integration by changing the field values to the required ones.
    3. Click Test connection in the LDAP Server record. If the connection is established successfully, click Browse LDAP to check the LDAP structure.
    4. After you checked the structure, go to the LDAP Setting you need and open the related import source.
    5. (optional) Click Test Load (20 records) to create a test import set.
    6. Click Load all records.
    7. Click View Transform Map to create a Transform Map record. The Target Table value should match the value of the Table field in the LDAP Settings record.
    8. On the Transform Map create Field Maps through the related list. The Login and Email field map records should have the selected Coalesce checkbox. The parameter defines the fields of the target table that will be used to search for the records based on the imported data. If a record is found in the target table, it will be updated. Otherwise, a new record will be created.
    9. Go back to the Import Source record and open the Import Set record via the related list.
    10. Click Transform to import data from the AD service. 
    11. Configure the copy of the Daily Import SimpleOne Employees scheduled import. Add the reference to the created Import Source.
    12. Configure the copy of the Daily Deletion of Obsolete Import Sets scheduled script and select the Active checkbox. Copy the ID of the Import Source to the import_source_id variable of the script.

    LDAP

    Log 

    log
    Anchor
    LDAP log
    LDAP log


    If an error occurred in the system, you can check the log messages to find the cause. In the LDAP Log, you can find records of failed authorization attempts or attempts to bypass authorization policy. In fact, all these messages are recorded into the Main Logs (sys_log) table.

    To see the LDAP logs, navigate to System LDAP → LDAP log.

    LDAP

    System Properties AnchorLDAP system propertiesLDAP system properties

    The following properties configure LDAP abilities on the client-side:

    Property nameTypeDefault valueDescription

    user.authorization_when_no_ldap_connection

    BooleantrueEnables authorization if there's no LDAP connection.

    user.ldap_authentication

    BooleantrueEnables or disables LDAP authentication.

    user.ldap_autoprovision

    BooleantrueEnables the automatic creation of users in the User table if there is no such record on the instance.

    Log form fields

    FieldDescription
    SourceDisplays the source from where this log record comes from (LDAP Authorization or LDAP Autoprovision, as an example).
    MessageThe log record message text.
    Level

    This field specifies the error level. Available options:

    • Info
    • Error
    • Warning
    • Debug
    UsernameReference to the user initiated this record creation.

    LDAP system properties
    Anchor
    LDAP system properties
    LDAP system properties


    Some LDAP features can be configured on the client side using system properties. Available properties can be found in the LDAP Properties article.

    Table of Contents
    absoluteUrltrue
    classfixedPosition

    Panel
  • LDAP Properties
  • Scheduled Script
  • Single Sign-On
  • Importing using LDAP