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 information sent by the platform 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.

Mapping Federated Groups

Introduction to Group Mapping

Group mapping is a structured approach used to connect user groups from an Identity Provider (IdP), such as Auth0 or Entra ID to corresponding groups on the Delinea Platform (SP). This integration ensures that users receive appropriate access and permissions on the platform based on their group memberships as defined in the IdP. This capability is particularly important in federated authentication scenarios where identity and access management are centralized in the IdP.

How Group Mapping Works

Administrators define group mappings that link the IdP's user groups to platform groups. These mappings dictate how group attributes received from the IdP are translated to corresponding groups on the Delinea Platform.
Federated groups are not directly added to named platform identity groups. Instead, each IdP group is identified by a unique Object ID, which the platform uses to establish the mapping.

Authentication Flow for Federated Users

When a federated user logs in to Delinea Platform, the IdP sends the platform an attribute or claim named groups. This claim includes the Object IDs of the IdP groups to which the user belongs.
The platform matches these Object IDs to mapped platform groups, automatically assigning the user as a member of the corresponding groups.
The attribute name depends on the IdP and may be defined by the administrator. Consult your IdP to determine the available options.

Access and Permissions Assignment

On the Delinea Platform, user access is governed by roles and permissions, which are assigned based on group membership.
Federated users inherit roles and permissions from the platform groups they are mapped to, ensuring seamless integration between the federated IdP and the platform's access control model.
For more details about roles and permissions, refer to the User Roles and Permissions section.

Configuring Group Mapping

Group mapping on the Delinea Platform can be configured in two ways: manually or automatically (now in private preview). These options provide flexibility for administrators to align the platform’s group structure with the Identity Provider’s (IdP) attributes and manage user access efficiently.

Manual Group Mapping

Manual mapping allows administrators to define explicit mappings between specific group attributes received from the IdP and local groups on the Delinea Platform.

How It Works:

Administrators can assign IdP group attributes values (e.g., IT Admin) to corresponding platform groups (e.g., System Administrator).
The mapping relies on the group attribute name provided by the IdP, which must be specified correctly during configuration.

Example:

A Group attribute name with value IT Admin received from the IdP is manually mapped to the System Administrator local group on the Delinea Platform. This ensures that users belonging to the IT Admins group in the IdP are granted the appropriate permissions associated with the System Administrator group.

Group attribute names and values are case-sensitive. When setting up group mappings between the Identity Provider (IdP) and the Delinea Platform, both the group attribute name and its values are case sensitive and must match exactly.

Automated Group Mapping

This feature is currently available only to customers participating in a private preview. If you'd like to participate to be among the first to try this feature, ask our support or account team for details.

Automated group mapping simplifies the process by dynamically creating and assigning groups based on the claims received from the IdP.

How It Works:

When the Map Groups Automatically option is enabled, the Delinea Platform processes group claims sent by the IdP during authentication.
If a group claim matches a group that does not yet exist on the platform, the platform will automatically create the local group and assign the user to it.
If no group claim is received, the platform can assign the user to a predefined fallback group, ensuring they are granted a baseline level of access.
If a user's group memberships are updated in the IdP, those changes will automatically be reflected on the Delinea Platform during the user's next login.
Administrators can later update or modify the user’s group memberships as needed.

Key Benefits:

Reduces manual effort for administrators, especially in dynamic or large-scale environments.
Ensures new groups and users are incorporated into the platform’s access structure without delays.

Example:

When a federated user logs into the Delinea Platform, the platform checks for group attribute name sent by the Identity Provider (IdP). If a matching group is found (e.g., as shown in the example below for Group), the platform automatically creates a platform local group (if it doesn’t already exist) based on the group claim value and adds the user to it, simplifying the onboarding process. If no group claims are received, administrators can optionally configure a fallback group to ensure such users are still assigned a baseline level of access.

Choosing Between Manual and Automated Mapping

The choice between manual and automated group mapping depends on your organization's needs:

Manual Mapping:

Suitable for controlled environments with predefined group structures.
Provides precise control over group assignments and permissions.

Automated Mapping:

Ideal for dynamic or federated environments where user groups frequently change or expand.
Minimizes administrative overhead while maintaining flexibility.

Mapping Federated Users

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 log-ins.
Update local users with federated user attributes. If you select this option, the claims and attributes (for example, MobileNumber) associated with the mapped Delinea Directory (local) user receive regular, consistent updates based on the claims and attributes associated with the federated user.
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.