001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2012-2021 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.ds.types; 028 029 030 031import java.util.List; 032 033import com.unboundid.asn1.ASN1OctetString; 034import com.unboundid.directory.sdk.common.types.Entry; 035import com.unboundid.ldap.sdk.Control; 036import com.unboundid.ldap.sdk.LDAPException; 037import com.unboundid.util.NotExtensible; 038import com.unboundid.util.ThreadSafety; 039import com.unboundid.util.ThreadSafetyLevel; 040 041 042 043/** 044 * This interface provides methods that may be used to construct SASL bind 045 * result objects. 046 */ 047@NotExtensible() 048@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 049public interface SASLBindResultFactory 050{ 051 /** 052 * Creates a success SASL bind result in which the authentication and 053 * authorization user identities are the same, and no diagnostic message, 054 * controls, or server SASL credentials need to be returned. 055 * 056 * @param authenticatedUserDN The DN of the user that has been 057 * authenticated. It may be {@code null} if the 058 * resulting authentication was anonymous. 059 * 060 * @return The created success SASL bind result. 061 */ 062 SuccessSASLBindResult createSuccessResult(final String authenticatedUserDN); 063 064 065 066 /** 067 * Creates a success SASL bind result with the provided information. 068 * 069 * @param authenticatedUserDN The DN of the user that has been 070 * authenticated. It may be empty or 071 * {@code null} if the resulting authentication 072 * was anonymous. 073 * @param authorizedUserDN The DN of the user that should be used as 074 * the authorization identity for subsequent 075 * operations requested on the connection. In 076 * most cases, it should be the same as the 077 * authenticated user DN, but it may be 078 * different if an alternate authorization 079 * identity was specified. It may be empty or 080 * {@code null} if the authorization identity 081 * should be that of the anonymous user. 082 * @param diagnosticMessage The diagnostic message that should be 083 * included in the response to the client. It 084 * may be {@code null} if no diagnostic message 085 * is needed. 086 * @param controls The set of controls that should be included 087 * in the response to the client. It may be 088 * {@code null} or empty if no response 089 * controls are needed. 090 * @param serverSASLCredentials The server SASL credentials that should be 091 * included in the response to the client. It 092 * may be {@code null} if no server SASL 093 * credentials are needed. 094 * 095 * @return The created success SASL bind result. 096 */ 097 SuccessSASLBindResult createSuccessResult(final String authenticatedUserDN, 098 final String authorizedUserDN, 099 final String diagnosticMessage, 100 final List<Control> controls, 101 final ASN1OctetString serverSASLCredentials); 102 103 104 105 /** 106 * Creates a success SASL bind result with the provided information. 107 * 108 * @param authenticatedUserDN The DN of the user that has been 109 * authenticated. It may be empty or 110 * {@code null} if the resulting authentication 111 * was anonymous. 112 * @param authorizedUserDN The DN of the user that should be used as 113 * the authorization identity for subsequent 114 * operations requested on the connection. In 115 * most cases, it should be the same as the 116 * authenticated user DN, but it may be 117 * different if an alternate authorization 118 * identity was specified. It may be empty or 119 * {@code null} if the authorization identity 120 * should be that of the anonymous user. 121 * @param diagnosticMessage The diagnostic message that should be 122 * included in the response to the client. It 123 * may be {@code null} if no diagnostic message 124 * is needed. 125 * @param controls The set of controls that should be included 126 * in the response to the client. It may be 127 * {@code null} or empty if no response 128 * controls are needed. 129 * @param serverSASLCredentials The server SASL credentials that should be 130 * included in the response to the client. It 131 * may be {@code null} if no server SASL 132 * credentials are needed. 133 * @param passwordUsed The plaintext password that was used to 134 * authenticate. This may be {@code null} if 135 * the associated SASL mechanism is not 136 * password-based or if the plaintext password 137 * is not available. 138 * 139 * @return The created success SASL bind result. 140 */ 141 SuccessSASLBindResult createSuccessResult(final String authenticatedUserDN, 142 final String authorizedUserDN, 143 final String diagnosticMessage, 144 final List<Control> controls, 145 final ASN1OctetString serverSASLCredentials, 146 final ASN1OctetString passwordUsed); 147 148 149 150 /** 151 * Creates a continuation SASL bind result (indicating that more processing 152 * is required to complete the authentication) with the provided information. 153 * 154 * @param diagnosticMessage The diagnostic message that should be 155 * included in the response to the client. It 156 * may be {@code null} if no diagnostic message 157 * is needed. 158 * @param controls The set of controls that should be included 159 * in the response to the client. It may be 160 * {@code null} or empty if no response 161 * controls are needed. 162 * @param serverSASLCredentials The server SASL credentials that should be 163 * included in the response to the client. It 164 * may be {@code null} if no server SASL 165 * credentials are needed. 166 * 167 * @return The created continuation SASL bind result. 168 */ 169 ContinuationSASLBindResult createContinuationResult( 170 final String diagnosticMessage, 171 final List<Control> controls, 172 final ASN1OctetString serverSASLCredentials); 173 174 175 176 /** 177 * Creates a failure SASL bind result with the provided information. 178 * 179 * @param authenticationFailureReason A message that explains the reason for 180 * the authentication failure. This will 181 * be recorded in the server access log 182 * but not included in the response to 183 * return to the client. 184 * @param diagnosticMessage The diagnostic message that should be 185 * included in the response to the 186 * client. It may be {@code null} if no 187 * diagnostic message is needed. 188 * @param matchedDN The matched DN that should be included 189 * in the response to the client. It may 190 * be {@code null} if no matched DN is 191 * needed. 192 * @param controls The set of controls that should be 193 * included in the response to the 194 * client. It may be {@code null} or 195 * empty if no response controls are 196 * needed. 197 * @param serverSASLCredentials The server SASL credentials that 198 * should be included in the response to 199 * the client. It may be {@code null} if 200 * no server SASL credentials are needed. 201 * 202 * @return The created failure SASL bind result. 203 */ 204 FailureSASLBindResult createFailureResult( 205 final String authenticationFailureReason, 206 final String diagnosticMessage, 207 final String matchedDN, 208 final List<Control> controls, 209 final ASN1OctetString serverSASLCredentials); 210 211 212 213 /** 214 * Creates a failure SASL bind result with the provided information. 215 * 216 * @param authenticationFailureReason A message that explains the 217 * reason for the authentication 218 * failure. This will be recorded 219 * in the server access log but not 220 * included in the response to 221 * return to the client. 222 * @param diagnosticMessage The diagnostic message that 223 * should be included in the 224 * response to the client. It may 225 * be {@code null} if no diagnostic 226 * message is needed. 227 * @param matchedDN The matched DN that should be 228 * included in the response to the 229 * client. It may be {@code null} 230 * if no matched DN is needed. 231 * @param controls The set of controls that should 232 * be included in the response to 233 * the client. It may be 234 * {@code null} or empty if no 235 * response controls are needed. 236 * @param serverSASLCredentials The server SASL credentials that 237 * should be included in the 238 * response to the client. It may 239 * be {@code null} if no server 240 * SASL credentials are needed. 241 * @param unsuccessfullyAuthenticatedUserDN The DN of the user that tried 242 * to authenticate but was unable 243 * to do so successfully, if 244 * applicable. 245 * 246 * @return The created failure SASL bind result. 247 */ 248 FailureSASLBindResult createFailureResult( 249 final String authenticationFailureReason, 250 final String diagnosticMessage, 251 final String matchedDN, 252 final List<Control> controls, 253 final ASN1OctetString serverSASLCredentials, 254 final String unsuccessfullyAuthenticatedUserDN); 255 256 257 258 /** 259 * Indicates whether the provided password is valid for the specified user. 260 * Note that absolutely no password policy processing will be performed. This 261 * method merely determines whether the provided password is contained in the 262 * specified user entry. 263 * 264 * @param userDN The DN of the user entry for which to make the 265 * determination. It must not be {@code null} or empty. 266 * @param password The bytes comprising the non-encoded clear-text password 267 * for which the determination is to be made. It must not 268 * be {@code null} or empty. 269 * 270 * @return {@code true} if the given password is contained in the specified 271 * user entry, or {@code false} if not. 272 * 273 * @throws LDAPException If a problem is encountered while attempting to 274 * make the determination. 275 */ 276 boolean isUserPasswordValid(final String userDN, 277 final ASN1OctetString password) 278 throws LDAPException; 279 280 281 282 /** 283 * Maps the provided username to a user entry using the identity mapper 284 * associated with the SASL mechanism handler. 285 * 286 * @param username The username to be mapped to a user entry. 287 * 288 * @return The entry for the user identified by the associated identity 289 * mapper. 290 * 291 * @throws LDAPException If no identity mapper is associated with the SASL 292 * mechanism handler, or if the identity mapper cannot 293 * be used to map the username to exactly one entry. 294 */ 295 Entry mapUsernameToEntry(final String username) 296 throws LDAPException; 297}