001/* 002 * Copyright 2007-2022 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2007-2022 Ping Identity Corporation 007 * 008 * Licensed under the Apache License, Version 2.0 (the "License"); 009 * you may not use this file except in compliance with the License. 010 * You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, software 015 * distributed under the License is distributed on an "AS IS" BASIS, 016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 017 * See the License for the specific language governing permissions and 018 * limitations under the License. 019 */ 020/* 021 * Copyright (C) 2007-2022 Ping Identity Corporation 022 * 023 * This program is free software; you can redistribute it and/or modify 024 * it under the terms of the GNU General Public License (GPLv2 only) 025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 026 * as published by the Free Software Foundation. 027 * 028 * This program is distributed in the hope that it will be useful, 029 * but WITHOUT ANY WARRANTY; without even the implied warranty of 030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 031 * GNU General Public License for more details. 032 * 033 * You should have received a copy of the GNU General Public License 034 * along with this program; if not, see <http://www.gnu.org/licenses>. 035 */ 036package com.unboundid.ldap.sdk.controls; 037 038 039 040import com.unboundid.asn1.ASN1Element; 041import com.unboundid.asn1.ASN1OctetString; 042import com.unboundid.asn1.ASN1Sequence; 043import com.unboundid.ldap.sdk.Control; 044import com.unboundid.ldap.sdk.DN; 045import com.unboundid.ldap.sdk.LDAPException; 046import com.unboundid.ldap.sdk.ResultCode; 047import com.unboundid.util.Debug; 048import com.unboundid.util.NotMutable; 049import com.unboundid.util.NotNull; 050import com.unboundid.util.ThreadSafety; 051import com.unboundid.util.ThreadSafetyLevel; 052import com.unboundid.util.Validator; 053 054import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 055 056 057 058/** 059 * This class provides an implementation of the proxied authorization V1 060 * request control, which may be used to request that the associated operation 061 * be performed as if it had been requested by some other user. It is based on 062 * the specification provided in early versions of the 063 * draft-weltman-ldapv3-proxy Internet Draft (this implementation is based on 064 * the "-04" revision). Later versions of the draft, and subsequently 065 * <A HREF="http://www.ietf.org/rfc/rfc4370.txt">RFC 4370</A>, define a second 066 * version of the proxied authorization control with a different OID and 067 * different value format. This control is supported primarily for legacy 068 * purposes, and it is recommended that new applications use the 069 * {@link ProxiedAuthorizationV2RequestControl} instead if this version. 070 * <BR><BR> 071 * The value of this control includes the DN of the user as whom the operation 072 * should be performed. Note that it should be a distinguished name, and not an 073 * authzId value as is used in the proxied authorization V2 control. 074 * <BR><BR> 075 * This control may be used in conjunction with add, delete, compare, delete, 076 * extended, modify, modify DN, and search requests. In that case, the 077 * associated operation will be processed under the authority of the specified 078 * authorization identity rather than the identity associated with the client 079 * connection (i.e., the user as whom that connection is bound). Note that 080 * because of the inherent security risks associated with the use of the proxied 081 * authorization control, most directory servers which support its use enforce 082 * strict restrictions on the users that are allowed to request this control. 083 * Note that while the directory server should return a 084 * {@link ResultCode#AUTHORIZATION_DENIED} result for a proxied authorization V2 085 * control if the requester does not have the appropriate permission to use that 086 * control, this result will not necessarily be used for the same condition with 087 * the proxied authorization V1 control because this result code was not defined 088 * until the release of the proxied authorization V2 specification. 089 * code. 090 * <BR><BR> 091 * There is no corresponding response control for this request control. 092 * <BR><BR> 093 * <H2>Example</H2> 094 * The following example demonstrates the use of the proxied authorization V1 095 * control to delete an entry under the authority of the user with DN 096 * "uid=alternate.user,ou=People,dc=example,dc=com": 097 * <PRE> 098 * // Create a delete request to delete an entry. Include the proxied 099 * // authorization v1 request control in the delete request so that the 100 * // delete will be processed as user 101 * // "uid=alternate.user,ou=People,dc=example,dc=com" instead of the user 102 * // that's actually authenticated on the connection. 103 * DeleteRequest deleteRequest = 104 * new DeleteRequest("uid=test.user,ou=People,dc=example,dc=com"); 105 * deleteRequest.addControl(new ProxiedAuthorizationV1RequestControl( 106 * "uid=alternate.user,ou=People,dc=example,dc=com")); 107 * 108 * LDAPResult deleteResult; 109 * try 110 * { 111 * deleteResult = connection.delete(deleteRequest); 112 * // If we got here, then the delete was successful. 113 * } 114 * catch (LDAPException le) 115 * { 116 * // The delete failed for some reason. In addition to all of the normal 117 * // reasons a delete could fail (e.g., the entry doesn't exist, or has one 118 * // or more subordinates), proxied-authorization specific failures may 119 * // include that the authenticated user doesn't have permission to use the 120 * // proxied authorization control to impersonate the alternate user, that 121 * // the alternate user doesn't exist, or that the alternate user doesn't 122 * // have permission to perform the requested operation. 123 * deleteResult = le.toLDAPResult(); 124 * ResultCode resultCode = le.getResultCode(); 125 * String errorMessageFromServer = le.getDiagnosticMessage(); 126 * } 127 * </PRE> 128 */ 129@NotMutable() 130@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 131public final class ProxiedAuthorizationV1RequestControl 132 extends Control 133{ 134 /** 135 * The OID (2.16.840.1.113730.3.4.12) for the proxied authorization v1 request 136 * control. 137 */ 138 @NotNull public static final String PROXIED_AUTHORIZATION_V1_REQUEST_OID = 139 "2.16.840.1.113730.3.4.12"; 140 141 142 143 /** 144 * The serial version UID for this serializable class. 145 */ 146 private static final long serialVersionUID = 7312632337431962774L; 147 148 149 150 // The DN of the target user under whose authorization the associated 151 // operation should be performed. 152 @NotNull private final String proxyDN; 153 154 155 156 /** 157 * Creates a new proxied authorization V1 request control that will proxy as 158 * the specified user. 159 * 160 * @param proxyDN The DN of the target user under whose authorization the 161 * associated request should be performed. It must not be 162 * {@code null}, although it may be an empty string to 163 * request an anonymous authorization. 164 */ 165 public ProxiedAuthorizationV1RequestControl(@NotNull final String proxyDN) 166 { 167 super(PROXIED_AUTHORIZATION_V1_REQUEST_OID, true, encodeValue(proxyDN)); 168 169 Validator.ensureNotNull(proxyDN); 170 171 this.proxyDN = proxyDN; 172 } 173 174 175 176 /** 177 * Creates a new proxied authorization V1 request control that will proxy as 178 * the specified user. 179 * 180 * @param proxyDN The DN of the target user under whose authorization the 181 * associated request should be performed. It must not be 182 * {@code null}. 183 */ 184 public ProxiedAuthorizationV1RequestControl(@NotNull final DN proxyDN) 185 { 186 super(PROXIED_AUTHORIZATION_V1_REQUEST_OID, true, 187 encodeValue(proxyDN.toString())); 188 189 this.proxyDN = proxyDN.toString(); 190 } 191 192 193 194 /** 195 * Creates a new proxied authorization v1 request control which is decoded 196 * from the provided generic control. 197 * 198 * @param control The generic control to be decoded as a proxied 199 * authorization v1 request control. 200 * 201 * @throws LDAPException If the provided control cannot be decoded as a 202 * proxied authorization v1 request control. 203 */ 204 public ProxiedAuthorizationV1RequestControl(@NotNull final Control control) 205 throws LDAPException 206 { 207 super(control); 208 209 final ASN1OctetString value = control.getValue(); 210 if (value == null) 211 { 212 throw new LDAPException(ResultCode.DECODING_ERROR, 213 ERR_PROXY_V1_NO_VALUE.get()); 214 } 215 216 try 217 { 218 final ASN1Element valueElement = ASN1Element.decode(value.getValue()); 219 final ASN1Element[] elements = 220 ASN1Sequence.decodeAsSequence(valueElement).elements(); 221 proxyDN = ASN1OctetString.decodeAsOctetString(elements[0]).stringValue(); 222 } 223 catch (final Exception e) 224 { 225 Debug.debugException(e); 226 throw new LDAPException(ResultCode.DECODING_ERROR, 227 ERR_PROXYV1_DECODE_ERROR.get(e), e); 228 } 229 } 230 231 232 233 /** 234 * Encodes the provided information into an octet string that can be used as 235 * the value for this control. 236 * 237 * @param proxyDN The DN of the target user under whose authorization the 238 * associated request should be performed. It must not be 239 * {@code null}, although it may be an empty string to 240 * request an anonymous authorization. 241 * 242 * @return An ASN.1 octet string that can be used as the value for this 243 * control. 244 */ 245 @NotNull() 246 private static ASN1OctetString encodeValue(@NotNull final String proxyDN) 247 { 248 final ASN1Element[] valueElements = 249 { 250 new ASN1OctetString(proxyDN) 251 }; 252 253 return new ASN1OctetString(new ASN1Sequence(valueElements).encode()); 254 } 255 256 257 258 /** 259 * Retrieves the DN of the target user under whose authorization the 260 * associated request should be performed. 261 * 262 * @return The DN of the target user under whose authorization the associated 263 * request should be performed. 264 */ 265 @NotNull() 266 public String getProxyDN() 267 { 268 return proxyDN; 269 } 270 271 272 273 /** 274 * {@inheritDoc} 275 */ 276 @Override() 277 @NotNull() 278 public String getControlName() 279 { 280 return INFO_CONTROL_NAME_PROXIED_AUTHZ_V1_REQUEST.get(); 281 } 282 283 284 285 /** 286 * {@inheritDoc} 287 */ 288 @Override() 289 public void toString(@NotNull final StringBuilder buffer) 290 { 291 buffer.append("ProxiedAuthorizationV1RequestControl(proxyDN='"); 292 buffer.append(proxyDN); 293 buffer.append("')"); 294 } 295}