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.BindResult; 042import com.unboundid.ldap.sdk.Control; 043import com.unboundid.ldap.sdk.DecodeableControl; 044import com.unboundid.ldap.sdk.LDAPException; 045import com.unboundid.ldap.sdk.ResultCode; 046import com.unboundid.util.NotMutable; 047import com.unboundid.util.ThreadSafety; 048import com.unboundid.util.ThreadSafetyLevel; 049import com.unboundid.util.Validator; 050 051import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 052 053 054 055/** 056 * This class provides an implementation of the authorization identity bind 057 * response control as defined in 058 * <A HREF="http://www.ietf.org/rfc/rfc3829.txt">RFC 3829</A>. It may be used 059 * to provide the primary authorization identity associated with the client 060 * connection after processing of the associated bind operation has completed. 061 * <BR><BR> 062 * The authorization identity value returned may be empty if the resulting 063 * authorization identity is that of the anonymous user. Otherwise, it should 064 * be an "authzId" value as described in section 5.2.1.8 of 065 * <A HREF="http://www.ietf.org/rfc/rfc4513.txt">RFC 4513</A>. That is, it 066 * should be either "dn:" followed by the distinguished name of the target user, 067 * or "u:" followed by the username. 068 * <BR><BR> 069 * Note that the authorization identity response control should only be included 070 * in a bind response message if the corresponding request included the 071 * {@link AuthorizationIdentityRequestControl}, and only if the bind was 072 * successful. 073 */ 074@NotMutable() 075@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 076public final class AuthorizationIdentityResponseControl 077 extends Control 078 implements DecodeableControl 079{ 080 /** 081 * The OID (2.16.840.1.113730.3.4.15) for the authorization identity response 082 * control. 083 */ 084 public static final String AUTHORIZATION_IDENTITY_RESPONSE_OID = 085 "2.16.840.1.113730.3.4.15"; 086 087 088 089 /** 090 * The serial version UID for this serializable class. 091 */ 092 private static final long serialVersionUID = -6315724175438820336L; 093 094 095 096 // The authorization ID string returned by the server. 097 private final String authorizationID; 098 099 100 101 /** 102 * Creates a new empty control instance that is intended to be used only for 103 * decoding controls via the {@code DecodeableControl} interface. 104 */ 105 AuthorizationIdentityResponseControl() 106 { 107 authorizationID = null; 108 } 109 110 111 112 /** 113 * Creates a new authorization identity response control with the provided 114 * authorization ID. 115 * 116 * @param authorizationID The authorization identity associated with the 117 * client connection. It must not be {@code null}, 118 * although it may be a zero-length string to 119 * indicate that the authorization identity is the 120 * anonymous user. 121 */ 122 public AuthorizationIdentityResponseControl(final String authorizationID) 123 { 124 super(AUTHORIZATION_IDENTITY_RESPONSE_OID, false, 125 new ASN1OctetString(authorizationID)); 126 127 Validator.ensureNotNull(authorizationID); 128 129 this.authorizationID = authorizationID; 130 } 131 132 133 134 /** 135 * Creates a new authorization identity response control with the provided 136 * information. 137 * 138 * @param oid The OID for the control. 139 * @param isCritical Indicates whether the control should be marked 140 * critical. 141 * @param value The encoded value for the control. This may be 142 * {@code null} if no value was provided. 143 * 144 * @throws LDAPException If the provided control cannot be decoded as an 145 * authorization identity response control. 146 */ 147 public AuthorizationIdentityResponseControl(final String oid, 148 final boolean isCritical, 149 final ASN1OctetString value) 150 throws LDAPException 151 { 152 super(oid, isCritical, value); 153 154 if (value == null) 155 { 156 throw new LDAPException(ResultCode.DECODING_ERROR, 157 ERR_AUTHZID_RESPONSE_NO_VALUE.get()); 158 } 159 else 160 { 161 authorizationID = value.stringValue(); 162 } 163 } 164 165 166 167 /** 168 * {@inheritDoc} 169 */ 170 @Override() 171 public AuthorizationIdentityResponseControl 172 decodeControl(final String oid, final boolean isCritical, 173 final ASN1OctetString value) 174 throws LDAPException 175 { 176 return new AuthorizationIdentityResponseControl(oid, isCritical, value); 177 } 178 179 180 181 /** 182 * Extracts an authorization identity response control from the provided 183 * result. 184 * 185 * @param result The result from which to retrieve the authorization 186 * identity response control. 187 * 188 * @return The authorization identity response control contained in the 189 * provided result, or {@code null} if the result did not contain an 190 * authorization identity response control. 191 * 192 * @throws LDAPException If a problem is encountered while attempting to 193 * decode the authorization identity response control 194 * contained in the provided result. 195 */ 196 public static AuthorizationIdentityResponseControl 197 get(final BindResult result) 198 throws LDAPException 199 { 200 final Control c = 201 result.getResponseControl(AUTHORIZATION_IDENTITY_RESPONSE_OID); 202 if (c == null) 203 { 204 return null; 205 } 206 207 if (c instanceof AuthorizationIdentityResponseControl) 208 { 209 return (AuthorizationIdentityResponseControl) c; 210 } 211 else 212 { 213 return new AuthorizationIdentityResponseControl(c.getOID(), 214 c.isCritical(), c.getValue()); 215 } 216 } 217 218 219 220 /** 221 * Retrieves the authorization ID string for this authorization identity 222 * response control. It may be a zero-length string if the associated 223 * authorization identity is that of the anonymous user. 224 * 225 * @return The authorization ID string for this authorization identity 226 * response control. 227 */ 228 public String getAuthorizationID() 229 { 230 return authorizationID; 231 } 232 233 234 235 /** 236 * {@inheritDoc} 237 */ 238 @Override() 239 public String getControlName() 240 { 241 return INFO_CONTROL_NAME_AUTHZID_RESPONSE.get(); 242 } 243 244 245 246 /** 247 * {@inheritDoc} 248 */ 249 @Override() 250 public void toString(final StringBuilder buffer) 251 { 252 buffer.append("AuthorizationIdentityResponseControl(authorizationID='"); 253 buffer.append(authorizationID); 254 buffer.append("', isCritical="); 255 buffer.append(isCritical()); 256 buffer.append(')'); 257 } 258}