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