Applicable to:Futurama Website
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:
- configuration of the identity provider in the web.config
- adding a button to the website that initiates the login process
- use a function that retrieves the identity that is provided by the identity provider (see Futurama formula ReadIdentityProviderResult).
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.
Within the configuration element the next code has to be included:
<sectionGroup name="futuramaSettings or visionSettings">
<section name="identityprovider" type="ActuIT.Futurama.Config.IdentityProviderSection, ActuIT.Futurama.Engine,Culture=neutral, PublicKeyToken=null"/>
Next to this code, also within the configuration element the next code has to be included:
<saml2 name="Digid" baseURL="http://myapplication/" binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
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="firstname.lastname@example.org"/>
<organization name="Futurama" displayName="Futurama" entityid="entity" url="www.futurama.eu"/>
<idp issuer="https://issuer/" idpssoURL="http://localhost/SAML2IdentityProviderVS/SAML/SSOService.aspx"
<scoping proxyCount="0" getComplete="http://www.test.nl">
<idp name="testIDP1" providerID="provID1" loc="loc1"/>
<idp name="testIDP2" providerid="provID2" loc="loc2"/>
<serviceName xml:lang="en" name="ServiceName"></serviceName>
<requestedAttribute name="AttributeName" isRequired="true">
The futuramaSettings element is the general part for more configuration settings. Within this element the Identity Provider element is set.
Within the identityprovider element some other elements and their attributes can be set. Below the explanation of these elements and attributes.
The saml2-elements does have some attributes. Below the explanation of these attributes.
The name used by the web application. This name is passed to the identity provider in the authentication request.
The URL used by the webapplication.
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.
The binding to use. Futurama supports the following bindings:
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.
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.
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.
In this section you define the settings as they are defined in the scoping options for SAML2. This element is optional.
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
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.
The name of the technical contact.
The email address of the technical contact.
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.
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
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.
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.
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.
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.
In the logging tag you can define the level of log information you want.
The logging level. Possible values are:
No information is logged
basic information is logged
The maximum amount of information is logged
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:
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:
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:
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'