Federation Management

Add a Federation Service Provider

From the left navigation, click Settings, then select Federation providers from the secondary menu.
On the Federation Providers page, click the Add Provider button.
Select SAML or OIDC. The Add Provider page opens, displaying all controls necessary for adding a provider.

You do not need to configure both OIDC and SAML applications for your integration. Depending on your organization's infrastructure and preferences, you can choose either OIDC or SAML.

Consult the detailed documentation for these specific IdPs:

Refer to your IdP’s documentation for guidance on SSO integration, as similar procedures can be followed for the Delinea Platform.

Enable a Federation Service Provider

From the left navigation, click Settings, then select Federation providers.
Click the name of one of the federation providers listed.
On the Settings tab, click Edit.
Next to Status, select the Enable check box.
Click Save.

Delete a Federation Service Provider

From the left navigation, click Settings, then select Federation providers.
Click the name of one of the federation provider you wish to remove.
Delete the provider from either the table, the preview panel, or the provider’s detail page.

You cannot delete a provider when it is in an enabled state, so you must disable the provider prior to deleting it. Proceed with caution when deleting the provider, as this action may affect user access to the platform, and it cannot be undone.

Advanced Settings (SAML only)

Customize Certificate Issuer Sent to IdP: This setting overrides the default Certificate Issuer (also referred to as the Entity ID) information sent to the Identity Provider (IdP). This setting should be used cautiously and only when necessary to maintain compatibility with your IdP configuration.

ForceAuthN: Select the checkbox to force authentication, or deselect it to disable forced authentication. When enabled, the Force Authentication (ForceAuthN) setting asks the identity provider (IdP) to require the user to authenticate again, even if the user has an existing session or has previously authenticated. The IdP must ignore any existing session and prompt the user to provide their credentials for authentication. The support and behavior for this option may vary depending on the IdP's SAML implementation.

Use Login Hint: This setting applies to SAML. Enabling this option transmits the username to the IdP using the login_hint parameter in the HTTP request, with the username automatically populating during the login process to the IdP. For OIDC, the username is always passed to the IdP. Please refer to your IdP documentation to confirm whether this configuration is supported and to understand its implementation details.

Request Binding: This setting controls the method for binding SAML authentication requests to the communication protocol. By default, it is set to 'HTTP-Redirect' for URL-based binding but alternatively can be set to 'HTTP-POST' for form-based binding.

Sign Request: When enabled, this setting ensures that the SAML authentication request sent to the identity provider is digitally signed for added security. You can upload the certificate in either format pfx or p12.

Advanced Settings (OIDC only)

Platform federation functionality supports two OIDC flows: Code Flow and Implicit Flow.

For optimal security and reliability, Delinea recommends using Code Flow by default. Implicit Flow should be used cautiously and only when necessary, considering its potential security risks.

Code Flow (Default):

Applied by default
Includes an additional step where an authorization code is exchanged for tokens
Strongly recommended due to its superior security features, and suitable for most scenarios

Implicit Flow (Optional):

Allows clients to directly obtain ID Tokens after authentication
Not recommended due to its inherent security vulnerabilities

Re-authentication with the IdP

By default, federated users are not prompted to re-authenticate with the IdP every time they try to log in to the platform, assuming the user has a valid authentication session with the IdP. This experience may not be desired on shared workstations, or if re-authentication is required for sensitive operations, such as managing requirements for governance. The platform allows Administrators to configure the desired behavior as needed for SAML or OIDC providers. When the user logs out of the Delinea Platform, the user's overall session with the IdP is not impacted or invalidated.

Prompt for Re-authentication (OIDC only)

On the IdP provider's page, click Edit.
Under Settings, set Prompt to the desired option.

Support for these options depends on the OIDC implementation used by the IdP.

Option	Description
Not specified	Default option. If the user has a valid authentication session with their IdP, they will not be prompted to authenticate again. If the user is not authenticated or has no active session, they will be redirected to the IdP to initiate the authentication process.
Prompt for Authentication (login)	Every time the user logs out of the platform and tries to log back in, they will be required to enter their credentials and authenticate with their IdP again, even if they are already logged in.
Select Account (select_account)	This option forces the user to select an account to authenticate with. This is useful when you want to provide the user with the option to switch accounts.

Attribute Mappings

User attributes are passed from an identity provider (IdP) such as Auth0 to the Delinea Platform Service Provider (SP) during the authentication and authorization process. Some default attributes for SAML and OIDC are provided out of the box, and new, custom attributes can be added.

The following screen shot provides an example set of custom attributes for SAML with Auth0.

The following attributes are required to properly set up federation on the Delinea Platform:

sub: nameidentifier. The user's unique identifier.
upn: upn. User Principal Name. The user account login name.
email: EmailAddress. The user's email address.

Optionally, these additional user attributes can be mapped on the platform:

displayname: Name (for example, Aditi Patel). While the displayname attribute is optional, it is advisable to include it for optimal results.
MobileNumber: The user's mobile phone number.
OfficeNumber: The user's office phone number.
HomeNumber: The user's home phone number.
PlatformUserMembershipType: Indicates whether the user is an Employee or Vendor
Description: Additional descriptive text.

Custom attributes for IdP federation can vary depending on the specific IdP. Consult the documentation and support resources of your chosen IdP.

We recommend against setting up a user account in which the User Principal Names (UPN) serves as the User ID (UUID). UPNs sometimes change, and when a UPN that was serving as a user’s UUID changes, the platform creates a new account with no permissions and assigns the existing user to the new account. Therefore that user loses all platform permissions they previously had.

Group Mappings

Group mapping is a method for associating user groups from an IdP, such as Auth0, to corresponding local groups on the Delinea Platform Service Provider (SP). This ensures that the user is granted the appropriate level of access based on their group memberships in the IdP's system.

Administrators can define mappings that dictate how the groups received from the IdP should be translated into specific groups on the platform.

On the Delinea Platform, federated groups are not added to named platform identity groups. Instead, they are mapped to platform groups through the IdP group's Object ID.

When a user logs in with an IdP's federated email domain, the platform logs them in as a federated user. The user is first authenticated when the IdP sends the platform an attribute/claim named groups for that user, which includes an Object ID for each IdP group that user belongs to. The Object ID maps to platform groups, and the user is added as a member of those mapped groups.

On the platform, user roles and their associated permissions are assigned to users through the users' memberships in platform groups, including platform groups mapped to federated groups as described later in this page. For more information on groups, roles, and permissions, see User Roles and Permissions.

The following screen shot shows an example of a group attribute with the group 'primary' received from the IdP, which is mapped to the System Administrator local group on the Delinea Platform.

Group Mappings

User Mappings

User mapping enables federated users (from Entra ID, Okta, Ping, etc.) to be recognized by their Active Directory identity after logging in to the Delinea platform. Users authenticating with their AD credential will be recognized by their AD identity instead of as a remote federated user. By mapping to the AD user, privileges are assigned based on AD group memberships, which is easier than mapping federated groups from the SAML provider to the Delinea Platform.

Map a federated user to an existing directory user

Required

When you select Required, you have three additional options:

Create local user if unable to map. If you select this option and an existing user is not found on the platform, a corresponding Delinea Directory user is created, and login is authorized. When the new Delinea local user is generated, it will subsequently be updated with the federated attributes. This functionality facilitates the inbound provisioning of Delinea users from another federation. By default, the attributes of the mapped user take precedence, and the assertions of the federated user are disregarded in future logins.
Update local users with federated user attributes. If you select this option, you guarantee that the mapped Delinea Directory user attributes receive regular, consistent updates based on the federated assertions.
Select neither option. If you select neither option and no existing platform user matches the federated user, the federated user's platform login attempt will fail, accompanied by an error message similar to the following:

Optional

If you select Optional, when a federation user attempts to authenticate, the platform maps the user to an existing Active Directory account, based on their User Principal Name (UPN). If mapping is not possible, the platform automatically creates a new Federated user to enable a seamless authentication process.

Although the two user objects are mapped, they are not reconciled, so they appear as separate users on the platform.

Disabled

If you select Disabled and another user with the same username exists in another directory service, a federated user's login attempt will fail. Below is an example of an error message generated when an attempt to log in to the platform causes a collision between a federated user and one or more other users on the platform with the same UPN.

Debugging

The Delinea Platform offers a self-service debugging tool for troubleshooting federation setups with IdPs. Administrators can use the debugging tool to independently identify, diagnose, and resolve common problems encountered during the configuration and management of federated authentication systems.

On the provider’s page, click the Federation console tab. You can also access the federation console from various shortcuts.
Click the Start Debugging button. The indicator next to the button changes from Stopped to Running.
Launch a new browser window, preferably in Incognito mode.
Navigate to your platform tenant URL.
Log in to the platform using a federated account.
Upon successful login using the federated account, you can go back to the original platform tab to review the logs captured. Each login event appears in a row displaying session details described in the following table. You can expand the entry to view additional details.

Column	Description
Timestamp	The date and time for the federated user's login event.
Email	Email address associated with the federated user.
UPN	User Principal Name; represents the federated user's identity.
Incoming Attributes	A collection of attributes and values received by the platform from the IdP for the federated user.
Mapped Custom Attributes	Represents the custom destination attributes on the platform and their corresponding values received from the IdP.
Mapped Groups	Contains information about the federated user's group memberships alongside the mapping assignment to local groups on the platform.
Missing Required Attributes	Any mandatory attributes that are missing for the federated user.

Logs are captured up to a limit of 30 minutes. After that, you need to rerun debugging for continued logging. Logs from previous captures are removed at the end of each logging period.

Analyzing Captured Logs

The log provides insight into the following:

All the claims received from the IdP. Each attribute consists of a key-value pair, where the key represents the attribute name, and the value represents its corresponding value.
The mapped custom attributes and corresponding values.
Group mappings, if any. This depends on whether there is a pre-existing configuration for group mappings.
Flagging of any essential attributes that might be missing.
A complete log of the SAML request and response.
Various other information such as Issuer and Entity ID that can aid in troubleshooting.

The following example demonstrates a login request by an Auth0 user to the Delinea Platform.