se.swedenconnect.opensaml.saml2.request.RequestHttpObjectBuilder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of opensaml-addons Show documentation
OpenSAML 5.X utility extension library
The newest version!
/*
 * Copyright 2016-2024 Sweden Connect
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package se.swedenconnect.opensaml.saml2.request;

import org.opensaml.messaging.encoder.MessageEncodingException;
import org.opensaml.saml.saml2.core.RequestAbstractType;
import org.opensaml.security.x509.X509Credential;
import org.opensaml.xmlsec.signature.support.SignatureException;

import net.shibboleth.shared.resolver.ResolverException;
import se.swedenconnect.opensaml.common.builder.SAMLObjectBuilder;

/**
 * A generic request builder that is used to create Request messages.
 * 
 * A request builder instance may only be used to create one request and should not be re-used. Instead a new builder
 * should be created using a builder factory.
 * 
 * 
 * By default the request builder creates a Request object based on the SP and IdP settings in metadata and the
 * configuration of the builder factory, but it is also possible to control the request by using chaining calls as
 * illustrated below:
 * 
 *
 * {@code
 * RequestHttpObject request =
 *     builder.relayState("hello").binding("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST").build();
 * }
 * 
 *
 * @author Martin Lindström ([email protected])
 *
 * @param  the concrete request type
 */
public interface RequestHttpObjectBuilder extends SAMLObjectBuilder {

  /**
   * Compiles the request by invoking {@link #build()}, optionally signs it and encodes it according to the configured
   * binding and returns a RequestHttpObject that can be used by the SP application to send the request to the Identity
   * Provider.
   *
   * @return a RequestHttpObject object
   * @throws SignatureException for signature creation errors
   * @throws ResolverException for metadata errors
   * @throws MessageEncodingException for encoding errors
   */
  RequestHttpObject buildHttpObject() throws SignatureException, ResolverException, MessageEncodingException;

  /**
   * Returns the entityID of the Service Provider that this builder is serving.
   *
   * @return entityID of the Service Provider
   */
  String entityID();

  /**
   * Returns the entityID for the IdP to which we are constructing the request.
   *
   * @return entityID of the Identity Provider
   */
  String idpEntityID();

  /**
   * Installs the SAML RelayState to use when sending the request.
   *
   * @param relayState the RelayState
   * @return an updated builder object
   */
  RequestHttpObjectBuilder relayState(final String relayState);

  /**
   * Returns the SAML RelayState that has been configured for this builder.
   *
   * @return the SAML RelayState or null if none has been configured
   */
  String relayState();

  /**
   * Replaces the request object that this builder currently is processing with a new and updated object.
   * 
   * Note: Care should be taken when using this method, and if only a particular attribute or element of the request
   * should be modified it is generally better to use the {@link #request()} method that returns a reference to the
   * contained request message, or the special purpose methods for this purpose.
   * 
   *
   * @param request the request object to install to the builder
   * @return an updated builder object
   * @see #request()
   */
  RequestHttpObjectBuilder request(final T request);

  /**
   * Returns a reference to the request object that this builder object is handling. In order to modify parts of the
   * request this method should be used.
   * 
   * Also see the methods that directly modifies attributes and elements.
   * 
   *
   * @return a reference to the request object
   */
  T request();

  /**
   * The builder is created with the SAML binding to use when sending the request message (redirect or post). This
   * method may be used to override this setting.
   *
   * @param binding the URI of the SAML binding to use (e.g., "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect")
   * @return an updated builder object
   * @throws ResolverException if the binding supplied does not match a binding found in the IdP:s entity descriptor
   */
  RequestHttpObjectBuilder binding(final String binding) throws ResolverException;

  /**
   * Returns the SAML binding that should be used when sending the request.
   *
   * @return the URI of the SAML binding to use
   */
  String binding();

  /**
   * The RequestBuilder reads the federation metadata and determines that a request should be signed if based on
   * requirements from the IdP and SP.
   * 
   * Using this method it is possible to override the default behaviour by explicitly state the request should be
   * signed, or not signed.
   * 
   *
   * @param signatureFlag flag telling whether the request being created should be signed or not
   * @return an updated builder object
   */
  RequestHttpObjectBuilder performSignature(final boolean signatureFlag);

  /**
   * Predicate that tells whether the request being created will be signed or not.
   *
   * @return if the request being created will be signed true is returned, and false otherwise
   */
  boolean performSignature();

  /**
   * Using this method the signature credentials for the builder object may be changed. This is typically useful when
   * the SP has more than one signature key, or for testing purposes.
   *
   * @param signatureCredentials the "new" signature credentials
   * @return an updated builder object
   */
  RequestHttpObjectBuilder signatureCredentials(final X509Credential signatureCredentials);

  /**
   * Returns the signature credentials this builder object has been configured to use during request signing.
   *
   * @return the signature credentials
   */
  X509Credential signatureCredentials();

  /**
   * For testing purposes
   * 
   * The method will change the endpoint to where the request will be sent, but will not modify the
   * {@code Destination} attribute of the request element.
   * 
   *
   * @param url the endpoint to assign
   * @return an updated builder object
   */
  RequestHttpObjectBuilder endpoint(final String url);

}