001/* 002 * Copyright 2007-2017 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2017 UnboundID Corp. 007 * 008 * This program is free software; you can redistribute it and/or modify 009 * it under the terms of the GNU General Public License (GPLv2 only) 010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 011 * as published by the Free Software Foundation. 012 * 013 * This program is distributed in the hope that it will be useful, 014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 016 * GNU General Public License for more details. 017 * 018 * You should have received a copy of the GNU General Public License 019 * along with this program; if not, see <http://www.gnu.org/licenses>. 020 */ 021package com.unboundid.ldap.sdk.extensions; 022 023 024 025import com.unboundid.ldap.sdk.Control; 026import com.unboundid.ldap.sdk.ExtendedRequest; 027import com.unboundid.ldap.sdk.ExtendedResult; 028import com.unboundid.ldap.sdk.LDAPConnection; 029import com.unboundid.ldap.sdk.LDAPException; 030import com.unboundid.ldap.sdk.ResultCode; 031import com.unboundid.util.NotMutable; 032import com.unboundid.util.ThreadSafety; 033import com.unboundid.util.ThreadSafetyLevel; 034 035import static com.unboundid.ldap.sdk.extensions.ExtOpMessages.*; 036 037 038 039/** 040 * This class provides an implementation of the LDAP "Who Am I?" extended 041 * request as defined in 042 * <A HREF="http://www.ietf.org/rfc/rfc4532.txt">RFC 4532</A>. It may be used 043 * to request the current authorization identity associated with the client 044 * connection. 045 * <BR><BR> 046 * The "Who Am I?" extended operation is similar to the 047 * {@link com.unboundid.ldap.sdk.controls.AuthorizationIdentityRequestControl} 048 * in that it can be used to request the authorization identity for the 049 * connection. The primary difference between them is that the authorization 050 * identity request control can only be included in a bind request (and the 051 * corresponding response control will be included in the bind result), while 052 * the "Who Am I?" extended operation can be used at any time through a separate 053 * operation. 054 * <BR><BR> 055 * <H2>Example</H2> 056 * The following example demonstrates the use of the "Who Am I?" extended 057 * operation. 058 * <PRE> 059 * // Use the "Who Am I?" extended request to determine the identity of the 060 * // currently-authenticated user. 061 * WhoAmIExtendedResult whoAmIResult; 062 * try 063 * { 064 * whoAmIResult = (WhoAmIExtendedResult) 065 * connection.processExtendedOperation(new WhoAmIExtendedRequest()); 066 * // This doesn't necessarily mean that the operation was successful, since 067 * // some kinds of extended operations return non-success results under 068 * // normal conditions. 069 * } 070 * catch (LDAPException le) 071 * { 072 * // For an extended operation, this generally means that a problem was 073 * // encountered while trying to send the request or read the result. 074 * whoAmIResult = new WhoAmIExtendedResult(new ExtendedResult(le)); 075 * } 076 * 077 * LDAPTestUtils.assertResultCodeEquals(whoAmIResult, ResultCode.SUCCESS); 078 * String authzID = whoAmIResult.getAuthorizationID(); 079 * if (authzID.equals("") || authzID.equals("dn:")) 080 * { 081 * // The user is authenticated anonymously. 082 * } 083 * else if (authzID.startsWith("dn:")) 084 * { 085 * // The DN of the authenticated user should be authzID.substring(3) 086 * } 087 * else if (authzID.startsWith("u:")) 088 * { 089 * // The username of the authenticated user should be authzID.substring(2) 090 * } 091 * else 092 * { 093 * // The authorization ID isn't in any recognizable format. Perhaps it's 094 * // a raw DN or a username? 095 * } 096 * </PRE> 097 */ 098@NotMutable() 099@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE) 100public final class WhoAmIExtendedRequest 101 extends ExtendedRequest 102{ 103 /** 104 * The OID (1.3.6.1.4.1.4203.1.11.3) for the "Who Am I?" extended request. 105 */ 106 public static final String WHO_AM_I_REQUEST_OID = "1.3.6.1.4.1.4203.1.11.3"; 107 108 109 110 /** 111 * The serial version UID for this serializable class. 112 */ 113 private static final long serialVersionUID = -2936513698220673318L; 114 115 116 117 /** 118 * Creates a new "Who Am I?" extended request. 119 */ 120 public WhoAmIExtendedRequest() 121 { 122 super(WHO_AM_I_REQUEST_OID); 123 } 124 125 126 127 /** 128 * Creates a new "Who Am I?" extended request. 129 * 130 * @param controls The set of controls to include in the request. 131 */ 132 public WhoAmIExtendedRequest(final Control[] controls) 133 { 134 super(WHO_AM_I_REQUEST_OID, controls); 135 } 136 137 138 139 /** 140 * Creates a new "Who Am I?" extended request from the provided generic 141 * extended request. 142 * 143 * @param extendedRequest The generic extended request to use to create this 144 * "Who Am I?" extended request. 145 * 146 * @throws LDAPException If a problem occurs while decoding the request. 147 */ 148 public WhoAmIExtendedRequest(final ExtendedRequest extendedRequest) 149 throws LDAPException 150 { 151 super(extendedRequest); 152 153 if (extendedRequest.hasValue()) 154 { 155 throw new LDAPException(ResultCode.DECODING_ERROR, 156 ERR_WHO_AM_I_REQUEST_HAS_VALUE.get()); 157 } 158 } 159 160 161 162 /** 163 * {@inheritDoc} 164 */ 165 @Override() 166 public WhoAmIExtendedResult process(final LDAPConnection connection, 167 final int depth) 168 throws LDAPException 169 { 170 final ExtendedResult extendedResponse = super.process(connection, depth); 171 return new WhoAmIExtendedResult(extendedResponse); 172 } 173 174 175 176 /** 177 * {@inheritDoc} 178 */ 179 @Override() 180 public WhoAmIExtendedRequest duplicate() 181 { 182 return duplicate(getControls()); 183 } 184 185 186 187 /** 188 * {@inheritDoc} 189 */ 190 @Override() 191 public WhoAmIExtendedRequest duplicate(final Control[] controls) 192 { 193 final WhoAmIExtendedRequest r = new WhoAmIExtendedRequest(controls); 194 r.setResponseTimeoutMillis(getResponseTimeoutMillis(null)); 195 return r; 196 } 197 198 199 200 /** 201 * {@inheritDoc} 202 */ 203 @Override() 204 public String getExtendedRequestName() 205 { 206 return INFO_EXTENDED_REQUEST_NAME_WHO_AM_I.get(); 207 } 208 209 210 211 /** 212 * {@inheritDoc} 213 */ 214 @Override() 215 public void toString(final StringBuilder buffer) 216 { 217 buffer.append("WhoAmIExtendedRequest("); 218 219 final Control[] controls = getControls(); 220 if (controls.length > 0) 221 { 222 buffer.append("controls={"); 223 for (int i=0; i < controls.length; i++) 224 { 225 if (i > 0) 226 { 227 buffer.append(", "); 228 } 229 230 buffer.append(controls[i]); 231 } 232 buffer.append('}'); 233 } 234 235 buffer.append(')'); 236 } 237}