sp_ldapadmin

Creates or lists an LDAP URL search string, verifies an LDAP URL search string or login, or specifies the access accounts and tunable LDAPUA-related parameters.

Syntax

sp_ldapadmin command [, option1 [, option2]]

Valid command [, option1 [, option2]] options are:

	'set_primary_url', 'url'
	'set_secondary_url', 'url'
	'set_dn_lookup_url', 'url'
	'set_secondary_dn_lookup_url', 'url'
	'set_access_acct', 'distinguished_name', 'password'
	'set_secondary_access_acct', 'distinguished_name', 'password'
	'set_failback_interval', time_in_minutes
	'suspend', {'primary' | 'secondary'}
	'activate', {'primary' | 'secondary'} 
	'list'
	'list_urls'
	'list_access_acct'
	'check_url', 'url'’
	'reinit_descriptors'
	'check_login', 'name'
	'set_timeout', timeout_in_milli_seconds
	'set_log_interval', log_interval_in_minutes
	'set_num_retries', num_retries
	'set_max_ldapua_native_threads', max_ldapua_native_threads
	'set_max_ldapua_desc', max_ldapua_desc
	'set_abandon_ldapua_when_full', {true|false}
	'starttls_on_primary', {true|false}
	'starttls_on_secondary', {true|false}
	'help’

Parameters

set_primary_url, ‘ldapurl’ – creates the specified search string ldapurl. Exactly one primary search string can be created.
The syntax for ldapurl is:
```
ldapurl::=ldap://host:port/node?attributes?base | one | sub?filter
```
where:
- host – is the host name of the LDAP server.
- port – is the port number of the LDAP server.
- node – specifies the node in the object hierarchy at which to start the search.
- attributes – is a list of attributes to return in the result set. Each LDAP server may support a different list of attributes.
- base – qualifies the search criteria, specifiying a search of the base node.
- one – qualifies the search criteria. base specifies a search of the base node; one specifies a search of node and one sublevel below node; and sub specifies a search of node and all node sublevels.
- sub – specifies a search of node and all node sublevels.
- filter – specifies the attribute or attributes to be authenticated. The filter can be simple, such as “uid=*,” or compound, such as “(uid=*)(ou=group).” The syntax is LDAP server dependent and uses a wildcard (*) to describe the login name.
set_secondary_url, { ‘ldapurl’ | null } – creates the specified secondary search string ldapurl or no secondary search string. Exactly one secondary search string can be created.
set_dn_lookup_url, distinguished_name_url – uses the searched distinguished name algorithm to authenticate the login with an LDAP directory server when you set set_dn_lookup_url to a non-NULL value.
distinguished_name_url has a maximum length of 255 characters and is used to search for a distinguished name associated with the login name.
set_secondary_dn_lookup_url, distinguished_name_url – creates the specified secondary distinguished name algorithm to authenticate the login with an LDAP directory server when you set set_secondary_dn_lookup_url to a non-NULL value.
distinguished_name_url has a maximum length of 255 characters and is used to search for a distinguished name associated with the login name.
set_access_acct, account_distinguished_name, account_password – specifies the identity and password that the SAP ASE server uses to conduct searches and other read-only adminstrative actions. The identity is in the form of a distinguished name. Use account_distinguished_name to authenticate this user with the LDAP server. Both account_distinguished_name and account_password are limited to 255 characters each.
set_secondary_access_acct, account_distinguished_name, account_password – creates the secondary identity and password that the SAP ASE server uses to conduct searches and other read-only adminstrative actions. The identity is in the form of a distinguished name. Use account_distinguished_name to authenticate this user with the LDAP server. Both account_distinguished_name and account_password are limited to 255 characters each.
set_failback_interval – sets the interval at which the SAP ASE housekeeper utility checks for failed LDAP servers.
suspend, {'primary' | 'secondary'} – suspends the use of a primary or secondary URL for authentication.
activate, {'primary' | 'secondary'} – enables using the set of primary or secondary URLs for authentication.
list – displays LDAP search strings.
list_urls – displays LDAP URL search strings.
list_urls – displays LDAP URL search strings.
list_access_acct – displays the LDAP access account distinguished name set.
check_url, ‘ldapurl’ – verifies an LDAP URL search string. Can also verify the existence of a user account, but it does not authenticate the user.
check_login, login_name – verifies a user account for the existing LDAP URL search strings. It does not authenticate the user.
'set_timeout' timeout_in_milli_seconds – sets the time in milliseconds that the SAP ASE server waits for a response from the LDAP server before abandoning the authentication request.
The default value for set_timeout is 10,000 milliseconds (10 seconds.) Valid values are between 1 and 3,600,000 (one hour.)
'set_log_interval', log_interval – sets the log interval, specified in minutes, from 0 to 480 minutes. The default value is 3 minutes. 0 implies that all messages are printed.
set_num_retries, num_retries – sets the number of retries attempted after transient errors. The valid range for set_num_retries is 1 – 60, and the default is 3.
'set_max_ldapua_naptive_threads, max_ldapua_native_threads – sets the maximum number of native threads that can be running concurrently in an engine processing an LDAP authentication request.
The minimum value of set_max_ldapua_native_threads is 1. The maximum value is max native threads minus number of dump threads as specified using sp_configure. The default value is the same as the maximum value.

sp_configure ensures that max native threads is sufficient for set_max_ldapua_native_threads and the value of the configuration parameter number of dump threads.
set_max_ldapua_desc, max_ldapua_desc – sets the maximum number of LDAP descriptors per engine. The valid range for set_max_ldapua_desc is 1 – 20, and the default is 20.
set_abandon_ldapua_when_full', {true | false} – allows you to seek alternative means of LDAP user authentication when the native threads per engine capacity is exceeded.
When no more threads are available, the request is abandoned if set_abandon_ldapua_when_full is set to true. If enable ldap user auth is set to 1, the client is authenticated using SAP ASE syslogins. If enable ldap user auth is set to 2, the client login fails.

If set_abandon_ldapua_when_full is set to false, the authentication request is blocked until the LDAP descriptor can accept new authentication requests.
help – displays usage information for sp_ldapadmin.
reinit_descriptors – Unbinds all established LDAP server descriptors, and reinitializes the LDAP user-authentication subsystem. The syntax is:
```
sp_ldapadmin 'reinit_descriptors'
```
Whenever a certification authority trusted root file is modified, the system security officer must use reinit descriptors to reinitialize LDAP user authentication. For complete documentation, see sp_ldapadmin in the Reference Manual: Procedures.
set_log_interval, log_interval – sets the time for the error message logging interval, in minutes. The valid range for set_log_interval is 0 – 480, and the default is 3.

Examples

Example 1 – Creates an LDAP URL search string for the LDAP SunONE Directory Server.
```
sp_ldapadmin set_primary_url,'ldap://voyager:389/
    ou=People,dc=MyCompany,dc=com??sub?uid=*'
```
The search string identifies a directory server listening on host name “voyager,” port number 389 (the default LDAP protocol port), the base node to begin the search is within organizational unit (ou) “People,” and the domain is “MyCompany.com.” It returns all attributes that match the filter uid=*. The SAP ASE server replaces the wildcard with the SAP ASE login name that is to be authenticated.
Example 2 – Creates an LDAP URL search string defined in OpenLDAP 2.0.25 using the criteria described in Example 1.
```
sp_ldapadmin set_primary_url,'ldap://voyager:389/
    dc=MyCompany,dc=com??sub?cn=*'
```
Example 3 – Sets the secondary LDAP URL search string to null, indicating no failover and no secondary LDAP server.
```
sp_ldapadmin set_secondary_url, null
```

Example 4 – Creates an LDAP URL search string with a compound filrer.

sp_ldapadmin set_primary_url, 'ldap://voyager:389/
    ou=people,dc=siroe,dc=com??sub?(&(uid=*) (ou=accounting))

Example 5 – Uses the default Microsoft Active Directory schema found on Windows 2000 controllers:
```
1> sp_ldapadmin set_access_acct, 'cn=aseadmin, cn=Users, dc=mycompany, 
      dc=com', 'aseadmin secret password'
2> go

1> sp_ldapadmin set_dn_lookup_url,
    'ldap://mydomainhostname:389/cn=Users,dc=mycompany,dc=com?
     distinguishedName?sub?samaccountname=*' 
2> go

1> sp_ldapadmin set_primary_url,'ldap://mydomainhostname:389/'
2> go
```
The “aseadmin” username is added to the Active Directory server and granted read access to the trees and objects where users are found. The LDAP attribute specified by distinguishedName is obtained and used to authenticate the user. The filter specifies a search on attribute samaccountname=*; the * wildcard is replaced with the name from the SAP ASE login record.

For example, “samaccountname=jqpublic” returns DN attribute “distinguishedName” with value “cn=John Q. Public, cn=Users,dc=mycompany, dc=com” to the SAP ASE server. The SAP ASE server uses this string to bind to ldap://mydomainhostname:389. If the bind is successful, authentication succeeds.
Example 6 – Sets the maximum number of native threads to 12:
sp_ldapadmin 'set_max_ldapua_native_threads', '12'
Example 7 – sets the time that the SAP ASE server waits for a response from the LDAP server before abandoning the authentication request to 25,000 milliseconds:
```
sp_ldapadmin, 'set_timeout', '25000'
```
Example 8 – Disables the authentications requests until the LDAP descriptor can accept new authentication requests:
```
sp_ldapadmin 'set_abandon_ldapua_when_full', 'false'
```

Example 9 – Displays the current LDAP values:

sp_ldapadminPrimary:
URL:                  'ldap://linuxpuneeng1:50917/'
DN Lookup URL:
'ldap://linuxpuneeng1:50917/dc=sybase,dc=com??sub?uid=*'
Access Account:      'cn=Directory Manager'
Active:              'TRUE'
Status:              'READY'
Secondary:
URL:                 ''
DN Lookup URL:       ''
Access Account:      ''
Active:              'FALSE'
Status:              'NOT SET'
Timeout value:       '5000' milliseconds
Log interval:        '1' minutes
Number of retries:   '3'
Maximum LDAPUA native threads per Engine: '400'
Maximum LDAPUA descriptors per Engine: '3'
Abandon LDAP user authentication when full: 'false'(return status = 0)

Usage

There are additional considerations when using sp_ldapadmin:

The LDAP vendor determines the syntax of the search string. In all cases, the search string specifies the attribute name that uniquely identifies the user in the form “attribute=wildcard” as in “cn=*”.
The first attribute in a compound filter must define the Relative Distinguished Name (RDN). For example, “...sub?(uid=*)(ou=group)”. Otherwise, the authentication fails.
When a search string is added, the SAP ASE server verifies that it uses valid LDAP URL syntax and that it references an existing node. To ensure that the valid string returns expected values, carefully choose and verify the search string when configuring the SAP ASE server.
The secondary URL search string enables failover to another LDAP server. The SAP ASE server uses the primary URL search string unless the LDAP Server is not active or the search string is invalid. In this event, the SAP ASE server uses the secondary URL search string for authentication.
The login sequence of searched DN algorithm requires the SAP ASE server to bind to the LDAP server using the access account before it can perform searches. The SAP ASE server obtains an LDAP descriptor (handle) as a result of the bind. This descriptor is used for searching the DN of the login on the LDAP server.
In order to access the server, users who are being authenticated with the LDAP server should either exist as a valid user in SAP ASE, or have a mapping defined.

See Creating and Managing ASE Logins Using LDAP in the System Administration Guide and sp_maplogin.

Permissions

The permission checks for sp_ldapadmin differ based on your granular permissions settings.

Setting	Description
Enabled	With granular permissions enabled, you must be a user with`manage security configuration` privilege.
Disabled	With granular permissions disabled, you must be a user with sso_role.

Auditing

Values in event and extrainfo columns from the sysaudits table are:

Information	Values
Event	38
Audit option	exec_procedure
Command or access audited	Execution of a procedure
Information in `extrainfo`	Roles – Current active roles Keywords or options – NULL Previous value – NULL Current value – NULL Other information – All input parameters Proxy information – Original login name, if set proxy in effect