Search

Version: 5.0.0 +

Applicable to: Futurama Website

 

Description

When you are using Futurama in Website mode you can select an external identity provider to determine if an user has access to the webpage. Currently Futurama supports the SAML 2 identity provider. This identity provider is described extensively by oasis on SAML2 overview.

When using a SAML2 identity provider the user is redirected to the website of the identity provider and performs a login on that website. After logging in the user is redirected to the website that initiated the process and you can use a Futurama function to retrieve the identity of the user.

When you want to use an external identity provider in Futurama you have to take the next steps:

  1. configuration of the identity provider in the web.config
  2. adding a button to the website that initiates the login process
  3. use a function that retrieves the identity that is provided by the identity provider (see Futurama formula ReadIdentityProviderResult).

Definitions

In this document, and in all the referenced documentation the names ServiceProvider (SP) and IdentityProvider (IDP) are used. The SP is the Futurama application that provides a service to the consumers. The identity provider is the external organisation that is used to authenticate the visitors.

Configuration

Settings

Within the element the next code has to be included:


	
 

 

Next to this code, also within the element the next code has to be included:

<futuramasettings>
	<identityprovider>
		<saml2 name="Digid" baseurl="http://myapplication/" binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" saml2loadbalancerurl="http://localhost/samlloadbalancer/" assertionbinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" loginbuttontext="Login with TestIDP">
			<spcertificate findvalue="www.sp.com" storelocation="LocalMachine" storename="Root" x509findtype="FindBySubjectName"/>
			<idpcertificate findvalue="www.idp.com" storelocation="LocalMachine" storename="Root" x509findtype="FindBySubjectName"/>
			<technicalcontact name="UserName" email="info@actuit.nl"/>
			<organization name="Futurama" displayname="Futurama" url="www.futurama.eu"/>
			<idp idpssourl="http://localhost/SAML2IdentityProviderVS/SAML/SSOService.aspx" idpartifactresponderurl="http://localhost/SAML2IdentityProviderVS/SAML/ArtifactResponder.aspx" idplogouturl="http://localhost/SAML2IdentityProviderVS/SAML/SingleLogoutService.aspx" claimnamegroupnameassertion="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"/>
			<security level="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" digestmethod="http://www.w3.org/2001/04/xmlenc#sha256" signaturemethod="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
			<logging mode="Simple"/>
			<scoping proxycount="0" getcomplete="http://www.test.nl">
				<idplist>
					<idp name="testIDP1" providerid="provID1" loc="loc1">
						<idp name="testIDP2" providerid="provID2" loc="loc2">
						</idp>
					</idp>
				</idplist>
				<requesterids>
					<requester requesterid="testRequesterID1">
						<requester requesterid="testRequesterID2">
						</requester>
					</requester>
				</requesterids>
			</scoping>
			<attributeconsumingservice>
				<servicenamelist>
					<servicename xml:lang="en" name="ServiceName">
					</servicename>
				</servicenamelist>
				<requestedattributelist>
					<requestedattribute name="AttributeName" isrequired="true">
					</requestedattribute>
				</requestedattributelist>
			</attributeconsumingservice>
		</saml2>
	</identityprovider>
</futuramasettings>

The futuramaSettings element is the general part for more configuration settings. Within this element the Identity Provider element is set.

Explanation

Within the identityprovider element some other elements and their attributes can be set. Below the explanation of these elements and attributes.

saml2

The saml2-elements does have some attributes. Below the explanation of these attributes.

name

The name used by the web application. This name is passed to the identity provider in the authentication request.

baseURL

The URL used by the webapplication.

SAML2LoadBalancerURL

The URL used by the SAML 2 LoadBalancer. SAML 2 Loadbalancer is a component that you need to use to enable SingleLogout in combination with a load balancer. This is supported in Futurama 6 and higher.

assertionBinding (Futurama 19.02+)

Optional configuration to define the binding of the assertion. Possible values are urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect and urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

binding

The binding to use. Futurama supports the following bindings:

 
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect;
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.
loginButtonText (Futurama 19.10 +)

The text that is used for the loginButton that is created for this IDP in Vision. This property is not used in a Futurama Website.

spcertificate

A reference to a certificate that is used by the service provider. This certificate should be placed in the certificate store. The configuration is described in certificateRerence element.

The use of the saml2 identity provider requires that you have the private key of the certificate of the service provider. Make sure that the private key is exportable.

idpcertificate

A reference to a certificate that is used by the identity provider. This certificate should be placed in the certificate store. The configuration is described in certificateRerence element.

scoping

In this section you define the settings as they are defined in the scoping options for SAML2. This element is optional.

attributeConsumingService

In this section you define the settings as they are defined in the attributeConsumingService options for SAML2. This element is optional. It is possible to use 1 attributeConsumingService

technicalContact

In this section you can define the name of the technical contact. This anme is used in the metadata.xml file that is generated by Futurama.

name

The name of the technical contact.

email

The email address of the technical contact.

organization

In the organization tag you can define the name of your organization. This name is used in the generated metada.xml file.

idp

In the idp section you can specify various addresses that are used by the idp. These addresses should be provided by the IDP. For more background information we would like to recommend the wikipedia article on SAML 2: http://en.wikipedia.org/wiki/SAML_2.0

idpssoURL

The URL that is used by the IDP to initiate a single sign on. So this is the address where the initial authentication request is sent.

idpArtifactResponderURL

The URL that is used by the SP to request information via the back channel from the IDP in response to the receipt of a SAML artifact from the IDP.

idpLogoutURL

The URL that is used by the IDP to request a logout. It is used when a users logs out in this application to initiate a log out at the IDP, and it is used to confirm a logout in response to an IDP initiated logout. From 19.01 on, if this URL is empty or if the idpLogoutUrl attribute is omiited at all, Futurama will not send a logout request to the IDP.

claimNameGroupNameAssertion (Futurama 19.10 +)

The name of the claimAssertion the SAML2 IDP provider uses to pass possible group names. This attribute is optional. If you want to use the functionality of Windows Groups in combination with SAML2 you will need this. For example in Azure AD you can specify which claim to fill with which property. If you do that and select the corresponding claimName here, you can use group membership for SAML2 authentication.

logging

In the logging tag you can define the level of log information you want.

mode

The logging level. Possible values are:

  • None
    No information is logged
  • Simple
    basic iinformation is logged
  • Extended
    The maximum amount of information is logged

security

level

The security level that you require for authentication. The default value is urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.

The possible values are:

  • urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
  • urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract
  • urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
digestMethod

The digest method used for determining the XML signature.

The possible values are:

signatureMethod

The encryption method used to determine the signature

The possible values are:

Multiple SAML2 identity providers (Futurama 18.10+)

It is possible to configure multiple SAML2 identityproviders, by adding more than one element in the configuration within the element. When this is done, it is required that a Name is provided for every Futurama Button control that is set to “RedirectToIdentityProvider”, otherwise Futurama does not know which identityprovider to use. This name is set in the “IdentityProviderName” property, as shown in the Button documentation. When set to an empty value, it will expect that only one saml2 element is present in the configuration.

Using 256 bit encryption

If you want to use an IDP that requires 256 bit encryption, you need to install an extra DLL and register that DLL in Windows.

Please follow the following steps.

By default, SHA-1 signatures are supported and are perfectly suitable for the majority of use cases. However, SHA-256 signatures are also supported for those use cases requiring additional security.
SHA-256 support in XML signatures requires the use of the CLR security update and is only available in .NET 3.5 and above.
Download the CLR security update from:
http://clrsecurity.codeplex.com/wikipage?title=Security.Cryptography.RSAPKCS
Installation instructions may be found at:
http://clrsecurity.codeplex.com/wikipage?title=Security.Cryptography.RSAPKCS1SHA256SignatureDescription&referringTitle=Home&ProjectName=clrsecurity
1. Extract the Security.Cryptography DLL from the CLR security zip.
2. Run gacutil.exe /i Security.Cryptography.dll to add the assembly to the GAC.
3. View the assembly (e.g. C:\Windows\assembly) and note the version number (e.g 1.6.0.0).
4. Update machine.config (e.g. in C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config and C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config) ensuring the version number of the assembly is correct. The should be inserted after the section in . See below for an example configuration.
5. Certificates and keys should be generated using the “Microsoft Enhanced RSA and AES Cryptographic Provider”.

The following is an example configuration for insertion into machine.config.


	
	
		
			
				
			
			
		
	

Attention points

See the next attention poitns:

  1. Do not use cookieless sessions with a saml 2 identity provider. Otherwise the logout functionality will not work;
  2. See Installation HTML, Troubleshoot paragraph how to fix the error message ‘key not valid in for use in specified state’

Generating metadata

Saml 2 Identity providers require you to publish or manually deliver a metadata file. Futurama can generate this file for you. If you setup the configuration for the identity provider in your web.config you can visit the page /SAML/GetMetadata.aspx and you will receive a metadata file with all the settings from the config section. This metadata will be signed with the sp certificate. So to be able to perform this step it is important to visit this page when the sp certificate is installed in the certificate store on the server that hosts the Futurama Website. The identity for the application pool needs to have access to the private key of the sp certificate. You can use localsystem or set up the correct permissions for the specified user.

Note: if you have configured multiple identity providers, then the metadata for a certain identity provider have to be created by disabling the other identity providers. So these are the steps to take if you have configured multiple identity providers and want to generate the metadata for identityprovider A:

  1. disable in your configuration file all the identity providers except identity provider A (disabling can be done by commenting the saml2 elements of the specific identity provider)
  2. generate the metadata by browsing to /SAML/GetMetadata.aspx (see above)
  3. save this generated metadata file
  4. enable all the identity providers again

Debugging

For the identity provider an external component is used. For debugging purposes you can turn on the extra logging for that module as well.

To do that you can add the following tags to the web.config:


	
		
			
				
			
		
	
	
		
	 

DigiD

Sample config

If you want to use the Dutch Digid authentication you can use the following config:


	
		
		
		
		
		
		
		
	

Accessible addresses

For the Dutch DigiD implementation the next addresses must be accessible from the server where your application is hosted:

Related Topics

- Cache: Settings regarding the caching of Futurama documents

- Debug: Settings to debug while developing with Futurama

- Format: Format settings of Futurama

- Log: Settings for displaying errors, warnings, information messages and developers messages

- Mail: Definition of the mailserver that is used to send e-mails with Futurama Vision

- Mapping: Settings for default locations of Futurama files

- Monitor: Settings for getting session information

- Rendering: Settings to allow Futurama to generate customized HTML

- Security: Additional possible security settings when using Futurama Website

- Server: Settings when using Futurama Export either in server or in batch mode

- Vision: Configuration of the connection between Futurama and Futurama Vision

- SAMLLoadBalancer: component that enables the use of SAML2 with a load balancer.

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2018-10-15