ADFS (SAML)

Prerequisites

• Review SAML (SaaS).

• Ensure you have a working, internet-accessible ADFS server. Interoperability testing has been performed specifically with ADFS on Windows Server 2012 R2.

For Service-Provider-Initiated Login Flow

Follow the instructions below to configure ADFS with the ADFS Management tool in the Windows Server Manager.

1. Right-click Service > Edit Federation Service Properties.

Note the hostname in the Federation Service Identifier, as this will be used in the metadata URL that you paste in the Metadata entry on the SAML Configuration page in the Sysdig authentication settings. Specifically, the metadata URL will be of the format https://HOSTNAME/FederationMetadata/2007-06/FederationMetadata.xml. Also, so that the Sysdig platform can access this URL directly, this host must resolve in DNS and have a valid (not self-signed) SSL/TLS certificate.

<img src="/image/373576210.png" width="649" />

<img src="/image/373576203.png" width="350" />

2. Add a Relying Party Trust configuration for the Sysdig application.

   1. Right-click Relying Party Trusts > Add Relying Party Trust and click Start to begin the wizard.

      

   2. In the Select Data Source option, click the Enter data about the relying party manually button, then click Next.

      

   3. Enter a Display name of your choice, then click Next.

      

   4. Click Next to accept the default option to use ADFS profile.

      

   5. Click Next to skip the selection of an optional token encryption certificate (Sysdig does not support this option).

      

   6. Select Enable support for the SAML 2.0 Web SSO protocol, then enter one of the following values for Relying party SAML 2.0 SSO service URL:

      If configuring Sysdig Monitor, enter: https://app.sysdigcloud.com/api/saml/auth

      If configuring Sysdig Secure, enter: https://secure.sysdig.com/api/saml/secureAuth

      Then click Next.

      

   7. For the Relying party trust identifier, enter one of the following values:

      If configuring Sysdig Monitor, enter: https://app.sysdigcloud.com

      If configuring Sysdig Secure, enter: https://secure.sysdig.com

      Then click Add > Next.

      

   8. Click Next to skip the configuration of multi-factor authentication.

      

   9. Choose a policy for whether users will be permitted to log in to the Sysdig application. The default to Permit all users to access the relying party will typically be acceptable. Click Next.

      

   10. Review the summary and click Next to complete the configuration of the Relying Party Trust.

       

   11. The next step will involve adding Claim Rules, so you can leave the box checked to Open the Edit Claim Rules dialog and click the Close button to be brought immediately into the Claim Rules editor.

       

3. Ensure that the SamlResponseSignature option matches the Sysdig authentication configuration.

   1. Use the Set-AdfsRelyingPartyTrust/Get-AdfsRelyingPartyTrust cmdlets via PowerShell to configure SamlResponseSignature.

      -SamlResponseSignature
      Specifies the response signatures that the relying party expects. The acceptable values for this parameter are:
      
      AssertionOnly
      MessageAndAssertion
      MessageOnly
      

      For more information, see Set-AdfsRelyingPartyTrust.

   2. Navigate to Settings > Authentication on the Sysdig app and check the Sysdig authentication setting maps to the SamlResponseSignature :

      

      For MessageAndAssertion, enable both options.

4. Next, use the Claim Rules to ensure that login data is sent as needed to the Sysdig platform. A user’s login to the Sysdig platform is based on an email address, and a default ADFS configuration would not send the email address as required. The following configuration ensures the correct field from Active Directory is delivered in the claim.

   1. If you’re not already in the Claim Rules editor from the previous step, navigate to it by right-clicking on the Relying Party Trust that was just created, and selecting Edit Claim Rules.

      

   2. Click Add Rule. On the following screen, accept the default rule template to Send LDAP Attributes as Claims and click Next.

      

   3. Enter a name for the rule, select Active Directory as the Attribute store, then use the pull-down selectors to pick E-Mail as both the LDAP Attribute and Outgoing Claim Type, then similarly make pull-down selections for Given Name and Surname. Once these selections are made, click Finish.

      

   4. Now click Add Rule again, this time selecting the template for Transform an incoming claim.

      

   5. Enter a name for the rule, then use the pull-downs to select an Incoming claim type of E-Mail, an Outgoing claim type of Name ID, and an Outgoing name ID format of Email. Click Finish.

      

   6. (Optional) If you want the user’s First Name and Last Name to be included in the records created in the Sysdig platform database when new users successfully login via SAML for the first time, additional Transform rules must also be created. Only the email-based username is strictly required and we already created a rule for this, so this step is optional.

      If you wish to do this, click Add Rule and once again select the template for Transform an incoming claim. Enter a name for the rule, then use the pull-down to select an Incoming claim type of Given Name, and for the Outgoing claim type, directly type the first name into the field. After clicking Finish, click Add Rule and create a similar rule to transform the Incoming claim type of Surname to the Outgoing claim type of last name.

      

   7. Having clicked Finish after creating your last rule, you will see all rules now in the editor. Click OK, and your ADFS configuration for your Sysdig application is complete.

      

For IdP-Initiated Login Flow (Optional)

If you prefer an IdP-initiated SAML configuration, follow the instructions given below.

1. On your ADFS host, edit %systemroot%\ADFS\Microsoft.IdentityServer.Servicehost.exe.config and add <useRelayStateForIdpInitiatedSignOn enabled="true" /> to the <microsoft.identityserver.web> section. Once the modification is saved, restart ADFS services for the change to take effect.

   The Sysdig platform requires a specific setting of RelayState in order to accept IdP-initiated login flows. On the ADFS versions tested, the use of RelayState is disabled by default, and a Microsoft article describes the topic in detail. See a Microsoft forum thread for information on how to enable it.

2. Retrieve your Sysdig customer number.

   See Find Your Customer Number for more information.

3. Generate an IdP-initiated login URL.

   In addition to having the correct settings, it must be properly URL encoded. To ease this configuration, use this ADFS RelayState Generator tool. When launched, enter the values below, then hit the Generate URL button.

   • For the IDP URL String, enter https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx

   • For the Relying Party Identifier, enter one of the following values:

     • If configuring Sysdig Monitor, enter https://app.sysdigcloud.com

     • If configuring Sysdig Secure, enter https://secure.sysdig.com

     For other regions, the format is https://.app.sysdig.com. Replace <region> with the region where your Sysidig application is hosted. For example, for Sysdig Monitor in the EU, you use https://eu1.app.sysdig.com/. See SaaS Regions and IP Ranges for more information.

   • For the Relay State/Target App, enter #/&customer=CUSTOMER-ID-NUMBER, substituting the CUSTOMER-ID-NUMBER you retrieved in the previous step

     

This Results URL will be used in the metadata URL that you paste in the Metadata entry in the [SAML connection settings](/en/docs/administration/administration-settings/authentication-and-authorization-saas/saml-saas/#saml-saas).

4. Use the Results URL from the tool to test your IdP-initiated login.

   Note that per this Microsoft forum thread, it is apparently not possible to configure ADFS to use such a URL when your users select the application from the pull-down menu at https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx. However, you may embed the URL into a custom portal or bookmarks list.

5. Now you can test login using an Active Directory user that has an Email address configured.

   

Test Metadata (Optional)

To ensure the metadata URL you copy at the end of the IDP configuration procedure is correct, you can test it by directly accessing it via your browser.

When accessing the URL, your browser should immediately download an XML file that begins similarly to the example shown below. No entry of credentials or other security measures should be required to successfully download it. If this is not the case, revisit the IdP configuration steps.