0
# Authentication and Security
1

2
Comprehensive authentication mechanisms including simple bind, SASL authentication, SSL/TLS support, and security configuration for LDAP connections.
3

4
## Capabilities
5

6
### Basic Authentication
7

8
#### Simple Bind
9

10
Standard username/password authentication using simple bind.
11

12
```java { .api }
13
/**
14
 * Simple authentication with username and password
15
 */
16
public class SimpleBindRequest extends BindRequest {
17
    public SimpleBindRequest(String bindDN, String password);
18
    public SimpleBindRequest(String bindDN, byte[] password);
19
    public SimpleBindRequest(String bindDN, String password, Control... controls);
20
    
21
    public String getBindDN();
22
    public ASN1OctetString getPassword();
23
}
24

25
/**
26
 * Perform simple bind authentication
27
 * @param bindDN The DN to bind as
28
 * @param password The password
29
 * @return Bind result
30
 * @throws LDAPException if authentication fails
31
 */
32
public BindResult bind(String bindDN, String password) throws LDAPException;
33

34
/**
35
 * Perform bind with bind request object
36
 * @param bindRequest Complete bind request
37
 * @return Bind result
38
 * @throws LDAPException if authentication fails
39
 */
40
public BindResult bind(BindRequest bindRequest) throws LDAPException;
41
```
42

43
#### Anonymous Bind
44

45
```java { .api }
46
/**
47
 * Anonymous authentication (no credentials)
48
 * @return Bind result
49
 * @throws LDAPException if bind fails
50
 */
51
public BindResult bind() throws LDAPException;
52

53
/**
54
 * Explicit anonymous bind request
55
 */
56
public class ANONYMOUSBindRequest extends SASLBindRequest {
57
    public ANONYMOUSBindRequest();
58
    public ANONYMOUSBindRequest(String trace);
59
    public ANONYMOUSBindRequest(Control... controls);
60
}
61
```
62

63
### SASL Authentication
64

65
#### Base SASL Framework
66

67
```java { .api }
68
/**
69
 * Base class for SASL authentication mechanisms
70
 */
71
public abstract class SASLBindRequest extends BindRequest {
72
    public abstract String getSASLMechanismName();
73
    public SASLQualityOfProtection getAllowedQoP();
74
    public void setAllowedQoP(SASLQualityOfProtection... allowedQoP);
75
}
76

77
/**
78
 * SASL Quality of Protection levels
79
 */
80
public enum SASLQualityOfProtection {
81
    AUTH("auth"),
82
    AUTH_INT("auth-int"), 
83
    AUTH_CONF("auth-conf");
84
}
85
```
86

87
#### CRAM-MD5 Authentication
88

89
```java { .api }
90
/**
91
 * CRAM-MD5 SASL authentication mechanism
92
 */
93
public class CRAMMD5BindRequest extends SASLBindRequest {
94
    public CRAMMD5BindRequest(String authenticationID, String password);
95
    public CRAMMD5BindRequest(String authenticationID, byte[] password);
96
    public CRAMMD5BindRequest(String authenticationID, String password, Control... controls);
97
    
98
    public String getAuthenticationID();
99
    public String getSASLMechanismName(); // Returns "CRAM-MD5"
100
}
101
```
102

103
#### DIGEST-MD5 Authentication
104

105
```java { .api }
106
/**
107
 * DIGEST-MD5 SASL authentication mechanism
108
 */
109
public class DIGESTMD5BindRequest extends SASLBindRequest {
110
    public DIGESTMD5BindRequest(String authenticationID, String password);
111
    public DIGESTMD5BindRequest(String authenticationID, String authorizationID, String password);
112
    public DIGESTMD5BindRequest(String authenticationID, String authorizationID, byte[] password, String realm);
113
    
114
    public String getAuthenticationID();
115
    public String getAuthorizationID();
116
    public String getRealm();
117
    public String getSASLMechanismName(); // Returns "DIGEST-MD5"
118
}
119
```
120

121
#### GSSAPI/Kerberos Authentication
122

123
```java { .api }
124
/**
125
 * GSSAPI/Kerberos SASL authentication mechanism
126
 */
127
public class GSSAPIBindRequest extends SASLBindRequest {
128
    public GSSAPIBindRequest(String authenticationID);
129
    public GSSAPIBindRequest(String authenticationID, String authorizationID);
130
    public GSSAPIBindRequest(String authenticationID, String authorizationID, String kdcAddress);
131
    public GSSAPIBindRequest(String authenticationID, String authorizationID, String password, String realm, String kdcAddress);
132
    
133
    public String getAuthenticationID();
134
    public String getAuthorizationID();
135
    public String getRealm();
136
    public String getKDCAddress();
137
    public String getSASLMechanismName(); // Returns "GSSAPI"
138
    
139
    // Kerberos-specific configuration
140
    public void setConfigFilePath(String configFilePath);
141
    public void setJAASClientName(String jaasClientName);
142
    public void setServicePrincipalProtocol(String protocol);
143
    public void setTicketCachePath(String ticketCachePath);
144
    public void setUseKeyTab(boolean useKeyTab);
145
    public void setKeyTabPath(String keyTabPath);
146
}
147
```
148

149
#### OAuth Bearer Authentication
150

151
```java { .api }
152
/**
153
 * OAuth Bearer token SASL authentication mechanism
154
 */
155
public class OAUTHBEARERBindRequest extends SASLBindRequest {
156
    public OAUTHBEARERBindRequest(String authenticationID, String accessToken);
157
    public OAUTHBEARERBindRequest(String authenticationID, String authorizationID, String accessToken);
158
    public OAUTHBEARERBindRequest(String authenticationID, String authorizationID, String accessToken, String authzID, Control... controls);
159
    
160
    public String getAuthenticationID();
161
    public String getAuthorizationID();
162
    public String getAccessToken();
163
    public String getSASLMechanismName(); // Returns "OAUTHBEARER"
164
}
165
```
166

167
#### EXTERNAL Authentication
168

169
```java { .api }
170
/**
171
 * EXTERNAL SASL authentication mechanism (for client certificates)
172
 */
173
public class EXTERNALBindRequest extends SASLBindRequest {
174
    public EXTERNALBindRequest();
175
    public EXTERNALBindRequest(String authorizationID);
176
    public EXTERNALBindRequest(String authorizationID, Control... controls);
177
    
178
    public String getAuthorizationID();
179
    public String getSASLMechanismName(); // Returns "EXTERNAL"
180
}
181
```
182

183
#### PLAIN Authentication
184

185
```java { .api }
186
/**
187
 * PLAIN SASL authentication mechanism
188
 */
189
public class PLAINBindRequest extends SASLBindRequest {
190
    public PLAINBindRequest(String authenticationID, String password);
191
    public PLAINBindRequest(String authenticationID, String authorizationID, String password);
192
    public PLAINBindRequest(String authenticationID, String authorizationID, byte[] password, Control... controls);
193
    
194
    public String getAuthenticationID();
195
    public String getAuthorizationID();
196
    public String getSASLMechanismName(); // Returns "PLAIN"
197
}
198
```
199

200
#### SCRAM Authentication
201

202
SCRAM (Salted Challenge Response Authentication Mechanism) family providing enhanced security.
203

204
```java { .api }
205
/**
206
 * Base class for SCRAM SASL authentication mechanisms
207
 */
208
public abstract class SCRAMBindRequest extends SASLBindRequest {
209
    public SCRAMBindRequest(String authenticationID, String password);
210
    public SCRAMBindRequest(String authenticationID, String authorizationID, String password);
211
    public SCRAMBindRequest(String authenticationID, String authorizationID, byte[] password, Control... controls);
212
    
213
    public String getAuthenticationID();
214
    public String getAuthorizationID();
215
    public abstract String getSASLMechanismName();
216
}
217

218
/**
219
 * SCRAM-SHA-1 SASL authentication mechanism
220
 */
221
public class SCRAMSHA1BindRequest extends SCRAMBindRequest {
222
    public SCRAMSHA1BindRequest(String authenticationID, String password);
223
    public SCRAMSHA1BindRequest(String authenticationID, String authorizationID, String password);
224
    public SCRAMSHA1BindRequest(String authenticationID, String authorizationID, byte[] password, Control... controls);
225
    
226
    public String getSASLMechanismName(); // Returns "SCRAM-SHA-1"
227
}
228

229
/**
230
 * SCRAM-SHA-256 SASL authentication mechanism
231
 */
232
public class SCRAMSHA256BindRequest extends SCRAMBindRequest {
233
    public SCRAMSHA256BindRequest(String authenticationID, String password);
234
    public SCRAMSHA256BindRequest(String authenticationID, String authorizationID, String password);
235
    public SCRAMSHA256BindRequest(String authenticationID, String authorizationID, byte[] password, Control... controls);
236
    
237
    public String getSASLMechanismName(); // Returns "SCRAM-SHA-256"
238
}
239

240
/**
241
 * SCRAM-SHA-512 SASL authentication mechanism
242
 */
243
public class SCRAMSHA512BindRequest extends SCRAMBindRequest {
244
    public SCRAMSHA512BindRequest(String authenticationID, String password);
245
    public SCRAMSHA512BindRequest(String authenticationID, String authorizationID, String password);
246
    public SCRAMSHA512BindRequest(String authenticationID, String authorizationID, byte[] password, Control... controls);
247
    
248
    public String getSASLMechanismName(); // Returns "SCRAM-SHA-512"
249
}
250
```
251

252
### SSL/TLS Security
253

254
#### SSL Socket Factory Configuration
255

256
```java { .api }
257
/**
258
 * Create SSL connection with socket factory
259
 * @param host LDAP server hostname
260
 * @param port LDAP server port (typically 636 for LDAPS)
261
 * @param socketFactory SSL socket factory
262
 * @throws LDAPException if connection fails
263
 */
264
public LDAPConnection(String host, int port, SSLSocketFactory socketFactory) throws LDAPException;
265

266
/**
267
 * SSL utilities for creating socket factories
268
 */
269
public class SSLUtil {
270
    public SSLUtil();
271
    public SSLUtil(TrustManager trustManager);
272
    public SSLUtil(TrustManager[] trustManagers);
273
    public SSLUtil(KeyManager keyManager, TrustManager trustManager);
274
    public SSLUtil(KeyManager[] keyManagers, TrustManager[] trustManagers);
275
    
276
    public SSLSocketFactory createSSLSocketFactory() throws GeneralSecurityException;
277
    public SSLSocketFactory createSSLSocketFactory(String protocol) throws GeneralSecurityException;
278
    public SSLContext createSSLContext() throws GeneralSecurityException;
279
    public SSLContext createSSLContext(String protocol) throws GeneralSecurityException;
280
}
281
```
282

283
#### Trust Management
284

285
```java { .api }
286
/**
287
 * Trust all certificates (for testing only)
288
 */
289
public class TrustAllTrustManager implements X509TrustManager {
290
    public TrustAllTrustManager();
291
    public void checkClientTrusted(X509Certificate[] chain, String authType);
292
    public void checkServerTrusted(X509Certificate[] chain, String authType);
293
    public X509Certificate[] getAcceptedIssuers();
294
}
295

296
/**
297
 * Trust manager that validates against specific certificates
298
 */
299
public class TrustStoreTrustManager implements X509TrustManager {
300
    public TrustStoreTrustManager(String trustStorePath);
301
    public TrustStoreTrustManager(String trustStorePath, char[] trustStorePassword);
302
    public TrustStoreTrustManager(File trustStoreFile, char[] trustStorePassword, String trustStoreFormat);
303
}
304

305
/**
306
 * Prompt user to accept certificates
307
 */
308
public class PromptTrustManager implements X509TrustManager {
309
    public PromptTrustManager();
310
    public PromptTrustManager(String acceptedCertificatesFile);
311
}
312
```
313

314
#### Start TLS
315

316
```java { .api }
317
/**
318
 * Start TLS extended operation for upgrading plain connection to SSL/TLS
319
 */
320
public class StartTLSExtendedRequest extends ExtendedRequest {
321
    public StartTLSExtendedRequest();
322
    public StartTLSExtendedRequest(SSLContext sslContext);
323
    public StartTLSExtendedRequest(SSLSocketFactory socketFactory);
324
    public StartTLSExtendedRequest(Control... controls);
325
}
326

327
/**
328
 * Process Start TLS extended operation
329
 * @param request Start TLS request
330
 * @return Extended result
331
 * @throws LDAPException if TLS negotiation fails
332
 */
333
public ExtendedResult processExtendedOperation(StartTLSExtendedRequest request) throws LDAPException;
334
```
335

336
### Bind Results and Status
337

338
#### BindResult
339

340
```java { .api }
341
/**
342
 * Result of a bind operation
343
 */
344
public class BindResult extends LDAPResult {
345
    public String getBindDN();
346
    public ASN1OctetString getServerSASLCredentials();
347
}
348
```
349

350
### Security Configuration
351

352
#### Connection Security Options
353

354
```java { .api }
355
/**
356
 * Security-related connection options
357
 */
358
public class LDAPConnectionOptions {
359
    // SSL/TLS verification
360
    public void setSSLSocketVerifier(SSLSocketVerifier sslSocketVerifier);
361
    public SSLSocketVerifier getSSLSocketVerifier();
362
    
363
    // Certificate validation
364
    public void setUseSynchronousMode(boolean useSynchronousMode);
365
    public boolean useSynchronousMode();
366
    
367
    // Connection security
368
    public void setUsePooledSchema(boolean usePooledSchema);
369
    public boolean usePooledSchema();
370
    
371
    // Authentication requirements
372
    public void setBindWithDNRequiresPassword(boolean bindWithDNRequiresPassword);
373
    public boolean bindWithDNRequiresPassword();
374
}
375

376
/**
377
 * SSL socket verification interface
378
 */
379
public interface SSLSocketVerifier {
380
    void verifySSLSocket(String host, int port, SSLSocket sslSocket) throws LDAPException;
381
}
382

383
/**
384
 * Hostname verification for SSL certificates
385
 */
386
public class HostNameSSLSocketVerifier implements SSLSocketVerifier {
387
    public HostNameSSLSocketVerifier(boolean allowWildcards);
388
    public void verifySSLSocket(String host, int port, SSLSocket sslSocket) throws LDAPException;
389
}
390
```
391

392
## Usage Examples
393

394
### Simple Authentication
395

396
```java
397
import com.unboundid.ldap.sdk.*;
398

399
// Basic username/password authentication
400
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
401

402
try {
403
    // Simple bind
404
    BindResult bindResult = connection.bind("cn=admin,dc=example,dc=com", "password");
405
    
406
    if (bindResult.getResultCode() == ResultCode.SUCCESS) {
407
        System.out.println("Authentication successful");
408
        System.out.println("Bound as: " + bindResult.getBindDN());
409
    }
410
    
411
} catch (LDAPException e) {
412
    if (e.getResultCode() == ResultCode.INVALID_CREDENTIALS) {
413
        System.err.println("Invalid username or password");
414
    } else {
415
        System.err.println("Authentication failed: " + e.getMessage());
416
    }
417
} finally {
418
    connection.close();
419
}
420
```
421

422
### SASL CRAM-MD5 Authentication
423

424
```java
425
import com.unboundid.ldap.sdk.*;
426

427
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
428

429
try {
430
    // CRAM-MD5 SASL authentication
431
    CRAMMD5BindRequest bindRequest = new CRAMMD5BindRequest("john.doe", "password");
432
    BindResult bindResult = connection.bind(bindRequest);
433
    
434
    System.out.println("CRAM-MD5 authentication successful");
435
    
436
} catch (LDAPException e) {
437
    System.err.println("SASL authentication failed: " + e.getMessage());
438
} finally {
439
    connection.close();
440
}
441
```
442

443
### SSL/TLS Connection
444

445
```java
446
import com.unboundid.ldap.sdk.*;
447
import com.unboundid.util.ssl.*;
448

449
try {
450
    // Create SSL socket factory (trust all certificates - for testing only)
451
    SSLUtil sslUtil = new SSLUtil(new TrustAllTrustManager());
452
    SSLSocketFactory socketFactory = sslUtil.createSSLSocketFactory();
453
    
454
    // Connect using SSL (LDAPS on port 636)
455
    LDAPConnection connection = new LDAPConnection(socketFactory, "ldaps.example.com", 636);
456
    
457
    // Authenticate
458
    connection.bind("cn=admin,dc=example,dc=com", "password");
459
    
460
    System.out.println("SSL connection established successfully");
461
    
462
    connection.close();
463
    
464
} catch (Exception e) {
465
    System.err.println("SSL connection failed: " + e.getMessage());
466
}
467
```
468

469
### Start TLS
470

471
```java
472
import com.unboundid.ldap.sdk.*;
473
import com.unboundid.ldap.sdk.extensions.*;
474
import com.unboundid.util.ssl.*;
475

476
// Start with plain connection
477
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
478

479
try {
480
    // Create SSL context
481
    SSLUtil sslUtil = new SSLUtil(new TrustAllTrustManager());
482
    
483
    // Start TLS to upgrade connection to SSL
484
    StartTLSExtendedRequest startTLSRequest = new StartTLSExtendedRequest(sslUtil.createSSLContext());
485
    ExtendedResult startTLSResult = connection.processExtendedOperation(startTLSRequest);
486
    
487
    if (startTLSResult.getResultCode() == ResultCode.SUCCESS) {
488
        System.out.println("TLS started successfully");
489
        
490
        // Now authenticate over the encrypted connection
491
        connection.bind("cn=admin,dc=example,dc=com", "password");
492
    }
493
    
494
} catch (Exception e) {
495
    System.err.println("Start TLS failed: " + e.getMessage());
496
} finally {
497
    connection.close();
498
}
499
```
500

501
### GSSAPI/Kerberos Authentication
502

503
```java
504
import com.unboundid.ldap.sdk.*;
505

506
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
507

508
try {
509
    // Configure GSSAPI authentication
510
    GSSAPIBindRequest bindRequest = new GSSAPIBindRequest(
511
        "john.doe@EXAMPLE.COM",     // authentication ID
512
        null,                       // authorization ID (null = same as auth ID)
513
        "password",                 // password
514
        "EXAMPLE.COM",              // realm
515
        "kdc.example.com"           // KDC address
516
    );
517
    
518
    // Configure Kerberos settings
519
    bindRequest.setConfigFilePath("/etc/krb5.conf");
520
    bindRequest.setServicePrincipalProtocol("ldap");
521
    
522
    // Perform authentication
523
    BindResult bindResult = connection.bind(bindRequest);
524
    
525
    System.out.println("Kerberos authentication successful");
526
    
527
} catch (LDAPException e) {
528
    System.err.println("Kerberos authentication failed: " + e.getMessage());
529
} finally {
530
    connection.close();
531
}
532
```
533

534
### Connection Pool with Authentication
535

536
```java
537
import com.unboundid.ldap.sdk.*;
538

539
// Create initial authenticated connection
540
LDAPConnection connection = new LDAPConnection("ldap.example.com", 389);
541
connection.bind("cn=admin,dc=example,dc=com", "password");
542

543
// Create connection pool with bind request for new connections
544
SimpleBindRequest bindRequest = new SimpleBindRequest("cn=admin,dc=example,dc=com", "password");
545
ServerSet serverSet = new SingleServerSet("ldap.example.com", 389);
546

547
LDAPConnectionPool pool = new LDAPConnectionPool(serverSet, bindRequest, 5, 10);
548

549
try {
550
    // All connections in the pool will be authenticated
551
    SearchResult result = pool.search("dc=example,dc=com", SearchScope.BASE, "(objectClass=*)");
552
    System.out.println("Pool operation successful");
553
    
554
} finally {
555
    pool.close();
556
}
557
```
558

559
### Client Certificate Authentication
560

561
```java
562
import com.unboundid.ldap.sdk.*;
563
import com.unboundid.util.ssl.*;
564
import javax.net.ssl.*;
565
import java.security.KeyStore;
566

567
try {
568
    // Load client certificate keystore
569
    KeyStore keyStore = KeyStore.getInstance("PKCS12");
570
    keyStore.load(new FileInputStream("client-cert.p12"), "password".toCharArray());
571
    
572
    // Create key manager with client certificate
573
    KeyManagerFactory kmf = KeyManagerFactory.getInstance("SunX509");
574
    kmf.init(keyStore, "password".toCharArray());
575
    
576
    // Create SSL configuration
577
    SSLUtil sslUtil = new SSLUtil(kmf.getKeyManagers(), new TrustAllTrustManager());
578
    SSLSocketFactory socketFactory = sslUtil.createSSLSocketFactory();
579
    
580
    // Connect with client certificate
581
    LDAPConnection connection = new LDAPConnection(socketFactory, "ldaps.example.com", 636);
582
    
583
    // Authenticate using EXTERNAL SASL (uses client certificate)
584
    EXTERNALBindRequest bindRequest = new EXTERNALBindRequest();
585
    BindResult bindResult = connection.bind(bindRequest);
586
    
587
    System.out.println("Client certificate authentication successful");
588
    
589
    connection.close();
590
    
591
} catch (Exception e) {
592
    System.err.println("Client certificate authentication failed: " + e.getMessage());
593
}
594
```