001 /*
002 * Copyright 2007-2016 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2008-2016 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 */
021 package com.unboundid.ldap.sdk.extensions;
022
023
024
025 import com.unboundid.ldap.sdk.Control;
026 import com.unboundid.ldap.sdk.ExtendedRequest;
027 import com.unboundid.ldap.sdk.ExtendedResult;
028 import com.unboundid.ldap.sdk.LDAPConnection;
029 import com.unboundid.ldap.sdk.LDAPException;
030 import com.unboundid.ldap.sdk.ResultCode;
031 import com.unboundid.util.NotMutable;
032 import com.unboundid.util.ThreadSafety;
033 import com.unboundid.util.ThreadSafetyLevel;
034
035 import 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)
100 public 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 }