SAML 2.0 (Security Assertion Markup Language) is an XML-based protocol used for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). Yeeflow supports SAML 2.0 as a custom login method, enabling organizations to leverage their existing SAML-based identity providers for user authentication.
Configure SAML 2.0
To configure SAML 2.0 as the custom login method in Yeeflow, system administrators need to access the Yeeflow admin center. From the Login authentication page, click "Add custom login method" button at the bottom of the custom login method section". Then click "SAML 2.0" from the drop-down list:
From the pop-up window, follow the provided documentation or guidance to set up the SAML 2.0 integration.
When configuring SAML 2.0 Single Sign-On (SSO) for Yeeflow, you need to provide several properties to establish the connection between Yeeflow and your SAML 2.0 identity provider (IdP). The specific properties may vary depending on your IdP, but here are the common ones you'll typically need to provide:
1. Metadata URL (Service Provider): The service provider (SP) refers to the application or system that users are trying to access. In this case, Yeeflow acts as the service provider, as it is the system that users will be logging into using their credentials from an identity provider (IdP). You can find the Identity Provider Metadata with the link provided on this configuration page. You can copy this link, and use it when configure the IdP.
The service provider (Yeeflow) relies on the identity provider (IdP) for user authentication and attribute assertions. When a user attempts to log in to Yeeflow, the SP initiates the SAML SSO process by redirecting the user to the IdP for authentication. The IdP then verifies the user's identity and generates a SAML assertion, which contains information such as the user's identity attributes and authentication status.
Once the IdP has generated the SAML assertion, it is sent back to the service provider (Yeeflow) through the user's browser. The SP validates the assertion's digital signature using the IdP's public key certificate, ensuring its authenticity. If the SAML assertion is valid, the SP considers the user authenticated and allows them access to the requested resources within Yeeflow.
2. Name: Input a unique display name for this SAML login method. This text will be display on the login page of your organization.
3. Metadata URL (Identity Provider): This is an XML file that contains the metadata of your SAML 2.0 IdP. It includes information such as the IdP's entity ID, endpoints (e.g., Single Sign-On URL and Single Logout URL), and public key certificates. Yeeflow will require you to provide the URL where it can be fetched.
4. Issuer: The "Issuer" refers to the entity that issues or provides the SAML assertion. It is an important element within SAML assertions and is used to uniquely identify the party generating the assertion. Typically, you may input "Yeeflow" here. You can also refer to the IDP configuration.
5. Signature Algorithm: Refers to the cryptographic algorithm used to generate and verify digital signatures within SAML assertions and other SAML-related elements.
Digital signatures are crucial in SAML to ensure the integrity, authenticity, and non-repudiation of the exchanged information. The signature algorithm determines the mathematical operations used to create and verify the digital signature.
When configuring SAML, the Signature Algorithm setting allows you to specify the algorithm that will be used to generate the digital signatures for SAML assertions or other SAML elements. Commonly used signature algorithms in SAML include:
RSA-SHA256: This algorithm uses the RSA encryption algorithm with the SHA-256 hash function. It offers stronger security compared to RSA-SHA1 and is widely used in modern SAML implementations.
RSA-SHA384: combines the RSA encryption algorithm with the SHA-384 (Secure Hash Algorithm 384) hash function. RSA-SHA384 provides a higher level of security compared to RSA-SHA256.
RSA-SHA512: Similar to RSA-SHA256, this algorithm employs the RSA encryption algorithm but with the SHA-512 hash function. It provides even stronger security than RSA-SHA256, but it may have increased computational overhead.
6. Certificate validation mode: Refers to the method used to validate the digital certificates presented during the SAML (Security Assertion Markup Language) authentication process. There are several options you can choice from the drop-down list. Here's an explanation of the different options:
None: With the "None" option, no certificate validation is performed. This means that the SAML service or software does not verify the authenticity or trustworthiness of the certificates presented by the identity provider (IdP) or service provider (SP). This option should only be used in development or testing environments, as it leaves the system vulnerable to potential security risks.
PeerTrust: In the "PeerTrust" mode, the SAML service or software validates the digital certificate presented by the peer (IdP or SP) based on its trust in the certificate alone. It verifies that the presented certificate is correctly formatted and has a valid chain of trust up to a trusted root certificate authority (CA). However, it does not perform additional checks such as certificate revocation or hostname matching.
ChainTrust: With the "ChainTrust" mode, the SAML service or software not only validates the peer's certificate but also verifies the entire certificate chain up to a trusted root CA. This mode ensures that all intermediate certificates in the chain are valid and properly signed by trusted authorities. It provides a higher level of certificate validation than PeerTrust.
PeerOrChainTrust: This mode combines the validation methods of both PeerTrust and ChainTrust. It first attempts to validate the peer's certificate using PeerTrust, and if that fails, it falls back to ChainTrust. This mode offers flexibility in certificate validation by allowing the system to accept valid certificates even if the chain of trust is incomplete or unknown.
Custom: The "Custom" option allows for a customized certificate validation process. With this mode, you can define and implement your own validation logic using custom code or external libraries. It provides the most flexibility but also requires advanced knowledge of certificate validation and programming.
7. Revocation Mode: Refers to the method used to check the revocation status of digital certificates during the SAML (Security Assertion Markup Language) authentication process. Revocation checking is important to ensure that a certificate has not been revoked or compromised before accepting it as valid. Yeeflow provides different options for revocation mode, each with its own implications. Here are the available options and their differences:
NoCheck: With the "NoCheck" option, no revocation checking is performed. This means that Yeeflow does not verify whether the presented certificates have been revoked or are still valid. Choosing this option can lead to potential security risks since revoked or compromised certificates may still be accepted.
Online: The "Online" mode enables real-time revocation checking. Yeeflow will attempt to connect to the certificate authority (CA) or the Online Certificate Status Protocol (OCSP) responder to verify the revocation status of the presented certificates. This mode ensures that only non-revoked certificates are accepted. However, it requires an active internet connection and relies on the availability and responsiveness of the CA or OCSP responder.
Offline: In the "Offline" mode, Yeeflow performs revocation checking using a locally stored Certificate Revocation List (CRL). A CRL is a file issued by the CA that contains a list of revoked certificates. Yeeflow will compare the presented certificates against the entries in the CRL to determine their revocation status. This mode does not require an active internet connection, but it relies on regularly updating the local CRL to ensure the latest revocation status information.
When configuring Yeeflow SAML integration, you can extract user information such as name and email from the identity token provided by the Identity Provider (IdP). These properties are typically included as claims in the SAML assertion and can be utilized within Yeeflow for user identification and personalization. Here's an overview of these properties and how to work with them:
8. Property:Name: The name property represents the user's full name or display name. It provides a human-readable identifier for the user. The value of the name property can be extracted from the identity token's claims. Depending on the IdP configuration, the name property may be represented by different claim names such as "name," "displayName," or "fullName."
To retrieve the name property in Yeeflow, you need to map the appropriate claim from the identity token to the corresponding user attribute or field in the Yeeflow user profile. This mapping is typically done during the SAML configuration process in Yeeflow's admin center. By mapping the name claim, Yeeflow can populate the user's name attribute with the retrieved value, enabling personalized display and identification within the system.
9. Property:Email: The email property represents the user's email address. It serves as a unique identifier and is commonly used for user communication and identification purposes. Similar to the name property, the email property can be extracted from the identity token's claims.
To retrieve the email property in Yeeflow, you need to map the appropriate claim from the identity token to the corresponding user attribute or field in the Yeeflow user profile. This mapping ensures that the user's email address is captured and associated with their Yeeflow account. This allows for seamless communication, user-specific notifications, and enables features such as sharing and collaboration based on email addresses.
10. Certificate (*.crt): Refers to the public key certificate that is used to establish trust between the Identity Provider (IdP) and Yeeflow. This certificate is typically provided by the IdP and is used to encrypt and verify digital signatures during the SAML authentication process.
To obtain the content of the certificate (*.crt file) required for Yeeflow SAML configuration, you can follow these general steps:
Contact your Identity Provider: Reach out to the administrator or support team of your Identity Provider (the service you are integrating with Yeeflow for SAML authentication). Request the public key certificate for SAML integration.
Obtain the Certificate: The IdP will usually provide the certificate in the form of a file with a ".crt" extension. This file contains the public key and other relevant information. They may provide it as a file attachment, a download link, or they may share the content of the certificate directly with you.
Retrieve the Certificate Content: Once you have the certificate file (*.crt), you can open it using a text editor or a certificate management tool. The certificate file contains encoded data, including the public key and other certificate details. Copy the entire content of the certificate file, including the "BEGIN CERTIFICATE" and "END CERTIFICATE" lines.
Paste the Certificate Content: In the Yeeflow SAML configuration page, locate the text area where the certificate information is required. Paste the content of the certificate file into the text area. Ensure that you include the entire certificate content, including any line breaks or additional information provided.
11. Private key (*.pem): This is an optional field that can be used to enhance the SAML (Security Assertion Markup Language) Single Sign-On (SSO) experience. While not mandatory for authentication purposes, the private key plays a crucial role in implementing advanced features such as single logout.
The private key, typically stored in a PEM file format, is used in conjunction with the public key to enable secure communication between Yeeflow (the service provider) and the identity provider (IdP) during the SAML authentication process. It ensures the authenticity and integrity of the SAML responses exchanged between the two entities.
While the private key is not required for the initial SAML authentication, it becomes relevant when implementing single logout functionality. Single logout allows users to log out of multiple applications simultaneously. By utilizing the private key, Yeeflow can sign and send logout requests to the IdP, initiating the logout process across all associated applications.
Including the "Private key (*.pem)" empowers Yeeflow administrators to implement enhanced security features and provide a seamless single logout experience to their users. However, it is important to note that if single logout is not a requirement, the private key field can be left empty without affecting the primary SAML authentication functionality.
Enable the SAML Login Method:
After successfully saving the SAML configuration, find theSAML method in the "Custom Login Method" section and enable it by clicking the enable button from the more operation menu list.
