Setting up Federation
This Quick Start will help you set up your RapidIdentity IdP (Identity Providers), enable federation for Service Providers (SPs), and enable MFA (Multi-factor Authentication) for web logins. For a general Federation overview, including common terminology, refer to that section in the Reference Material.
Note
If this in a Cloud deployment, this setup has already been completed. RapidIdentity Cloud has an authentication infrastructure that is built, hosted, and managed by a third-party service provider on a subscription basis. Cloud solutions are predominately cloud-based and can be single sign-on (SSO).
Use the checklist to reference the quick start steps for Federation Setup.
Create RapidIdentity as an Identity Provider
Configure a Service Provider
Assign Applications
Prerequisites
A valid host name must be defined that resolves to your RapidIdentity instance.
If this is a stand-alone instance, create a host name record in the DNS server or, for development and testing, create host entries in the local hosts file.
Note
Verify the "Base URL" contains your DNS host for the environment: https://[your-host-name]/idp.
RapidIdentity Federation IdP Setup
The RapidIdentity Federation Identity Provider setup requires access to the RapidIdentity Configuration Module. Users must log in to RapidIdentity as a user with the System Administrator or Tenant Administrator role.
From Configuration, click Identity Providers in the Security options.
New Identity Provider Setup
If the Identity Provider has not yet been set up, follow the below steps.
From Identity Providers, select IDP Configuration and click Create New Configuration.
From the Identity Provider Configuration window enter the following values:
Identity Provider Configuration Type*: Automatic/Quick Configuration
Domain*: Enter the IP address of the appliance that will serve as the portal that users will access and that is allocated to the Federation activity.
The Identity Configuration workspace will then be populated with the Identity Provider Configuration data. Click here for more information on Identity Provider configuration data.
From the Configuration menu, click Integration from the Security section.
From the Integration menu, click Federation.
Federation Hostname: "localhost'
Federation Username: Enter your domain adminstrator's name
Federation Debug Level: None
Click Update Password.
Enter the Domain Administrator's password.
Click Save.
Important
You must select to Trigger Service Reload and Trigger Web Reload to activate the new attributes, or upon logging out, the server configuration will not be saved and future access will fail. An error similiar to this will appear
Validate the Identity Provider Setup
If the Identity Provider setup was performed successfully, you will be able to validate the Adminstrator login in the RapidIdeintity Portal.
Perform these steps using an appliance that has Portal_UI capability.
Log into your Portal using the Domain Administrator account used above in the IdP configuration as the Internal-Appliance Configuration-LDAP.
Answer the Setup Security Questions.
Choose either the Pre-defined or the custom Your Choice questions.
Note
Verify the "Base URL" contains your DNS host for the environment: https://[your-host-name]/idp
RapidIdentity IdP Configuration
The Identity Provider Configuration page contains various URL sites, links to download metadata and certificate information, the certificate fingerprint, and an option to ensure consistent client address. This page provides administrators with their Registered Identity Provider information for user authentication in web applications.
Expand Identity Providers from the Left Menu Items, and click IDP Configuration.
 |
The current Identity Provider Configuration will be displayed in the workspace. For details, refer to the below table.
Field | Description |
|---|---|
Entity ID | The SAML EntityID of the Identity Provider |
Base URL | The base URL to the IdP |
Logout URL | The IdP's logout URL |
Live Metadata URL | The URL to view the metadata associated with the provider which allows the remote vendor to access the metadata at any time. |
Metadata | Click to download the registered metadata for the Identity Provider to save as an XML file. |
Signing Certificate .PEM File | Click to download the (.PEM) encryption certificate used by the Identity Provider. |
Signing Certificate .CER File | Click to download the (.CER) signing certificate used by the Identity Provider. |
Certificate Fingerprint | The SHA1 fingerprint of the IdP's signing and encryption certificate |
Ensure Consistent Client Address Checkbox | When this box is checked, the client address is maintained across clustering and is bound to a particular client IP address and is only considered valid when used from that same IP address. This box should remain un-checked if the IdP is behind a load-balancer whose own IP address can change over time (e.g. AWS ELB). The box should be unchecked when users are required to re-authenticate and when an error message occurs stating that a cookie was sent from one address but issued to another address. Sample error message:
|
The Delete Configuration function should be used only if there is an issue with the IdP configuration, such as a mismatch of IP address or a change to the DNS name, as the IdP configuration will be deleted and must be reconfigured completely.
Important
Deleting an IdP configuration will also result in deleting all SAML Relying Party configurations and will require reconfiguration of the IdP, Relying Parties, and all federated Service Providers.
RapidIdentity Service Providers SAML Authentication
RapidIdentity supports SAML authentication and is configured as a Service Provider that allows immediate access to any licensed RapidIdentity component. individual RapidIdentity Components (e.g. Portal, Connect) do not need to be configured individually as Service Providers; however, one service provider does need to be configured for all of RapidIdentity and registered to RapidIdentity.
Note
If configuring RapidIdentity for SAML authentication against an Identity Provider in a different domain, that domain may require being added as Allowed Origin in the RapidIdentity CORS Configuration . The Allowed Origin value should be formatted as "https://identity_provider_domain."
Follow these steps to configure RapidIdentity SAML authentication as a Service Provider.
After IdP configuration is complete, click on the Configuration Module and select Service Providers from the Security section.
Important
The identity Provider must be configured in RapidIdentity. IDaaS tenants have a pre-configured IdP.
Click Service Providers from the left hand menu.
This page displays any current configurations, along with action buttons to configure new applications, and assign applications.
Click Register Service Provider+.
Hover over the question marks for additional information on completing the fields and for an example.
The table below describes how to complete the Service Provider information.
Field
Description
Name
Enter a name for the Service Provider.
Description
Optionally, enter a description for the service provider.
Entity ID
The unique identifier for the SAML 2.0 Service Provider. When federating with a particular Identity Provider, it must be unique among all of the Relying Parties the Identity Provider federates with. This value must be a valid URI or URN and it is recommended to use the base RapidIdentity URL (e.g. "https://{host}/")
Base URL
Enter the URL from which to construct SAML endpoints; the URL must be comprised of protocol, server, port, and context path. and is the base URL to the Rapididentity instance (e.g. "https://{host}[:{port}]/"). Generally, this is exactly the same as the Entity ID, but a requirement.
Logout URL
A URL to redirect the user's browser to after logging out of the local RapidIdentity session. This typically points to the logout URL of the Identity Provider, such as "https://idp-host/idp/logout." The URL must be comprised of protocol, server, port, and context path. Click to automatically populate with the current IdP logout URL.
Organization Name
Enter the name of the organization associated with the provider. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
Organization URL
Enter the website of the organization associated with the provider. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata .
Contact Email Address
Email address for the contact at the organization. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
IDP Metadata
Paste the XML metadata from the server, or click to automatically populate with the metadata of the IdP configured to run in the same RapidIdentity cluster.
Tip
Open the Service Provider's metadata URL in a web browser and copy and paste it into the Metadata input box. Also, a metadata URL can not be used as metadata.
After entering required information, click Save. The service provider will be listed in the workspace and can be assigned applications for login.
To activate this Service Provider configuration and enable SAML authentication for RapidIdentity, select the entry in the list and click Assign to RapidIdentity in the action bar.
If successful, the Assigned to RapidIdentity column will display a "Yes" value. A brief confirmation message, "Saved" will be displayed at the top of the workspace.
In order to refresh the configuration, return to the IDP Configuration workspace.
Click Trigger Service Reload.
Close all browser sessions.
Re-open browser and access your RapidIdentity instance. You should immediately notice that the login page is updated showing help links and the Claim Account button.
Click Delete from the action bar to delete a selected Service Provider from the workspace.
Caution
Deleting the active Service Provider configuration will cause RapidIdentity to cease requiring SAML authentication until a new Service Provider configuration is assigned. If the Service Provider configuration needs to be changed for whatever reason, it's often better to create the new one, assign it and then delete the old configuration.
Click Details next to an entry in the workspace to view or edit the Service Provider details.
RapidIdentity Federation IdP Setup
The RapidIdentity Federation Identity Provider setup requires access to the RapidIdentity Configuration Module. Users must log in to RapidIdentity as a user with the System Administrator or Tenant Administrator role.
From Configuration, click Identity Providers in the Security options.
The Identity Provider Configuration page contains various site URLs, links to download metadata and certificate information, the certificate fingerprint, and an option to ensure a consistent client address.
Configure a Service Provider for SAML SSO
This Quick Start will help you to configure a new Service Provider for single sign-on federated with your RapidIdentity Tenant Identity Provider(IdP). Users access the web-based service through an Applications icon in the RapidIdentity Portal.
The IdP must be configured in RapidIdentity and the Service Provider Application must be configured to use the RapidIdentity IdP. Refer to Setting up the Federation Administrative User Guide for detailed configuration information.
From the Configuration menu, select Identity Providers.
From the Security section in the left menu items, click the caret to expand the Identity Providers menu and select Federation Partners.
From the Federation Partners workspace, select SAML 2.0 from the Add Federation Partner selector.
The Community-SAML Relying Parties workspace will launch. If the Federation Partner is listed in the Community, select the relying party from the workspace for auto-configuration. Refer to the Reference Material on the Community for additional information.
The Community contains basic configuration information to automatically register commonly used SAML Relying Parties. Before manually adding a new SAML Relying Party, search the Community for the entry, as the Community will be updated on an ongoing basis with new SAML Relying Parties.
If the Relying Party is not in the list, click Create New SAML Relying Party+.
Enter the Name and optional Description, and paste the Metadata that was obtained from the Service Provider/Federation Partner.
Click SSO Settings to expand the options. If selecting the Enable ECP Settings checkbox, those options will display. Refer to the Reference Material for details on SAML SSO / ECP Settings and Attribute Mapping.
Click Save to add the SAML 2.0 Partner.
From the Federation Partners workspace, select to Edit the entry.
Click Choose an Attribute to DENY or PERMIT.
Click to expand the drop-down of available attributes to deny or permit mapping.
If the attribute is not available in the list, click theThe Add New Attribute window will load. Select the attribute type from the drop-down and click Create.
Based on the type of attribute being added, different menu options will display.
After the attribute has been added, Permit or Deny access the mapping, as in step 12.
Select to Permit or Deny the attribute mapping.
Click Save to add the attribute to the selected Federation Partner.
A confirmation notice will display if updates are successful.
Click to Trigger Service Reload to activate the new attributes for the Federation Partner.
SAML SSO Integration Guide
The overall goal of the SAML SSO Configuration Process is to federate the Customer and Service Provider to provide Customer-environment users a Single Sign-On (SSO) experience to access the Service Provider's web-based service. Users access the web-based service through an Applications icon in the RapidIdentity Portal.
This document focuses on configuring a third party application to be authenticated via SAML to the RapidIdentity Portal as an Identity Provider.
For a general Federation overview, including additional terminology, view the link to the Reference Material. Below are some relevant terms to understand the main entities in SAML SSO.
SAML: Allows Identity Providers (IdP) to pass authorization credentials to Service Providers for SSO. SAML is the link between the authentication of a user’s identity and the authorization to use a service.
RapidIdentity IdP: Performs the authentication that verifies the end-user identity and passes that data to the service provider along with the user’s access rights for the service.
The Customer must perform the following in order to complete the configuration process:
Communicate with the Service Provider to determine proper metadata exchange
Obtain the endpoint URL from the Service Provider to access the service
Determine what attributes to exchange and, if necessary, any attributes to deny
Configure the Service Provider in RapidIdentity.
Each Service Provider is unique and is the ultimate decision maker with respect to how any organization can access their service. Thus, each Service Provider configuration, while it contains the same overall sequence, varies slightly with respect to the specific configuration settings.
Note
If this in an IDaaS (Identity as a Service), deployment, this setup has already been completed. IDaaS is an authentication infrastructure that is built, hosted, and managed by a third-party service provider on a subscription basis. IDaaS solutions are predominately cloud-based and can be single sign-on (SSO).
Use the checklist to reference the quick start steps for Federation Setup.
Create RapidIdentiy as an Identity Provider
Configure a Service Provider
Assign Applications
Note
It is advised to review this documentation in its entirety to understand the configuration requirements before communicating with the Service Provider.
SSO Configuration Process
This is general overview of the process to configure SAML SSO service providers.
The RapidIdentity Federation Identity Provider setup requires access to the RapidIdentity Configuration Module. Users must log in to RapidIdentity as a user with the System Administrator or Tenant Administrator role.
Authenticate to RapidIdentity Portal as an administrator to https://<Portal hostname>.
From the Configuration menu, select Identity Providers from the Security menu.
The Identity Provider Configuration contains information to exchange with the Service Provider. It is necessary to provide the Service Provider with the IdP metadata, however, some Service Providers may require the Base URL, Logout URL, Certificate, or Certificate Fingerprint. Click the link for more details on the RapidIdentity Identity Provider.
The IdP metadata can be provided to the Service Provider using either of two choices:
Click the Metadata link. Copy and save the metadata as an XML file, and send to the remote vendor.
Provide the remote vendor with the Live Metadata URL, which allows the remote vendor to access the metadata at any time.
Important
It is important that the Service Provider provides access to their metadata, which can be obtained from a live URL or an XML file. The attributes that are necessary for SSO to work with their application must be included.
Note
Prior to configuring the Service Provider application in RapidIdentity Portal, the Customer should ask the Service Provider whether authentication to the service is initiated by the Service Provider or the Identity Provider.
Service Provider-Initiated authentication: Users access the Service Provider through a specific Service Provider SAML URL and enter a username or email address to be redirected to the RapidIdentity login page to authenticate. After authentication to RapidIdentity, users are directed to the Service Provider's service that was provided as the SAML URL to initiate the authentication process. This is incorporated into the application definition in the next step.
Identity Provider Initiated authentication: Authentication begins with RapidIdentity and users authenticate based on the authentication policies configured and click the corresponding application icon in RapidIdentity Portal. It is necessary to extract the Service Provider entityID from the Service Provider metadata and the URL for this authentication is included in the application definition in the next step as follows.
IDP-Initiated Authentication URL: https://<Portal hostname or IP address>/idp/profile/SAML2/Unsolicited/SSO?providerId=<entityID from SP metadata>
Additional Attributes
Additonal attributes required by the Service Provider are defined in the Identity Provider to pass static attributes, LDAP atributes, nameID values, and static nameID values. A Service Provider may also request the Identity Provider to send an attribute with a name different than what is in the directory service. For example, the Identity Provider can send the LDAP attribute of mail, but define it with the Email name that the Service Provider requested by adjusting the SAML name and Friendly Name.
Access the SAML SSO Advanced Settings from the Configuration menu and select Federation Partners from the left hand menu items.
If there are Federation Partners that have been configured, they will display in the workspace. Hover in the far right of the row and click the Edit button.
If there are no Federation Partners already configured, click Add Federation Partner and select SAML 2.0 from the drop-down to open the configuration settings.
The Community Federation Partners workspace will load. Refer to the Community section to learn more about that topic.
Click Create SAML Relying Party+ to open the configuration options.
Complete the Name and Description of Federation Partner/ Service Provider.
Paste the metadata for the Service Provider in the Metadata field.
SSO and ECP Advanced Settings
The SSO and ECP Advanced Settings include how attributes, assertions, responses, name IDs, and signature algorithms should be configured. These settings are determined by the Service Provider and this information should be obtained when the Customer communicates with the Service Provider. Refer to the reference material on SAML SSO and ECP Advanced Settings and SAML Attributes for additional details on configuring these attributes.
From the Federation Partners configuration screen, click on SSO Settings.
Note
By default, the ECP Settings are not active. Click Enable ECP Settings to enable ECP Settings.
When selecting the Enable ECP Settings checkbox, the ECP Settings section will become available beneath the SSO Settings along with the configuration options.
From the Federation Partners workspace, click SAML Attributes. All of the attributes that were available will be displayed for each category, LDAP, Static, Name ID, and Static Name ID.
To add an attribute click the tab for the attribute category and click the right-hand button to add the attribute. Refer to the Reference Material for additional information on SAML Attributes.
Select the Federation Partner from the Federation Partners workspace, and click Edit by hovering in the last column.
Assign the Attribute Mapping, as described in the Attribute Mapping section in the topic SAML SSO, ECP Settings and Attribute Mappings .
From the bottom action buttons, clickTrigger Web Reload. After the confirmation appears at the top, Click Trigger Service Reload to allow RapidIdentity to communicate with the service provider once the RapidIdentity Portal application icon is clicked.
Access RapidIdentity Portal to define the application. This application allows users to access the Service Provider's service. Refer to the Reference Material for information toCreate an Application.
Note
After a user authenticates successfully, a SAML Assertion is generated by the IdP. The SAML Assertion contains attributes about the user (e.g. name, email address, etc.) and other information describing how and when authentication occurred at the IdP. The SAML Assertion is then embedded inside of a more consolidated SAML Response and it is the SAML Response containing the Assertion which is ultimately conveyed to the Relying Party.
Test SAML SSO Configuration
If the endpoint SAML configuration exists in RapidIdentity Community, its configuration can be greatly simplified. Refer to the Community reference material.
Ensure the Application Type in the General tab is set to Simple. This setting is required for federated SSO.
Complete the required fields labeled with a red asterisk, set the application to Active, and define any access control lists, to allow user groups matching a specific LDAP filter access to the application. Users can access the newly configured application by refreshing the browser and accessing the Applications module.
Troubleshoot SAML Authentication
Sometimes the SAML SSO configuration process does not work as expected and this instance is usually the result of a miscommunication between two or more parties to identify the exact configuration requirements.The result of a misconfiguration can lead to users and administrators temporarily being unable to authenticate to RapidIdentity.
Note
If it is observed that an existing Service Provider implementation is no longer accessible for any reason, especially if a Service Provider updates access requirements, contact Identity Automation Support to initiate the troubleshooting and updating processes. The Identity Automation Support team can facilitate the SAML SSO integration process, however, the Support team does not serve as an intermediary between the Customer and Service Provider to determine or obtain any necessary configuration information.
Configure Clever SSO SAML Integration
Please first read how to Configure a Service Provider for SAML SSO to understand how to use these application-specific settings.
Include SAML2 Attribute Statement | Checked |
SAML2 SSO Assertion Lifetime | 500000 ms (5 minutes) |
Sign SAML2 SSO Responses | Conditional |
Sign SAML2 SSO Assertions | Never |
Encrypt SAML2 SSO Assertions | Never |
Encrypt SAML2 SSO Name IDs | Never |
Signature Algorithm | SHA-256 |
Skip Endpoint Validation when Signed | Unchecked |
Enable ECP Settings | Unchecked |
LDAP Attribute | SAML Name | Friendly Name | Name Format Friendly Name | Name Format Value |
|---|---|---|---|---|
clever.any.email | clever.any.email | URI Reference |
|
PERMIT Attributes
Name |
|---|
clever.any.email |
DENY Attributes
Name |
|---|
[INTERNAL] SAML Transient ID |
SAML for Clever is fairly straightforward from the Identity Automation Identity Provider.
Clever has posted an article outlining their requirements: https://support.clever.com/hc/s/articles/218050687?language=en_US
As always, there's a metadata/certificate exchange needed so that both ends have the proper encryption/decryption available. Please remove the validUntil entry if present.
Note
Clever requires a Single-Logout URL to be provided in our metadata and metadata supplied via live URL. Since Identity Automation does not support either of these, they added the logout URL entry to our metadata anyway, and hosted the metadata on a separate site. Additionally, since they expect metadata to be exchanged via Live URL, their metadata includes an XML entry validUntil which, as mentioned above, must be manually removed from the metadata prior to import into RapidIdentity Federation.
Clever may accept a static copy of the metadata. If they will accept this, a pair of logout lines can be manually added to the metadata before sending it to them. Those lines would look like this:
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location "https://%ENTER_CUSTOMER_URL_HERE%/idp/logout"/>
And
<SingleLogoutServe Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://%ENTER_CUSTOMER_URL_HERE%/idp./logout"/>
The actual location can be worked out with Clever.
Note
If the customer's IDP is used here, it will log a user out of all IDP-authenticated sessions when they log out of Clever.
Important
Please ensure not to add any extra characters, line spaces, or spaces at any point to the metadata.
Clever Metadata URL: https://clever.com/oauth/saml/metadata.xml