# How to configure Authentication Provider SAML

To configure SAML, you need to configure the 4ALLPORTAL as your Service Provider (SP) and one or more Identity Providers (IDP) depending on your used service(s).

Service Provider = application to which access should be provided, e.g. the 4ALLPORTAL
Identity Provider = central user database with the stored user information, e.g. Microsoft ADFS

# Configuring the Service Provider

To configure the Service Provider use admin snap-in Authentication/Authentication provider SAML in the administration area.

All changes made here will be stored in the following files / folders in folder custom/global/authentication_provider/saml:

file / folder description
file saml_sp.xml SP configuration file
file idp/[IDP_NAME].xml IDP configuration file (one for each configured IDP)
folder certificates/sp For SP certificate with private key. A file with extension .p12 or .pfx. Other files will be ignored.
folder certificates/idp/[IDP_NAME] For IDP certificate with name IDP_NAME. A file with extension .pem, crt, or .cer. Other files will be ignored. This file may contain more than one certificate.
folder metadata/idp/[IDP_NAME] For IDP metadata file with name IDP_NAME. Necessary if no access to metadata URL.

# Quick guide (SP)

  1. Set entity_id: name the customer sees on the IDP.
  2. Set scheme (HTTP/S) and server name to 4ALLPORTAL URL.
  3. Upload the certificate file and configure both certificate_key and certificate_password.
    A self-generated certificate with a long runtime can be used. The IDP(s) will get this certificate via the SP metadata.
  4. Export metadata of the SP and give it to your customer / system owner.
    [EXTERNAL_URL]]/saml/metadata

# Snap-in fields details (SP)

field attribute description
Entity ID entity_id Unique identifier of the SP. The configuration on the IDP will be created with this name.
Entity URL (optional) entity_base_url This URL will be generated into the SP metadata.
If this fields remains empty the Entity URL will be generated automatically from attributes schema, server_name, server_port, context_path, and include_server_port_in_request_url.
Protocol scheme Allowed values: HTTP and HTTPS. Value used to generate SP URL.
Please note: Use HTTPS if possible. ADFS only supports HTTPS.
Host server_name Name of the SP host. Value used to generate SP URL.
Port server_port SP port. Value used to generate SP URL. If port <= 0, the port from the request will be used.
Path context_path Path where the web application is accessible. Must in most cases be set to /. Value used to generate SP URL.
Use port in URL include_server_port_in_request_url Allowed values: true and false. If set to "true", the port will be included in SP URL.
Authentication contexts authnContexts List of authentication contexts the IDP is allowed to use when authenticating a user. Default: empty. Allows the SP to specify the login method that the IDP should use. If the IDP does not support any of these, no login is possible.
In ADFS, urn:oasis:names:tc:SAML:2.0:ac:classes:Password always allows to enable the password request, even if the IDP uses Kerberos for Windows Authentication by default.
Validity period for SAML messages in seconds response_skew Sets the validity for messages between SP and IDPs in seconds. Default: 60 seconds. Maximum should not be higher than 90.000 seconds. Please consider different time zones and summer/winter time.
Max authentication age max_authentication_age Sets the maximum time between a user's authentication and processing of an authentication statement. Default: 7.200 seconds. Increase this if you get an error "Authentication statement is too old to be used with value ..."
Max assertion time max_assertion_time Customizes the maximum time between an assertion creation and its usability. Default: 3.000 seconds. Maximum should not be higher than 90.000 seconds.
Sign metadata sign_metadata Allowed values: true and false. Default: "false". If set to "true", SP (4ALLPORTAL) metadata will be signed.
ECP enabled ecp_enabled Indicates whether Enhanced Client/Proxy (ECP) profile should be used for requests. Allowed values: true and false. Default: "false". If you only need access via browser, the default can remain.
Signature algorithm name signature_algorithm_name Encryption configuration. Default: RSA. All IDPs must support the same.
Signature URL signature_algorithm_uri Encryption configuration. Default: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256. All IDPs must support the same.
Digest algorithm URL digest_algorithm_uri Encryption configuration. Default: http://www.w3.org/2001/04/xmlenc#sha256 All IDPs must support the same.
Certificate file N/A Upload the certificate file here. (more details).
Key for alias in the certificate file certificate_key Name under which the certificate is stored in the certificate file. Permitted file extensions .p12 or .pfx.
Certificate password certificate_password Password to access the certificate file.
Show attributes print_attributes Allowed values: true and false. After a successful login, the attribute names are shown in the log. Set to "true" only for configuration and if you do not know with which name attributes are transferred.

# Example Service Provider configuration file

<authentication_provider>
  <entity_id>4allportal</entity_id>
  <entity_base_url>https://example.4allportal.net</entity_base_url>
  <scheme>https</scheme>
  <server_name>example.4allportal.net</server_name>
  <server_port>0</server_port>
  <context_path>/</context_path>
  <include_server_port_in_request_url>false</include_server_port_in_request_url>
  <!--
  <authnContexts>
    <value>urn:federation:authentication:windows</value>
    <value>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</value>
  </authnContexts>
  -->
  <response_skew>7200</response_skew>
  <max_authentication_age>7200</max_authentication_age>
  <max_assertion_time>3000</max_assertion_time>
  <sign_metadata>true</sign_metadata>
  <ecp_enabled>false</ecp_enabled>
  <signature_algorithm_name>RSA</signature_algorithm_name>
  <signature_algorithm_uri>http://www.w3.org/2001/04/xmldsig-more#rsa-sha256</signature_algorithm_uri>
  <digest_algorithm_uri>http://www.w3.org/2001/04/xmlenc#sha256</digest_algorithm_uri>
  <certificate_key>4allportal</certificate_key>
  <certificate_password>123456</certificate_password>
</authentication_provider>

# Configuring an Identity Provider

To configure an Identity Provider use admin snap-in Authentication/Identity provider SAML in the administration area.

# Quick guide (IDP)

  1. The customer / system owner must configure the IDP in their Azure, Active Directory, KeyCloak etc., using the metadata file generated by the SP. This cannot be done in the 4ALLPORTAL.
  2. After configuring, the customer's IDP must be configured and tested in the 4ALLPORTAL.

# Snap-in fields details (IDP)

  • The first part of fields (from Provider name to Language mapping, except fields Attribute for role mapping and SAML groups from multiple attributes) is our general authentication configuration. For details and descriptions of these fields, please take a look at our Authentication base documentation (opens new window).

  • The following fields are SAML specific:

field attribute description
Attribute for role mapping group_attribute SAML attribute to map a group / role to a user.
SAML groups from multiple attributes group_attribute Allowed values: true and false. Default: "false". If "true", allows to get group values from SAML from multiple attributes with the same name instead of one attribute with array result.
Metadata URL metadata_url Sets the URL to the metadata of the IDP. Fields Certificate file, Reject invalid metadata, and Enable certificate verification are related to this parameter (more details).
Metadata File N/A Upload the metadata file here. If there is no access to the metadata URL, the metadata file can be used for configuration.
Certificate file N/A Upload the certificate file here. To allow access to a HTTPS metadata URL, you need to put the parent of the certificate chain to the URL into a PEM file. Add only parent certificates to avoid problems in case a child certificate will change.
If Enable certificate verification is "true", add the certificate for the signing key to the PEM file. (more details).
Reject invalid metadata requires_signature Allowed values: true and false. Default: "false". If set to "true", metadata from this provider is only accepted if correctly signed and verified (requires field Metadata URL).
Enable certificate verification metadata_trust_check Allowed values: true and false. Default: "true". If the metadata from field Metadata URL is signed, set this to "true" to enable certificate verification. The signing key for the metadata must be added to the Certificate file.

# Metadata URL details

If this is a URL with HTTPS, a certificate file must be stored for the IDP. This file ...

  • must contain the PEM certificate for accessing metadata_url
  • may contain additional PEM certificates. If requires_signature and metadata_trust_check are set to "true", the signing certificate of the IDP may need to be included.

# Example Identity Provider configuration file

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<identity_provider>
  <visible>true</visible>
  <order>100</order>
  <ignore_frontend_language>false</ignore_frontend_language>
  <default_role_id>...</default_role_id>
  <sync_to_contact>false</sync_to_contact>
  <user_mapping>
    <atr ce="firstname" extern="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"/>
    <atr ce="ext_id" extern="objectSid" overwrite="false"/>
    <atr ce="email" extern="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"/>
    <atr ce="username" extern="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"/>
    <atr ce="lastname" extern="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"/>
  </user_mapping>
  <group_role_mappings>
    <group_role_mapping>
      <prio>0</prio>
      <group>Domänen-Admins</group>
      <role>Admin</role>
    </group_role_mapping>
    <group_role_mapping>
      <prio>1</prio>
      <group>Domänen-Benutzer</group>
      <role>User</role>
    </group_role_mapping>
  </group_role_mappings>
  <language_attribute>preferredLanguage</language_attribute>
  <language_mapping>
    <language>
      <extern>Deutsch</extern>
      <ce>de_DE</ce>
    </language>
    <language>
      <extern>englisch</extern>
      <ce>en_US</ce>
    </language>
  </language_mapping>
  <metadata_url>https://example_idp.4allportal.net/FederationMetadata/2007-06/FederationMetadata.xml</metadata_url>
  <requires_signature>true</requires_signature>
  <metadata_trust_check>false</metadata_trust_check>
  <group_attribute>http://schemas.xmlsoap.org/claims/Group</group_attribute>
</identity_provider>

# Certificates

# SP certificate file

The certificate file must have the format pkcs12. Allowed file extensions are: .p12 or .pfx.
A self-generated certificate with a long runtime can be used. The IDP(s) will get this certificate via the SP metadata.

# Download IDP certificate

openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
# certificate valid for 10 years: You can always chose the default value.
openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.pem
# generate pkcs12: Set password because without the certificate file isn't usable.
openssl pkcs12 -export -inkey server.key  -in server.pem -name 4allportal -out 4allportal.p12

Remember to set a password.

# Service Provider configuration:

certificate_file: Parameter after -out - "4allportal.p12"
certificate_key: Parameter after -name - "4allportal"
certificate_password: Manually entered password for the file

# IDP certificate file

When installing the IDP, it receives certificates via the metadata. As soon as these expire, they must be updated on the IDP.

IDP description
Keycloak The server.pem generated during certificate creation can be imported in the keycloak under SAML Keys.
Windows ADFS The server.pem must be converted with: openssl x509 -outform der -in server.pem -out win.cer.
Afterwards, this certificate can be uploaded via AD FS Management/Relying Party Trusts for Encryption and Signature.

# Self-generated IDP certificate

Required if the IDP is accessed via HTTPS, and the metadata is read via metadata_url. A PEM certificate with the complete certificate chain is required. If on the other side the metadata is stored as a file, the IDP certificate is included in that file.

Possibilities to create:

  • Firefox

    • Call the URL of the IDP in Firefox and click the lock next to the URL.
    • Open "Connection details/More information/Show certificate/Details
    • Export
    • X.509 certificate including issuer (PEM).

  • ADFS server

    • AD FS Management/Service/Certificates/Service communications
    • View Certificate
    • Copy to file
    • No, do not export the private key
    • Base-64 encoded X.509 (.CER)
    • Yes, do "Include all certificates in the certification path if possible"

# Login screen

To define a default or chosen provider for login, please take a look at our Authentication Base documentation here (opens new window).

# Set icon and text for login GUI (optional)

To configure the icon, just replace or copy your chosen svg file to custom/global/styles_pre_login/default/GLOBAL-AUTHENTICATION_PROVIDER-{$provider_name}.4apicon.

Define texts for the login page in a new file, e.g. custom/global/locale_pre_login/en_US/saml_login.properties.

# Set pre login locale for login GUI (optional)

  • locale keys for LDAP
    • L-GLOBAL-CONNECTOR-{$provider_name}
    • L-GLOBAL-CONNECTOR-{$provider_name}-INFO

Reload or restart your 4ALLPORTAL and check your login page.

# Troubleshooting

If the exception: javax.net.ssl.SSLPeerUnverifiedException: SSL peer failed hostname validation for name: null occurs, the certificate chain for the IDP is corrupt/expired. The certificate needs to be updated.

← How to integrate SAML login to 4ALLPORTAL with Azure as IDP →

Request missing documentation