Free trial

Manage users and groups with SAML in DESK Managed

DESK Managed supports integration with SAML 2.0 as an SSO IdP (Single Sign-On Identity Provider) for the management of users and groups. SAML can use either HTTP POST (preferred) or HTTP Redirect bindings. When both are present, HTTP POST is used.

Set up SAML 2.0 integration

This procedure requires configuration in DESK Managed and at your IdP.

In DESK Managed

  1. From the Cluster Management Console menu, select User authentication > Single sign-on settings.

  2. From Select single sign-on technology, select SAML 2.0.

  3. From Select login page, select the login options you want to offer users:

    • Standard + SSO displays the standard DESK login page, where the user has the choice to sign in using a local user account (as configured through User authentication > User accounts) or to select the Log in using SSO link and use SSO authentication.
    • SSO skips the DESK login page, so the user cannot sign in using a local user account, and redirects to the IdP login page for SSO authentication only.

  4. Select Download SP metadata to download (to file sp.xml) the SAML metadata you need to provide to your SP.
    The XML metadata of a SAML 2.0 Service Provider box displays the metadata.

On your Identity Provider server (IdP)

Refer to your IdP documentation for details on these steps.

At your IdP server

  1. Use the sp.xml metadata file you downloaded earlier to configure DESK Managed as a Service Provider (SP).
  2. Download the completed configuration metafile from your IdP server.

In DESK Managed

Back in the DESK Managed Cluster Management Console

  1. Return to the Single sign-on settings page (User authentication > Single sign-on settings) to continue where you left off.
  2. Select the Select file button and upload your IdP configuration metafile to DESK Managed.
    The XML metadata of a SAML 2.0 Identity Provider box displays the metadata.
  3. Under User attributes based on SAML 2.0 response attributes, enter the user attributes.
    • First name attribute
    • Last name attribute
    • Email attribute

Group assignment configuration

Each DESK Managed user must be assigned to at least one user group, with at least one associated monitoring environment. Without such a mapping, the user can't sign in to DESK Managed and will instead receive an error message stating that no environment has been found.

The Assign users to groups based on SAML 2.0 response attribute switch determines how you manage user-group assignments:

  • Manually: Set the switch to the off position if you want to make user-group assignments manually from within DESK Managed. In this case, DESK Managed ignores the list of groups sent in your IdP's authentication response.

  • Automatically: Turn on the toggle and enter the group name in the User group attribute field if you want to handle user-group assignment automatically. In this case, any assignments made within DESK Managed are overwritten by the list of groups sent in your IdP's authentication response, such as

    <Attribute Name="gr">  
    <AttributeValue>Admins</AttributeValue>  
    <AttributeValue>Users</AttributeValue>  
</Attribute>

    which would assign the user to the Admins and Users groups.

    • If the value of the user group attribute in the SAML response contains commas, DESK recognizes it as a comma-separated list of user groups and assigns the user to each group in the list. For example
      <Attribute Name="gr">
        <AttributeValue>Admins,Users</AttributeValue>
</Attribute>
      would assign the user to the Admins and Users groups.
    • Make sure group names exactly match existing DESK user group names (case-sensitive, no extra spaces). For example, Admins and admins would be two different groups.

SAML signing certificate update

To submit a new SAML signing certificate, make a PUT request through the Cluster Management API.

  1. In Cluster Management Console, get a ServiceProviderAPI token.

  2. Open the User menu User menu in the top-right corner of the window and select Cluster Management API.

  3. Submit the token.

  4. Expand the SSO configuration section and select PUT.

  5. Select Try it out.
    The Description section displays the format expected for the body of the PUT request.

    {
  "privateKeyEncoded": "string",  
  "publicKeyCertificateEncoded": "string"
}

  6. Paste the contents of the RSA private key and certificate to replace the corresponding privateKeyEncoded and publicKeyCertificateEncoded value placeholders (string). Be sure to include the full BEGIN and END tags of each. In this example, the key and certificate are truncated for brevity:

    {  
  "privateKeyEncoded": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAp8RXe0PIuDwj1ZbYrShXRxjiFnq8xmLWZlWIYkScX/1KC69M\n...\nPM3kel4na+AGibenqRs7PA6rqFeXDg193pepzWqvqmJ98W8YYecZ\n-----END RSA PRIVATE KEY-----",  
  "publicKeyCertificateEncoded": "-----BEGIN CERTIFICATE-----\nMIICzTCCAbWgAwIBAgIRAIpaHcbUOpvhKf6exsxJjVowDQYJKoZIhvcNAQELBQAw\n...\nuw==\n-----END CERTIFICATE-----"  
}

  7. Select Execute to submit the request.

ADFS configuration

If you choose to integrate DESK Managed with Active Directory Federation Services (ADFS), perform the following steps on the ADFS side and then in DESK Managed.

Configuration on the ADFS side

Use the Add Relying Party Trust Wizard to add a new relying party trust using DESK SP metadata configuration.

On the Advanced tab, set Secure hash algorithm to SHA-1.

Add a claim issuance policy to the added relying party trust.

Define a rule to send LDAP attributes as claims.

Define rules to transform LDAP attributes to Name ID (create a rule appropriate to your needs).

Configuration on the DESK Managed side

On the DESK Managed Single sign-on settings page, set the User group attribute appropriately.