001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2010 Sun Microsystems, Inc.
015 * Portions Copyright 2012-2014 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.i18n.LocalizedIllegalArgumentException;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.LdapException;
026import org.forgerock.opendj.ldap.controls.Control;
027import org.forgerock.opendj.ldap.controls.ControlDecoder;
028
029/**
030 * The External SASL bind request as defined in RFC 4422. This SASL mechanism
031 * allows a client to request the server to use credentials established by means
032 * external to the mechanism to authenticate the client. The external means may
033 * be, for instance, SSL or TLS.
034 * <p>
035 * A client may either request that its authorization identity be automatically
036 * derived from its authentication credentials exchanged at a lower security
037 * layer, or it may explicitly provide a desired authorization identity.
038 * <p>
039 * The optional authorization identity is specified using an authorization ID,
040 * or {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
041 *
042 * @see <a href="http://tools.ietf.org/html/rfc4422">RFC 4422 - Simple
043 *      Authentication and Security Layer (SASL) </a>
044 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
045 *      SASL Authorization Identities (authzId) </a>
046 */
047public interface ExternalSASLBindRequest extends SASLBindRequest {
048
049    /**
050     * The name of the SASL mechanism based on external authentication.
051     */
052    String SASL_MECHANISM_NAME = "EXTERNAL";
053
054    @Override
055    ExternalSASLBindRequest addControl(Control control);
056
057    @Override
058    BindClient createBindClient(String serverName) throws LdapException;
059
060    /**
061     * Returns the authentication mechanism identifier for this SASL bind
062     * request as defined by the LDAP protocol, which is always {@code 0xA3}.
063     *
064     * @return The authentication mechanism identifier.
065     */
066    @Override
067    byte getAuthenticationType();
068
069    /**
070     * Returns the optional desired authorization ID of the user, or
071     * {@code null} if the authorization ID should derived from authentication
072     * credentials exchanged at a lower security layer. The authorization ID
073     * usually has the form "dn:" immediately followed by the distinguished name
074     * of the user, or "u:" followed by a user ID string, but other forms are
075     * permitted.
076     *
077     * @return The desired authorization ID of the user, which may be
078     *         {@code null} .
079     */
080    String getAuthorizationID();
081
082    @Override
083    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
084            throws DecodeException;
085
086    @Override
087    List<Control> getControls();
088
089    /**
090     * Returns the name of the Directory object that the client wishes to bind
091     * as, which is always the empty string for SASL authentication.
092     *
093     * @return The name of the Directory object that the client wishes to bind
094     *         as.
095     */
096    @Override
097    String getName();
098
099    @Override
100    String getSASLMechanism();
101
102    /**
103     * Sets the optional desired authorization ID of the user, or {@code null}
104     * if the authorization ID should derived from authentication credentials
105     * exchanged at a lower security layer. The authorization ID usually has the
106     * form "dn:" immediately followed by the distinguished name of the user, or
107     * "u:" followed by a user ID string, but other forms are permitted.
108     *
109     * @param authorizationID
110     *            The desired authorization ID of the user, which may be
111     *            {@code null}.
112     * @return This bind request.
113     * @throws UnsupportedOperationException
114     *             If this external SASL request does not permit the
115     *             authorization ID to be set.
116     * @throws LocalizedIllegalArgumentException
117     *             If {@code authorizationID} was non-empty and did not contain
118     *             a valid authorization ID type.
119     */
120    ExternalSASLBindRequest setAuthorizationID(String authorizationID);
121}