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 configuration element the next code has to be included:

<configSections>
	<sectionGroup name="futuramaSettings or visionSettings">
		<section name="identityprovider" type="ActuIT.Futurama.Config.IdentityProviderSection, ActuIT.Futurama.Engine,Culture=neutral, PublicKeyToken=null"/>
	</sectionGroup>
</configSections>

Next to this code, also within the configuration 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" entityid="entity" url="www.futurama.eu"/>
            <idp issuer="https://issuer/" 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" authcontextComparison="minimum" />
            <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"/>    
                </idpList>
                <requesterIds>
                    <requester requesterId="testRequesterID1"/>
                    <requester requesterid="testRequesterID2"/>   
                </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 and the url of your organization.

From Futurama 20.03 it is possible to use the entityid parameter. This parameter is optional. If it is not used, then in the generated metadata file the value of the url is used for the entityid. 

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

issuer

From Futurama 20.04 you can specify the issuer that is used by the IDP. This is necessary if you define multiple SAML2 IDP's and you use SingleLogout. The issuer is used to determine the config that is used for the LogoutRequest that is received during a Logout from the IDP. 

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 information 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. From Futurama version 20.01 only sha256 is supported as sha1 is not considered to be safe.

The possible values are:

signatureMethod

The encryption method used to determine the signature. From Futurama version 20.01 only sha256 is supported as sha1 is not considered to be safe.

The possible values are:

authcontextComparison

The Comparison method to use for the authentication statements. This property optional and is available from version 20.03. The default value is 'minimum'.

The possible values are :

  • minimum: then the resulting authentication context in the authentication statement MUST be at least as strong (as deemed by the responder) as defined in 'level'
  • exact: then the resulting authentication context in the authentication statement MUST be the exact match of the security defined in 'level'
  • better: then the resulting authentication context in the authentication statement MUST be stronger (as deemed by the responder) than the security defined in 'level'
  • maximum: then the resulting authentication context in the authentication statement MUST be as strong as possible (as deemed by the responder) without exceeding the strength of the security defined in 'level'

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. If you use multiple SAML2 identity providers please be sure to provide the issuer property for the IDP. 

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’
  3. Make sure the the cookie permission are set correctly. Futurama needs to receive the session cookie after the round trip to the IDP. For a redirect binding this means that the session cookies needs a SameSite policy 'Lax'. For a POST binding this means that the session cookie needs a SameSite binding 'None'. You can specify this by using the cookieSameSite property in the sessionState section within the system.web section of the web.config. 

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 browsing to /SAML/GetMetadata.aspx?idpname=name, where name is the name attribute of the saml2 element configured in the identityprovider section.

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:

<system.diagnostics>
	<sources>
		<source name="ComponentSpace.SAML2" switchValue="Verbose">
			<listeners>
				<add name="TextWriter" />
			</listeners>
		</source>
	</sources>
	<trace autoflush="true" indentsize="3" />
	<sharedListeners>
		<add name="TextWriter" type="System.Diagnostics.TextWriterTraceListener" initializeData="D:\folder\file.log" />
	</sharedListeners>
</system.diagnostics>  

DigiD

Sample config

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

<identityprovider>
	<saml2 baseURL="http://yoururl/" binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" name="Digid">
		<spcertificate findValue="test.registerexpress.nl" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectName"/>
		<idpcertificate findValue="was-preprod1.digid.nl" storeLocation="LocalMachine" storeName="TrustedPublisher" x509FindType="FindBySubjectName"/>
		<technicalContact email="info@actuit.nl" name="John Doe"/>
		<organization displayName="ActuIT B.V." name="ActuIT B.V." url="www.actuit.nl"/>
		<idp idpArtifactResponderURL="https://was-preprod1.digid.nl/saml/idp/resolve_artifact" idpLogoutURL="https://preprod1.digid.nl/saml/idp/request_logout" idpssoURL="https://preprod1.digid.nl/saml/idp/request_authentication"/>
		<security digestMethod="http://www.w3.org/2001/04/xmlenc#sha256" level="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" signatureMethod="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
		<logging mode="Simple"/>
	</saml2>
</identityprovider>

Accessible addresses

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

Feedback

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

Updated: 2020-04-16