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.ASN1OctetString; 041import com.unboundid.ldap.sdk.Control; 042import com.unboundid.ldap.sdk.LDAPException; 043import com.unboundid.ldap.sdk.ResultCode; 044import com.unboundid.util.NotMutable; 045import com.unboundid.util.ThreadSafety; 046import com.unboundid.util.ThreadSafetyLevel; 047import com.unboundid.util.Validator; 048 049import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 050 051 052 053/** 054 * This class provides an implementation of the proxied authorization V2 055 * request control, as defined in 056 * <A HREF="http://www.ietf.org/rfc/rfc4370.txt">RFC 4370</A>. It may be used 057 * to request that the associated operation be performed as if it has been 058 * requested by some other user. 059 * <BR><BR> 060 * The target authorization identity for this control is specified as an 061 * "authzId" value as described in section 5.2.1.8 of 062 * <A HREF="http://www.ietf.org/rfc/rfc4513.txt">RFC 4513</A>. That is, it 063 * should be either "dn:" followed by the distinguished name of the target user, 064 * or "u:" followed by the username. If the "u:" form is used, then the 065 * mechanism used to resolve the provided username to an entry may vary from 066 * server to server. 067 * <BR><BR> 068 * This control may be used in conjunction with add, delete, compare, delete, 069 * extended, modify, modify DN, and search requests. In that case, the 070 * associated operation will be processed under the authority of the specified 071 * authorization identity rather than the identity associated with the client 072 * connection (i.e., the user as whom that connection is bound). Note that 073 * because of the inherent security risks associated with the use of the proxied 074 * authorization control, most directory servers which support its use enforce 075 * strict restrictions on the users that are allowed to request this control. 076 * If a user attempts to use the proxied authorization V2 request control and 077 * does not have sufficient permission to do so, then the server will return a 078 * failure response with the {@link ResultCode#AUTHORIZATION_DENIED} result 079 * code. 080 * <BR><BR> 081 * There is no corresponding response control for this request control. 082 * <BR><BR> 083 * <H2>Example</H2> 084 * The following example demonstrates the use of the proxied authorization V2 085 * control to delete an entry under the authority of the user with username 086 * "alternate.user": 087 * <PRE> 088 * // Create a delete request to delete an entry. Include the proxied 089 * // authorization v2 request control in the delete request so that the 090 * // delete will be processed as the user with username "alternate.user" 091 * // instead of the user that's actually authenticated on the connection. 092 * DeleteRequest deleteRequest = 093 * new DeleteRequest("uid=test.user,ou=People,dc=example,dc=com"); 094 * deleteRequest.addControl(new ProxiedAuthorizationV2RequestControl( 095 * "u:alternate.user")); 096 * 097 * LDAPResult deleteResult; 098 * try 099 * { 100 * deleteResult = connection.delete(deleteRequest); 101 * // If we got here, then the delete was successful. 102 * } 103 * catch (LDAPException le) 104 * { 105 * // The delete failed for some reason. In addition to all of the normal 106 * // reasons a delete could fail (e.g., the entry doesn't exist, or has one 107 * // or more subordinates), proxied-authorization specific failures may 108 * // include that the authenticated user doesn't have permission to use the 109 * // proxied authorization control to impersonate the alternate user, that 110 * // the alternate user doesn't exist, or that the alternate user doesn't 111 * // have permission to perform the requested operation. 112 * deleteResult = le.toLDAPResult(); 113 * ResultCode resultCode = le.getResultCode(); 114 * String errorMessageFromServer = le.getDiagnosticMessage(); 115 * } 116 * </PRE> 117 */ 118@NotMutable() 119@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 120public final class ProxiedAuthorizationV2RequestControl 121 extends Control 122{ 123 /** 124 * The OID (2.16.840.1.113730.3.4.18) for the proxied authorization v2 request 125 * control. 126 */ 127 public static final String PROXIED_AUTHORIZATION_V2_REQUEST_OID = 128 "2.16.840.1.113730.3.4.18"; 129 130 131 132 /** 133 * The serial version UID for this serializable class. 134 */ 135 private static final long serialVersionUID = 1054244283964851067L; 136 137 138 139 // The authorization ID string that may be used to identify the user under 140 // whose authorization the associated operation should be performed. 141 private final String authorizationID; 142 143 144 145 /** 146 * Creates a new proxied authorization V2 request control that will proxy as 147 * the specified user. 148 * 149 * @param authorizationID The authorization ID string that will be used to 150 * identify the user under whose authorization the 151 * associated operation should be performed. It may 152 * take one of three forms: it can be an empty 153 * string (to indicate that the operation should use 154 * anonymous authorization), a string that begins 155 * with "dn:" and is followed by the DN of the target 156 * user, or a string that begins with "u:" and is 157 * followed by the username for the target user 158 * (where the process of mapping the provided 159 * username to the corresponding entry will depend on 160 * the server configuration). It must not be 161 * {@code null}. 162 */ 163 public ProxiedAuthorizationV2RequestControl(final String authorizationID) 164 { 165 super(PROXIED_AUTHORIZATION_V2_REQUEST_OID, true, 166 new ASN1OctetString(authorizationID)); 167 168 Validator.ensureNotNull(authorizationID); 169 170 this.authorizationID = authorizationID; 171 } 172 173 174 175 /** 176 * Creates a new proxied authorization v2 request control which is decoded 177 * from the provided generic control. 178 * 179 * @param control The generic control to be decoded as a proxied 180 * authorization v2 request control. 181 * 182 * @throws LDAPException If the provided control cannot be decoded as a 183 * proxied authorization v2 request control. 184 */ 185 public ProxiedAuthorizationV2RequestControl(final Control control) 186 throws LDAPException 187 { 188 super(control); 189 190 final ASN1OctetString value = control.getValue(); 191 if (value == null) 192 { 193 throw new LDAPException(ResultCode.DECODING_ERROR, 194 ERR_PROXY_V2_NO_VALUE.get()); 195 } 196 197 authorizationID = value.stringValue(); 198 } 199 200 201 202 /** 203 * Retrieves the authorization ID string that will be used to identify the 204 * user under whose authorization the associated operation should be 205 * performed. 206 * 207 * @return The authorization ID string that will be used to identify the user 208 * under whose authorization the associated operation should be 209 * performed. 210 */ 211 public String getAuthorizationID() 212 { 213 return authorizationID; 214 } 215 216 217 218 /** 219 * {@inheritDoc} 220 */ 221 @Override() 222 public String getControlName() 223 { 224 return INFO_CONTROL_NAME_PROXIED_AUTHZ_V2_REQUEST.get(); 225 } 226 227 228 229 /** 230 * {@inheritDoc} 231 */ 232 @Override() 233 public void toString(final StringBuilder buffer) 234 { 235 buffer.append("ProxiedAuthorizationV2RequestControl(authorizationID='"); 236 buffer.append(authorizationID); 237 buffer.append("')"); 238 } 239}