se.litsec.opensaml.saml2.authentication.build

Class ExtendedAuthnRequestBuilder

java.lang.Object

se.litsec.opensaml.core.AbstractSAMLObjectBuilder<T>

se.litsec.opensaml.saml2.core.build.AbstractRequestBuilder<AuthnRequest,BUILDER>

se.litsec.opensaml.saml2.core.build.AbstractAuthnRequestBuilder<ExtendedAuthnRequestBuilder>

se.litsec.opensaml.saml2.authentication.build.ExtendedAuthnRequestBuilder

All Implemented Interfaces:

SAMLObjectBuilder<AuthnRequest>

public class ExtendedAuthnRequestBuilder
extends AbstractAuthnRequestBuilder<ExtendedAuthnRequestBuilder>

The ExtendedAuthnRequestBuilder builds an AuthnRequest object given the metadata entry for the Service Provider that sends the request and the metadata entry for the Identity Provider that is the recipient of the request.

The purpose with this builder is that the caller does not have to go through the SP and IdP metadata and create a valid AuthnRequest. By invoking assignDefaults() the AuthnRequest is built using values found in the metadata entries. Any particular settings that are non-default should be assigned using the builder's assigment methods, either before or after invoking assignDefaults(). The builder will assume that the "HTTP-Redirect" binding is used to send the request to the IdP (given that the IdP has an endpoint for this binding). Should the caller want to use another binding (POST), the binding(String) should be invoked before calling assignDefaults().

Author:

Martin Lindström (martin.lindstrom@litsec.se)

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_ID_SIZE If an ID attribute is generated by the builder it uses 24 characters for it.
static String	DEFAULT_REQUEST_BINDING If no binding for how the request is to be passed to the IdP we assume SAMLConstants.SAML2_REDIRECT_BINDING_URI.

Constructor Summary

Constructors

Constructor and Description
ExtendedAuthnRequestBuilder(EntityDescriptor spMetadata, EntityDescriptor idpMetadata) Constructor initializing the builder with the metadata entry for the Service Provider that is creating the authentication request and the metadata entry for the Identity Provider which is about to receive the request.

Method Summary

Modifier and Type	Method and Description
ExtendedAuthnRequestBuilder	assignDefaults() Calculates values based on the SP and IdP metadata and assigns them to the AuthnRequest.
ExtendedAuthnRequestBuilder	authnContextClassRefs(boolean onlyMatching, boolean failOnNoMatch, List<String> uris) A utility method that helps adding one or more Authentication context class reference URI(s) to the RequestedAuthnContext element.
ExtendedAuthnRequestBuilder	authnContextClassRefs(boolean onlyMatching, boolean failOnNoMatch, String... uris)
String	binding() Returns the binding URI to be used to this request, i.e., should the request be redirected to the IdP or should it be posted?
ExtendedAuthnRequestBuilder	binding(String binding) Assigns the URI that tells which binding (method) to use when transfering the AuthnRequest to the IdP.
ExtendedAuthnRequestBuilder	destination(String destination) Assigns the Destination attribute and also updates the binding to use based on which of the IdP SingleSignService elements that match the supplied destination value.
protected ExtendedAuthnRequestBuilder	getThis() In order for us to be able to make chaining calls we need to return the concrete type of the builder.
ExtendedAuthnRequestBuilder	id(int idSize) Generates an identifier of size idSize and assigns it to the AuthnRequest.
ExtendedAuthnRequestBuilder	nameIDPolicyFormat(String format) Assigns a NameIDPolicy element with the Format attribute assigned to format and its AllowCreate attribute set to true.

Methods inherited from class se.litsec.opensaml.saml2.core.build.AbstractAuthnRequestBuilder

assertionConsumerServiceIndex, assertionConsumerServiceURL, attributeConsumerServiceIndex, build, conditions, forceAuthn, getObjectType, isPassive, nameIDPolicy, postProtocolBinding, protocolBinding, providerName, requestedAuthnContext, scoping, subject

Methods inherited from class se.litsec.opensaml.saml2.core.build.AbstractRequestBuilder

consent, extensions, id, issueInstant, issueInstant, issuer, issuer, version, version

Methods inherited from class se.litsec.opensaml.core.AbstractSAMLObjectBuilder

object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_REQUEST_BINDING

public static final String DEFAULT_REQUEST_BINDING

If no binding for how the request is to be passed to the IdP we assume SAMLConstants.SAML2_REDIRECT_BINDING_URI.

See Also:

Constant Field Values

DEFAULT_ID_SIZE

public static final int DEFAULT_ID_SIZE

If an ID attribute is generated by the builder it uses 24 characters for it.

See Also:

Constant Field Values

Constructor Detail

ExtendedAuthnRequestBuilder

public ExtendedAuthnRequestBuilder(EntityDescriptor spMetadata,
                                   EntityDescriptor idpMetadata)

Constructor initializing the builder with the metadata entry for the Service Provider that is creating the authentication request and the metadata entry for the Identity Provider which is about to receive the request.

Parameters:

spMetadata - the SP metadata

idpMetadata - the IdP metadata

Method Detail

assignDefaults

public ExtendedAuthnRequestBuilder assignDefaults()

Calculates values based on the SP and IdP metadata and assigns them to the AuthnRequest. The following rules are automatically applied by the assignDefaults() method:

• The version is set to 2.0.
• An ID attribute is generated and assigned.
• The ProtocolBinding is assigned to HTTP-POST.
• The Destination attribute is assigned the value found in the IdP metadata's SingleSignOnService element having a binding matching the binding that was assigned this builder.
• The Issuer element is assigned the entityID found in the SP metadata.
• The NameIDPolicy element is assigned by iterating over the declared NameIDFormat elements of the SP metadata and using the first format that is also declared by the IdP. The AllowCreate is set to true.

Returns:

the builder

id

public ExtendedAuthnRequestBuilder id(int idSize)

Generates an identifier of size idSize and assigns it to the AuthnRequest.

Parameters:

idSize - the number of characters to be used in the ID

Returns:

the builder

destination

public ExtendedAuthnRequestBuilder destination(String destination)

Assigns the Destination attribute and also updates the binding to use based on which of the IdP SingleSignService elements that match the supplied destination value.

Using this builder it is not recommended to assign the Destination attribute. Instead assign the desired binding (binding(String)) and the Destination attribute will be automatically assigned.

Overrides:

destination in class AbstractRequestBuilder<AuthnRequest,ExtendedAuthnRequestBuilder>

Parameters:

destination - the destination URI

Returns:

the builder

See Also:

binding(String)

binding

public String binding()

Returns the binding URI to be used to this request, i.e., should the request be redirected to the IdP or should it be posted?

The setting controls how the AuthnRequest is put together and which data that is read from the IdP metadata.

Returns:

the binding URI

binding

public ExtendedAuthnRequestBuilder binding(String binding)
                                    throws SAMLObjectBuilderRuntimeException

Assigns the URI that tells which binding (method) to use when transfering the AuthnRequest to the IdP.

The setting controls how the AuthnRequest is put together and which data that is read from the IdP metadata. More specifically it assigns the Destination attribute to the address found in the IdP SingleSignOnService element having this binding.

Parameters:

binding - the binding URI

Returns:

the builder

Throws:

SAMLObjectBuilderRuntimeException - is thrown if the IdP metadata does not define a SingleSignOnService element having the given binding, which means that it does not support it, and it it thus meaningless to send this request using this binding

nameIDPolicyFormat

public ExtendedAuthnRequestBuilder nameIDPolicyFormat(String format)
                                               throws SAMLObjectBuilderRuntimeException

Assigns a NameIDPolicy element with the Format attribute assigned to format and its AllowCreate attribute set to true.

Parameters:

format - the format to assign

Returns:

the builder

Throws:

SAMLObjectBuilderRuntimeException - if the IdP's metadata entry does not list the supplied format as supported

authnContextClassRefs

public ExtendedAuthnRequestBuilder authnContextClassRefs(boolean onlyMatching,
                                                         boolean failOnNoMatch,
                                                         List<String> uris)
                                                  throws SAMLObjectBuilderRuntimeException

A utility method that helps adding one or more Authentication context class reference URI(s) to the RequestedAuthnContext element. The method will read the IdP's declared assuranceCertification URIs from its metadata.

Parameters:

onlyMatching - only add URIs that are also declared by the IdP in its metadata

failOnNoMatch - throw if none of our given URIs are declared by the IdP

uris - the URIs to add

Returns:

the builder

Throws:

SAMLObjectBuilderRuntimeException - is thrown if failOnNoMatch is set and we don't get a match between given URIs and declared URIs

authnContextClassRefs

public ExtendedAuthnRequestBuilder authnContextClassRefs(boolean onlyMatching,
                                                         boolean failOnNoMatch,
                                                         String... uris)
                                                  throws SAMLObjectBuilderRuntimeException

Parameters:

onlyMatching - only add URIs that are also declared by the IdP in its metadata

failOnNoMatch - throw if none of our given URIs are declared by the IdP

uris - the URIs to add

Returns:

the builder

Throws:

SAMLObjectBuilderRuntimeException - is thrown if failOnNoMatch is set and we don't get a match between given URIs and declared URIs

See Also:

authnContextClassRefs(boolean, boolean, List)

getThis

protected ExtendedAuthnRequestBuilder getThis()

In order for us to be able to make chaining calls we need to return the concrete type of the builder.

Specified by:

getThis in class AbstractRequestBuilder<AuthnRequest,ExtendedAuthnRequestBuilder>

Returns:

the concrete type of the builder