The SAML 2.0 login service can be used to connect a SAML 2.0 identity provider (e.g. Shibboleth 2.0) to formcycle. The SAML 2.0 specific configuration options are described below. For general information on basic settings and creating login services, see Login services.

Contents

Configuration

Type of identity provider metadata integration

SAML 2.0 Identity Providers (e.g. Shibboleth or Keycloak) provide metadata in the form of an XML file. This metadata contains various information about the identity provider for configuring the connection (entity ID, endpoints, encryption, signing, etc.). There are two ways to store the metadata of the identity provider:

Via file

• Upload / update identity provider metadata: Clicking this button opens a file selection dialog that can be used to select the configuration file supplied by the identity provider. Confirming the selection in the dialog will upload the file.
  
• Filename.xml: After a configuration file has been uploaded and the configuration has been saved, it is possible to download the file again at this point.

Via URL

The metadata of the identity provider can also be stored via URL. Some identity providers make their metadata available via a URL. Formcycle reads this metadata via the specified URL at regular intervals. To read the metadata from the identity provider again, the "Update now" button must be clicked.

• Caching duration in hours: Defines the time period (in hours) of how long the determined metadata of the identity provider should be cached before it is read again via the specified URL.
• Connection timeout in seconds: Defines a connection timeout (in seconds) for establishing the connection to read the identity provider metadata.
• Read timeout in Seconds: Defines the timeout (in seconds) of how long to wait for the identity provider's metadata to be transmitted.
• Proxy server: Defines an optional proxy server by host or IP.

Type of service provider entity ID

The service provider entity ID is the entity ID of formcycle, which is used in the formcycle metadata (service provider metadata) as well as in authentication requests. The entity ID can be set as fixed or dynamic:

• Fixed entity ID (recommended): As a rule, a fixed entity ID is preferred, since identity providers store the entity ID (e.g. via the service provider metadata) and check it during authentication requests. The fixed entity ID is specified once via the input field and is then used both in the formcycle metadata (service provider metadata) and for all authentication requests.
• Dynamic entity ID: When using a dynamic entity ID, the callback URL of the current server is always used as the entity ID.

Manage Keystore

To use the SAML authentication requests, it is necessary that a keystore with a key pair exists. The key pair of the keystore is used for the signature as well as for the encryption of the SAML authentication requests. By default, formcycle creates a corresponding keystore. By clicking on Manage Keystore, the settings for the keystore become visible. First, there are the following two buttons:

• Create new keystore: Creates a new keystore with a new key pair.
• Update keystore file: Opens a file selection dialog that can be used to select and upload an existing keystore.

After uploading your own keystore, the following input fields will also appear:

• Keystore password: Password of the keystore
• Keypair password: Password of the key pair

The uploaded keystore must contain a key pair. The correct password for the keystore and the key pair must be specified so that the keystore can be used for encryption and signing authentication requests.

Custom keystores must be Java keystores of type JKS that contain a corresponding 2048-bit RSA key pair. Such a keystore can be generated, for example, with the keytool utility for certificate lifetimes of about 10 years (3650 days) using the following command:
keytool -genkeypair -alias ihr-alias -keypass ihr-passwort -keystore samlKeystore.jks -storepass ihr-passwort -keyalg RSA -keysize 2048 -validity 3650

Extended settings

With a click on Extended settings further parameters for the connection with the identity provider can be configured.

Force authentication

Specifies whether a user should be forced to log in even if a valid session is still present.

Passive authentication

Specifies whether an authentication without interaction with the user should be tried.

User name qualifier

Specifies whether the authentication request should also send the NameQualifier. This is not required by the SAML standard, but for some identity providers it is necessary.

Authentication request signed

Specifies whether the authentication request should be digitally signed.

Logout request signed

Specifies whether the logout request should be digitally signed.

Wants assertions signed

Specifies whether the SAML statements (assertions) are requested to be digitally signed.

Wants response signed

Specifies whether the SAML responses should be digitally signed.

Max. authentication lifetime (seconds)

Maximum duration of an exisitng login to the identity provider. The default value is 3600 seconds.

Max. clock skew (seconds)

Maximum allowed difference in system clock times between the  formcycle Server and the identity provider. The default value is 300 seconds.

Assertion consumer service index

Specifies the index of the Assertion Consuming Service to be used in the login request. The default value is -1, which is the default of the identity provider.

Attribute consumer service index

Specifies the index of the attribute consuming services which should be used for the authentication request. The default value is -1, which is the default of the identity provider.

Authentication request binding type

Specifies the transmission type with which formcycle requests a login to the identity provider.

Response binding type

Specifies the transmission type with which the identity provider responds to a formcycle login.

Logout request binding type

Specifies the transmission type with which formcycle requests a logoff from identity provider.

Logout response binding type

Specifies the transmission type with which the identity provider responds to a logoff from formcycle.

Signature canonicalization algorithm

Specifies the algorithm to be used to convert the signed request into a standardized XML form. http://www.w3.org/2001/10/xml-exc-c14n# is used by default.

Black listed signature signing algorithms

Algorithms that are forbidden for signing.

Signature algorithms

Algorithms allowed for signing.

Signature reference digest methods

Specifies the hash algorithms that are allowed when signing the SAML statements (assertions).

Mapping to user attributes

By clicking on Attribute mapping to users, the configuration fields for mapping individual attributes can be made visible. The mapped attributes can be used in forms via the user variables or the XFC_METADATA. SAML attributes can be configured for the following data. In each case, the name of the saml:Attribute node must be specified.

• Given name (firstname): first name of the user
• Last name (familyName): Last name of the user
• Display name (displayName): Display name of the user
• Username (userName): User name of the user
• Email (mail): Email address of the user
• Language (locale): Language of the user
• Location (location): Location of the user
• Picture url (pictureUrl): Picture URL of the user
• Profile url (profileUrl): Profile URL of the user

Generate service provider metadata

The service provider metadata is the metadata of the formcycle server in the form of an XML file and contains information about the formcycle server, such as the entity ID, endpoints, encryption, signing, etc.. This information is necessary for the identity provider to establish a SAML connection to the formcycle system. Usually, the metadata XML file can simply be passed to the identity provider so that they can register the connection of the formcycle server.
The Generate service provider metadata button can be used to generate the metadata XML file. If frontend servers are configured in the formcycle system, the metadata can also be generated for the frontend servers. A dialog appears with a selection of the server for which the metadata should be generated. When using a dynamic entity ID (see above), the metadata can only be generated for one server at a time. When using a fixed entity ID (see above), the metadata can be generated for several servers in one file.

If the login service is to be used via a frontend server, the metadata must also be generated for this and submitted to the identity provider.