sp_ldapadmin

Description

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 Adaptive 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 Adaptive 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 Adaptive Server 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 Adaptive 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 Adaptive Server 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=*. Adaptive Server replaces the wildcard with the Adaptive Server 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 Adaptive Server login record.

For example, “samaccountname=jqpublic” returns DN attribute “distinguishedName” with value “cn=John Q. Public, cn=Users,dc=mycompany, dc=com” to Adaptive Server. Adaptive 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 Adaptive 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

Permissions

Only the system security officer can execute sp_ldapadmin.

Auditing

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

Event

Audit option

Command or access audited

Information in extrainfo

38

exec_procedure

Execution of a procedure

  • 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