# Authentication Provider Basics

Our authentication providers allow accessing the 4ALLPORTAL with external user managements. Users can login to the 4ALLPORTAL using their identity stored centrally in a user authentication service (e.g. Microsoft Active Directory).

On first login, a user will be created automatically in the 4ALLPORTAL. For all further logins, the user is updated with the data from the external system if necessary.

# Available Provider

With 4App Core Engine comes the basic authentication configuration options as well as the complete configuration options for LDAP and SAML 2.0.

For LDAP, we provide two additional Apps:

Authentication Service SSO (opens new window) (to enable Single Sign-on (SSO) for Windows Active Directory (AD) users)
LDAP Sync User (opens new window) (LDAP extension for user synchronization)

Our services support:

LDAP and SAML 2.0
Windows single sign-on (SSO)
user synchronization
user, role and language mapping
configuring two or more authentication services if required

We prefer to use standard providers, but can also work with customer specific.

Provider Types

Authentication providers can be divided into different types. They are defined in enum ProviderType:

USERNAME_PASSWORD
These providers require a username and a password for login
REDIRECT
To login with these providers, a redirect to a targetUrl has to be processed. A session is created after a successful login. The frontend can access it with getSessionAttributes.
LOAD_TOKEN
To login with these providers, a targetUrl has to be processed. The response body contains a token after a successful login. The frontend needs to send this token with the login method.

# Installation

For LDAP and SAML 2.0, no installation is required, all functionality comes with 4App Core Engine.
For configuration, the corresponding admin snap-ins are available:

LDAP: Authentication/LDAP provider
SAML 2.0: Authentication/SAML2 Asserting Party (IDP) and Authentication/SAML2 Relying Party (SP).

For LDAP, two separate 4Apps are available. Install the required 4App following the steps described in its specific documentation:

# Configuration

To configure an authentication provider, go to the corresponding snap-in (e.g. Authentication/LDAP provider):

First part of LDAP snap-in with basic provider settings

Second part of LDAP snap-in with provider specific settings

The snap-in's first part (from field Provider name to Language mapping) is our basic authentication configuration which is the same for all authentication providers: Basic provider configuration.
The snap-in's second part is always a provider specific configuration. Again, refer to the provider's specific documentation:

SAML 2.0 Order

Note that for SAML admin snap-in SAML2 Asserting Party (IDP), the basic configuration fields have a deviating order and are grouped with SAML specific fields.

Custom Snap-in Display

Note that depending on the installed provider, and the customer's needs, the snap-ins may be customized. A snap-in's field order or displayed number can thus differ from the standard fields shown above.

# Storage

The corresponding configuration XML file is stored in the file system's folder custom/global/authentication_provider/{provider}, e.g. file My LDAP Provider in folder custom/global/authentication_provider/ldap.

# Basic Provider Configuration

The following table describes the snap-in's first part with the fields for basic authentication configuration, valid for default authentication providers (except SAML, see above):

Field	Attribute	Type	Description
Provider name	name	string	Choose a unique name for the authentication provider (it will also be the filename of the configuration XML file). Naming rules
Visible	visible	boolean default: true	If set to "true", the provider is shown on the authentication provider list in the login GUI.
Order	order	int	Position on authentication provider list in login GUI. The position of the default provider is `0`. All below `0` will be listed before the default provider, all higher than `0` will be listed after.
Ignore frontend language	ignore_frontend_language	boolean	If you set "Ignore" to "true", the provider's language is used (despite the user language from the database or the browser's language).
Default role id	default_role_id	string (CEId)	Assigns this role to new users if no explicit mapping was configured.
Default language	default_language	string	Assigns this language to new users if no explicit mapping was configured. If the language was not set, the user will see the default 4ALLPORTAL language.
Create contact	sync_to_contact	boolean default: false	Parameter will be ignored if 4App Essentials is not installed. If set to "true", a contact will be created (and later updated) on login automatically. It is also possible to activate sync user later by changing the user attribute `sync_to_contact` to "true".
Mapping of user fields	user_mapping	complex	Use to map external user data to fields from 4ALLPORTAL's User module (User mapping details).
Role mapping	group_role_mappings	complex	Use to map external groups to 4ALLPORTAL roles (Role mapping details).
Language attribute	language_attribute	string	Add the external attribute's name to read the language content from.
Language mapping	language_mapping	Map<String, String>	Use to map external languages to 4ALLPORTAL languages (Language mapping details).
URL after logout (provider)	logoutUrl	string	Set a URL to call after logout (only for the specific provider configured). You can set a URL for each provider configured. If not configured, the general logout URL (`logoutURL`) will be called (set in admin snap-in `General system configurations/User settings/Sessions`) or, if not configured either, the default 4ALLPORTAL login page.

Login Screen

After configuration, you may define a default username/password provider, or a default (chosen) provider for login in snap-in Authentication/Authentication Provider (details).

# Naming Rules

The 4ALLPORTAL uses the name from field "Provider name" for the login screen display, and the XML file name. Please consider the following rules when naming your provider:

The name of the authentication provider should not end with "_sso". If you use an LDAP provider with SSO, its name will be generated with "name" + "_sso" when a single_sign_on_url is set (only with 4App Authentication Provider LDAP).
The names of all existing authentication providers have to be unique. If a name is duplicate, an error will be logged.

# User Mapping Details

Core Engine Field
Target: Name of the User module's field into which the content shall be stored.
External Field
Source: Attribute of the external system from which to retrieve the content.
Overwrite
Default: true. If set to "false", the field will only be set on insert and not on update.

Required Mapping

Field ext_id must be mapped, also the following fields are important:

username
email
firstname
lastname

Note that for field ext_id "Overwrite" is always false . The parameter will be ignored.

# Role Mapping Details

Role
Name of the target 4ALLPORTAL role.
Group
Name or ID of the source group in the external system.
Priority
If the external system sends multiple groups, the group with the lowest value will be selected. Allowed values are from 0 (highest) to 2147483647 (Integer.MAX_VALUE). If not set, it equals the highest priority 0.

Available Group Values

In field Group, you can enter any values that your authentication service sends for group mapping. The values depend on the authentication service and the configuration of the authentication provider (SAML, LDAP, ..., custom - if role mapping is implemented).

# Language Mapping Details

External language
Name of the language in the external system.
Core Engine language
Language key from your 4ALLPORTAL (e.g. en_US). It is possible to map different external languages to the same 4ALLPORTAL language key.

# Password Restrictions and External ID

When configuring an authentication provider, please consider the following:

Password restrictions only work for default 4ALLPORTAL user.
- External systems are able to define the length and complexity of a password.
- Setting a maximum for login attempts is not possible, because a user is not known until they successfully logged in.
The Username from the User module does not have to be unique, because field ext_id will be used for mapping.
Field ext_id of a user has to be set to a not changeable id of the external system. For Active Directory: objectSid.

You have three options to display authentication providers on your login screen:

Let users choose from all configured and visible authentication providers (Microsoft Active Directory, Domino, eDirectory ...).
Set one username/password provider that will additionally be called when entering 4ALLPORTAL credentials.
Predefine one chosen provider that displays/logs in per default.

Login screen with two LDAP providers to choose from

Login screen with chosen SAML provider (AD FS) and further SAML providers to choose from

# Default Username/Password Provider

You can define one of your configured username/password providers to be called additionally/as a fallback.

Users can log in with either their default 4ALLPORTAL credentials, or the default username/password provider's credentials (e.g. an LDAP provider). Both are checked when entered on the login screen.
This works even if that provider is invisible and cannot actively be selected by a user.

Go to admin snap-in Authentication/Authentication Provider.
In field Default Username/password authentication provider select one configured username/password provider.
Set the provider in it's snap-in to visible = false.
Activate your settings with a reload.

Your default username/password provider is stored in XML file authentication_provider in folder /custom/global/authentication_provider in element <default_provider>.

Fallback

When logging in with an authentication provider of type UsernamePassword, you can usually set connectorName to choose the provider. The frontend passes the connectorName to the backend.

If a login is tried with a UsernamePassword provider and connectorName=default or no connectorName is passed to the backend, the following fallback applies:

A login with the default 4ALLPORTAL is tried.
A login with the configured username/password provider is tried.

# Username/Password Provider as a Workaround

In some cases it is not possible to pass a connectorName (e.g. the PowerPoint Plugin's login cannot do this). In order for the login to still work with a configured provider, set it as the default username/password provider.

# Default (Chosen) Provider for Frontend

If you want an automatic provider selection/automatic login without the need for user interaction (e.g. when working with SSO), you can define one of your configured providers as the default (chosen) provider. Depending on its type, the following will happen:

If the provider is of type username/password (e.g. LDAP), it is always preselected on the login screen. A user still needs to enter their credentials and may select another provider.
If the provider is of type redirect (e.g. SAML), the corresponding URL is called (depending on configuration, a user may be logged in automatically).
If the provider is of type load_token (e.g. LDAP with SSO), the login is started automatically (depending on configuration, no login screen, or the default browser login will be shown).

Go to admin snap-in Authentication/Authentication Provider.
In field Default provider for frontend you can select one configured provider (any type) as the chosen default (value "default" from the drop-down selects the regular 4ALLPORTAL login).
Activate it with a reload.

Your default (chosen) provider is stored in XML file authentication_provider in folder /custom/global/authentication_provider in element <chosen_provider>.

# Provider URL

If you want to display one specific provider in your login GUI (even if set to invisible or if set as the default username/password or chosen provider), call URL {server_url}?connectorName={connectorName}. The connector {connectorName} will be displayed as the active connector in your login GUI.

← Request management Active Directory: User Search Filter →