dev-4: openedge ® in an ldap world michael jacobs architect, progress openedge

DEV-4: OpenEdge in an LDAP World Michael Jacobs Architect, Progress OpenEdge

2007 Progress Software Corporation 2 DEV-4: OpenEdge in an LDAP World Agenda Introduction to LDAP Directory Service fundamentals Exploring the LDAP API LDAP Authentication Process Using LDAP from the ABL language

2007 Progress Software Corporation 3 DEV-4: OpenEdge in an LDAP World LDAP v3 Client-server wire protocol for accessing and managing objects in a Directory Service Originated from the X standards as DAP (Directory Access Protocol) and X.500 Directory Open standard supported by many Programming languages: C, Perl, Java, Software vendors Microsoft Active Directory Sun Novell OpenLDAP.org Lightweight Directory Access Protocol :

2007 Progress Software Corporation 4 DEV-4: OpenEdge in an LDAP World LDAP Directory Service Extensible, general purpose, object storage Used for storing frequently read, seldom written information Single unified view of distributed and replicate object storage across multiple servers Primary OpenEdge application uses Single point of user authentication Access user account information and role membership Synchronize user-accounts from LDAP A network accessible source of enterprise information:

2007 Progress Software Corporation 6 DEV-4: OpenEdge in an LDAP World Mastering Directory Services 1. LDAP object storage model 2. LDAP object name-space model 3. Connect and search for data objects 4. Extracting data objects information To effectively use LDAP, you need four basic skills :

2007 Progress Software Corporation 7 DEV-4: OpenEdge in an LDAP World Directory Service Storage Model Objects represent real-world concepts Users Organizations Servers, applications, Objects support an inheritance model Object definitions include The parent object OID (Object-IDentifier) Required & allowed data attributes person Parent: top OID: 1.2.3.4 Required:a, b Allowed:c, d organizationalPerson Parent:person OID: 1.2.3.5 Required:a, b, k Allowed:c, d, p inetOrgPerson Parent: organizationalPerson OID:1.2.3.6 Required:a, b, k, m Allowed:c, d, p, r Directories provide data storage as objects :

2007 Progress Software Corporation 8 DEV-4: OpenEdge in an LDAP World Directory Service Storage Model User accounts person, inetOrgPerson, user DNS domain server domainComponent (dc) A company & its organizational hierarchy organization (o) & organizationalUnit (ou) Some common Directory objects (objectClass) :

2007 Progress Software Corporation 9 DEV-4: OpenEdge in an LDAP World Directory Service Storage Model Objects store information in Attributes : An Attribute definition has a Full name Object identification (by OID) Data-type (by OID) An Attribute definition may have Alias name Description Suggested max value length An Attributes data-type definition has Object identification (by OID) Single/multi-values Encoding style (strings) Matching rules commonName OID:2.5.4.3 Type:directoryString Alias:cn directoryString: OID:1.3.6.1.4 Values:Multi-value Format:UTF-8 Match:caseIgnoreMatch

2007 Progress Software Corporation 10 DEV-4: OpenEdge in an LDAP World Common Attribute Data Types DirectoryString (UTF-8 character string) DistinguishedName Boolean Integer NumericString OID OctetString GeneralizedTime LDAP data types are defined by their OID description :

2007 Progress Software Corporation 11 DEV-4: OpenEdge in an LDAP World User Account Entry Attributes objectClass commonName (cn) telephoneNumber description locality (l) organization (o) userid (uid) mail country (c) sAMAccountName* userPrincipalName* mobile* lastLogon* displayName* userWorkstations* userSharedFolder* maxStorage* primaryGroupID* ... LDAP user accounts can contain a wealth of information : * Active Directory only Common user login attribute names

2007 Progress Software Corporation 12 DEV-4: OpenEdge in an LDAP World Directory Service Name-space Model Instances of objects are stored as entries Entries are arranged in a hierarchical treelike structure Every entry is a node in the tree and may contain data Any entry may have 0 to n children of any object type Each entry has a unique distinguished name (DN) All entries are located and referenced via its DN All children of an entry must have a unique relative distinguished name (RDN), which is relevant to its parents DN Every companys directory has its own unique design :

2007 Progress Software Corporation 13 DEV-4: OpenEdge in an LDAP World ou=people Directory Service Name-space Model ou=us ou=au ou=people ou=doc uid=robuid=barbuid=alice uid=bob uid=jim ou=it o=acme corp uid=alice, Sample Directory Information Tree model ou=doc,ou=people,ou=us,o=acme corp

2007 Progress Software Corporation 14 DEV-4: OpenEdge in an LDAP World Directory Service Entry Example Extend the schema with your own objects or attributes : dn: uid=alice,ou=doc,ou=people,ou=us,o=acme corp objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson objectclass: acmeEmployee uid: alice sn: Smith cn: Alice Smith cn: Alice F Smith telephonenumber: 510-555-1234 o: Acme Corp mail: [email protected] homedirectory: /home/asmith loginshell: /usr/local/bin/bash acmedepartment: documentation acmeemployeeid: 034678

2007 Progress Software Corporation 15 DEV-4: OpenEdge in an LDAP World LDAP Connections 1. Initialize an LDAP connection context a.server[:port][ server[:port] ] 2. Set the connection contexts network options a.LDAP protocol version b.SSL on/off c.Timeouts d. 3. Connect and authenticate* (bind) to the directory as a.Anonymous b.LDAP user account DN & secret (password) 4. Disconnect (unbind) when done with the service Four simple steps : * Use LDAP simple authentication

2007 Progress Software Corporation 16 DEV-4: OpenEdge in an LDAP World Searching a Directory Service LDAP searches require three components 1.The entrys DN of where to start the search [root] 2.An attribute filter to determine which entries to find and return 3.The scope of the search 1.Search root entry 2.Search roots child entries 3.Search root and its entire sub-tree LDAP searches return 0 N entries Optionally returns each returned entrys attributes LDAP searches are used to find and retrieve information : Tip: always check how many entries were returned

2007 Progress Software Corporation 17 DEV-4: OpenEdge in an LDAP World 1.Search-root ou=us,o=acme corp 2.Filter: (uid=barb) 3.Scope: sub-tree ou=people Searching a Directory Service ou=us ou=au ou=people ou=doc uid=robuid=barbuid=alice uid=bob uid=jim ou=it o=acme corp Search a sub-tree for Barbs entry :

2007 Progress Software Corporation 18 DEV-4: OpenEdge in an LDAP World Directory Service Security Model Discretionary access controls applied at run-time Controls assigned to stored entries & their attributes Allowed LDAP users & groups Allowed user/group actions (read, write, search, ) For example: Everyone can connect to LDAP without a user-id or password Certain accounts can search for entries Nobody can see a user-account entrys password Only user & administrator changes password Directory vendors supply security systems :

2007 Progress Software Corporation 19 DEV-4: OpenEdge in an LDAP World Retrieving LDAP Entries 1. Complete the LDAP search 2. Get the number of entries returned from the search 3. Use first - next operations to access individual entries 4. Get the entrys DN for later use LDAP entries are accessed dynamically :

2007 Progress Software Corporation 20 DEV-4: OpenEdge in an LDAP World Retrieving LDAP Attribute Values 1. Get the number of returned attributes 2. Use first - next functions to access individual attributes For each attribute: a.Get the number of attribute values b.Get the array of attribute values c.Loop through the array of attribute values to retrieve individual values d.Release the memory allocated by the LDAP API library in step b Entry attributes are accessed dynamically :

2007 Progress Software Corporation 22 DEV-4: OpenEdge in an LDAP World LDAP C Shared-library API Guidelines LDAP C functions all start with ldap_ LDAP has synchronous & asynchronous API calls ldap_bind() (asynchronous) ldap_bind_s() (synchronous) Windows OS ANSI & WIDE (Unicode) function calls ldap_bind_sA (ANSI) ldap_bind_sW (WIDE)

2007 Progress Software Corporation 23 DEV-4: OpenEdge in an LDAP World LDAP API Cheat-sheet OperationLDAP APIUse Initializationldap_initInitialize LDAP library ldap_set_option ldap_get_option Set/get connection options Connect (binding) ldap_bind_s ldap_unbind Connect/login user-id & logout/disconnect Searchldap_search ldap_count_entries Search for entries & return how many found Enumerate entries ldap_first_entry ldap_next_entry Enumerate returned list of searched entries ABL language LDAP API declarations at the end of the slide deck

2007 Progress Software Corporation 24 DEV-4: OpenEdge in an LDAP World LDAP API Cheat-sheet (cont) ClassLDAP APIUse Entry attributes ldap_get_dnGet returned entrys fully qualified DN ldap_first_attribute ldap_next_attribute Enumerate returned entrys attribute list Attribute values ldap_get_valuesReturn attributes list of [multiple] values ldap_count_valuesHow many attribute values returned ldap_value_freeFree LDAP memory allocation

2007 Progress Software Corporation 25 DEV-4: OpenEdge in an LDAP World LDAP Search Filter Examples All entries: (objectclass=*) All entries with userid starting with al (uid=al*) Operators: = ~= = & | ! Entry with object type user and user-id alice ( &(objectclass=person) (uid=alice) ) Entry with user-id alice and objectclass user or inetOrgPerson ( &(uid=alice) ( |(objectclass=person) (objectclass=inetOrgPerson) ) ) Can use wildcards and logical operators in filters : Tip: LDAP server implementations may not index all attributes, so some filters may not perform well.

2007 Progress Software Corporation 27 DEV-4: OpenEdge in an LDAP World LDAP User Authentication DN Nobody types in their full DN uid=alice,ou=doc,ou=people,ou=us,o=acme corp LDAP authentication code finds the users full DN for them Search for the users entry where the login-id matches one, or more, of the entrys attribute value login-id LDAP search filter alice (uid=alice) alice smith (cn=alice smith) asmith (sAMAccountName=asmith) Do I have to type in my full user account DN?

2007 Progress Software Corporation 28 DEV-4: OpenEdge in an LDAP World User-id prompts value used in LDAP search for users full DN Can allow multiple forms of login-ids, each a different user object attribute example: uid, cn, or e-mail Building LDAP Search Filters Map user account attributes to Login-id prompts : cSearchTpl = (&(objectclass=person)(|(uid=%s)(cn=%s)(mail=%s))). cSearchFilter = replace(cSearchTpl, %s, cLoginId). cSearchTpl = (&(objectclass=person)(uid=%s)). cSearchFilter = replace(cSearchTpl, %s, cLoginId).

2007 Progress Software Corporation 29 DEV-4: OpenEdge in an LDAP World LDAP Authentication Process After initializing and setting LDAP options : bind DN Bind with Anonymous LDAP user Bind with LDAP DN success N S F ldap_bind_s() Initialize Does Directory security require user DN to search? Use DN that has LDAP search privilege

2007 Progress Software Corporation 30 DEV-4: OpenEdge in an LDAP World Login: alice Password: ******* LDAP Authentication Process Search for users full DN success Searching for the users LDAP account : N Unbind session F V S ldap_search() ldap_unbind() Build search filter from users login-id Verify search returns exactly 1 (&(objectclass=person)(uid=%s)) Search sub-tree for matching entry

2007 Progress Software Corporation 31 DEV-4: OpenEdge in an LDAP World LDAP Authentication Process Get users attributes & check values success Validating the password and specific user entry attributes : N F C V ldap_search() ldap_first_attribute() ldap_next_attribute() ldap_get_values() ldap_free_value() N ldap_bind_s() Bind using user entrys full DN success F Execute a second ldap_search() of users full DN Login: alice Password: ******* Validates users password

2007 Progress Software Corporation 32 DEV-4: OpenEdge in an LDAP World LDAP Authentication Process Failure Success Cache Attribute Values Caching useful LDAP user account information : home directory surname given name country organization custom attributes CF Unbind from LDAP ldap_unbind() Do not authenticate on each user context switch

2007 Progress Software Corporation 34 DEV-4: OpenEdge in an LDAP World Use OS Native LDAP Shared Libraries All vendors support common LDAP options Identify and conditionalize vendor specific options Option support is relative to the Directory Service, not the LDAP client Find the operating systems LDAP shared library Solaris: /usr/lib/libldap.so Windows: wldap32.dll Linux: /usr/lib/libldap.so HPUX: Mozilla / OpenLDAP / Internet Express AIX: OpenLDAP* Tip: OpenLDAP is the most common cross-platform LDAP implementation, and is available on all these systems.

2007 Progress Software Corporation 35 DEV-4: OpenEdge in an LDAP World Working With a Native Shared Library Use a MEMPTR variable (mNULL) Set iPtrSize to hardwares address size (4 or 8 bytes) Fill MEMPTR with zeros define variable mNULL as MEMPTR no-undo. define variable iPtrSize as INTEGER INITIAL 4 no-undo. set-size(mNULL) = iPtrSize. do i = 1 to iPtrSize: put-byte(mNULL, i) = 0. Pass mNULL as INPUT parameter to LDAP function Native C language NULL parameter value :

2007 Progress Software Corporation 36 DEV-4: OpenEdge in an LDAP World Working With a Native Shared Library Extracting attribute value memory-pointers returned from ldap_search() ldap_get_values(, OUTPUT mAttrValues). iPtrIndex = 1. for i = 1 to iNumValues do: if (iPtrSize = 4) then do: set-pointer-value(mValue) = get-long(iPtrIndex, mAttrValues). end. else do: set-pointer-value(mValue) = get-int64(iPtrIndex, mAttrValues). end. iPtrIndex = iPtrIndex + iPtrSize. cAttrValue = get-string(mValue,1). end. Native C language array of memory-pointers :

2007 Progress Software Corporation 37 DEV-4: OpenEdge in an LDAP World In Summary LDAP is a popular choice for managing distributed network services Used often as a single-point of user authentication LDAP support is achievable from the OpenEdge ABL

2007 Progress Software Corporation 38 DEV-4: OpenEdge in an LDAP World For More Information, go to PSDN White paper: LDAP User Authentication in an OpenEdge ABL Environment Internet references: www.openldap.org msdn.microsoft.com docs.sun.com www.iana.org/assignments www.alvestrand.no/objectid/ Reference books: LDAP Programming Directory-Enabled Applications with Lightweight Directory Access Protocol

2007 Progress Software Corporation 39 DEV-4: OpenEdge in an LDAP World Relevant Exchange Sessions DB-14: OpenEdge Database Run-time Security Revealed DB-19: OpenEdge Authentication without the _User Table DB-8: Jump-starting Your OpenEdge Auditing Solution ARCH-4: A Statefull Application in a Stateless World

2007 Progress Software Corporation 40 DEV-4: OpenEdge in an LDAP World Questions?

2007 Progress Software Corporation 41 DEV-4: OpenEdge in an LDAP World Thank you for your time

2007 Progress Software Corporation 42 DEV-4: OpenEdge in an LDAP World LDAP API Session Functions (Binding) Establishing LDAP sessions : PROCEDURE ldap_init EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_cServerHost AS CHAR. DEFINE INPUT PARAMETER p_mPort AS LONG. DEFINE RETURN PARAMETER p_mLDAPContext AS MEMPTR. END PROCEDURE. PROCEDURE ldap_set_option EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_iLDAPOption AS LONG. DEFINE INPUT PARAMETER p_mOptionValue AS MEMPTR. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. PROCEDURE ldap_bind_s EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_cBindUserDN AS CHAR. DEFINE INPUT PARAMETER p_cBindUserPwd AS CHAR. DEFINE INPUT PARAMETER p_iAuthMethod AS LONG. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. Configure server host & port Set session options Connect & authenticate user-id

2007 Progress Software Corporation 43 DEV-4: OpenEdge in an LDAP World LDAP API Search Functions PROCEDURE ldap_search_s EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_cSearchRoot AS CHAR. DEFINE INPUT PARAMETER p_iScope AS LONG. DEFINE INPUT PARAMETER p_cSearchFilter AS CHAR. DEFINE INPUT PARAMETER p_mAttrArray AS MEMPTR. DEFINE INPUT PARAMETER p_iAttrsOnly AS LONG. DEFINE OUTPUT PARAMETER p_mLDAPMessage AS HANDLE TO LONG. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. PROCEDURE ldap_count_entries EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. Search for LDAP entries How many entries were found? Establishing LDAP sessions :

2007 Progress Software Corporation 44 DEV-4: OpenEdge in an LDAP World LDAP API Entry Functions PROCEDURE ldap_first_entry EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE RETURN PARAMETER p_mLDAPEntry AS HANDLE TO LONG. END PROCEDURE. PROCEDURE ldap_get_dn EXTERNAL "libldap.so" PERSISTENT. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE RETURN PARAMETER p_mAttrName AS MEMPTR. END PROCEDURE. PROCEDURE ldap_next_entry EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE RETURN PARAMETER p_mLDAPEntry AS HANDLE TO LONG. END PROCEDURE. Get the first returned LDAP entry Get entrys fully qualified DN Enumerate remaining LDAP entries

2007 Progress Software Corporation 45 DEV-4: OpenEdge in an LDAP World LDAP API Attribute Functions PROCEDURE ldap_first_attribute EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE OUTPUT PARAMETER p_mCtxPtr AS MEMPTR. DEFINE RETURN PARAMETER p_mAttrName AS MEMPTR. END PROCEDURE. PROCEDURE ldap_next_attribute EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE INPUT PARAMETER p_mCtxPtr AS MEMPTR. DEFINE RETURN PARAMETER p_mAttrName AS MEMPTR. END PROCEDURE. Get the first LDAP entry attribute Enumerate remaining attribues

2007 Progress Software Corporation 46 DEV-4: OpenEdge in an LDAP World LDAP API Attribute Value Functions PROCEDURE ldap_get_values EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_mLDAPMessage AS MEMPTR. DEFINE INPUT PARAMETER p_mAttrName AS MEMPTR. DEFINE RETURN PARAMETER p_mAttrValues AS MEMPTR. END PROCEDURE. PROCEDURE ldap_count_values EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mValueMemory AS MEMPTR. DEFINE RETURN PARAMETER p_iCount AS LONG. END PROCEDURE. PROCEDURE ldap_value_free EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mValueMemory AS MEMPTR. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. Get pointer to attribute value list How many values in the list FREE LDAP API MEMORY

2007 Progress Software Corporation 47 DEV-4: OpenEdge in an LDAP World LDAP API Session Function (Unbinding) PROCEDURE ldap_unbind_s EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. End LDAP session

2007 Progress Software Corporation 48 DEV-4: OpenEdge in an LDAP World Error Handling PROCEDURE ldap_get_option EXTERNAL "libldap.so" PERSISTENT CDECL. DEFINE INPUT PARAMETER p_mLDAPContext AS MEMPTR. DEFINE INPUT PARAMETER p_iLDAPOption AS LONG. DEFINE INPUT PARAMETER p_mOptionValue AS MEMPTR. DEFINE RETURN PARAMETER p_iStatus AS LONG. END PROCEDURE. Get LDAP information p_iLDAPOption LDAP_OPT_ERROR_NUMBER[0x31] LDAP_OPT_ERROR_STRING[0x32]

2007 Progress Software Corporation 49 DEV-4: OpenEdge in an LDAP World LDAP API Session API Parameters ldap_set_option : LDAP-Option conform to productions configuration LDAP_OPT_AREC_EXCLUSIVE[0x98] LDAP_OPT_SSL [0x0a] LDAP_OPT_TIMELIMIT [0x04] LDAP_OPT_PROTOCOL_VERSION* [0x11] ldap_set_option : Option-Value for setting & discovering configuration values LDAP_OPT_ON [0x01] LDAP_OPT_OFF [0x00] LDAP_VERSION3* [0x03] LDAP connection API notes : *Required