SAML SSO for DEX
    • Dark
      Light
    • PDF

    SAML SSO for DEX

    • Dark
      Light
    • PDF

    Article Summary

    Note

    To sign in with SAML, make sure that Sign-In with SAML SSO is enabled as a login method in your organization.

    This article describes how to enable SAML SSO authentication in DEX (app.controlup.com).

    While using DEX, you sign in with two different accounts.

    • Your DEX account. This is the first account you sign in with when you go to app.controlup.com. You use this account to access Edge DX and Scoutbees.
    • Your VDI & DaaS account. After signing in to app.controlup.com with your DEX account, you can sign in to your VDI & DaaS environment using your Active Directory-linked account that is managed in the ControlUp Real-Time DX Console.

    You can use SAML for both accounts. Note that you can use SAML for your VDI & DaaS account only if you also use SAML for your DEX account. If you don't use SAML for your DEX account, then you must use LDAP to sign in to VDI & DaaS.

    If you upgraded from Solve
    If you previously accessed your organization from solve.controlup.com and upgraded to app.controlup.com, you must enable either LDAP or SAML in Solve to use SAML in DEX. 

    Sign in to DEX with SAML

    After you have configured SAML, you can sign in to your organization using SAML by either:

    • Using your ControlUp SAML URL. Visit this URL to directly sign in using SAML SSO.
    • Using the With SAML login method on your organization login page.

    IdP-initiated SSO

    You can sign in to your Identity Provider's page and then select the ControlUp application to sign into ControlUp with SSO. Note that to use IdP-initiated SSO, you must add the attribute orgurl to your SAML assertion. Read Configure User Attributes in Your IdP for more details.

    Use SSO for multiple ControlUp organizations

    You can use SSO for multiple ControlUp organizations using the same IdP tenant, you must set a unique identifier for each organization. To do this, add a unique string to the end of the Relying Party Trust Identifier field in the DEX SAML settings page for each organization. 

    Automatic DEX User Account Provisioning

    ControlUp automatically provisions a DEX user account for any new user who signs in with SAML. In your DEX SAML settings, you can set the Default Role assigned to provisioned user accounts. Note that you can also assign roles based on user groups in your IdP. If you don't want to allow users to sign in and automatically create their DEX user accounts, you can restrict access to ControlUp in your IdP settings. Learn more about users and permissions.

    Automatic VDI & DaaS User Account Provisioning

    If you use ControlUp for VDI & DaaS, ControlUp can automatically provision a VDI & DaaS user account when a new user signs in with SAML. The VDI & DaaS user account is provisioned only if the sAMAccountName and distinguishedName attributes are configured in your IdP. If you don't include those attributes, users must first create their account by registering in the Real-Time Console, or be added using a script.

    The automatically provisioned VDI & DaaS user account does not necessarily have permission to access your VDI & DaaS environment, unless the user already belongs to an Active Directory group that has been given permission in your Security Policy. After the user account has been provisioned, a ControlUp admin can give the user permission to Use Solve or Manage Solve in the Security Policy.

    Assign user roles to IdP groups

    You can assign roles to users based on SSO groups in your IdP. For example, let's say that your level 1 help desk employees are in the SSO group "Level 1 Help Desk". You can create a role for level 1 help desk employees and assign that user role to the "Level 1 Help Desk" SSO group. All users in the "Level 1 Help Desk" group are automatically assigned that user role when they sign in. 

    Roles are assigned based only on SSO groups that are sent in the SAML assertion and added to your SSO Groups settings. If multiple groups are sent in the SAML assertion, then the user is assigned all relevant roles for all groups.

    ControlUp checks a user's SSO groups and assigns the relevant roles each time a user signs in. This means that if you change a user's groups in your IdP, then the user's roles and permissions are automatically updated the next time they sign in.

    Note that it is possible for a user to have roles assigned other than the roles assigned to their SSO groups. This can happen if you manually assign roles to a user, or if a new user signs in for the first time and is assigned the default role for automatically provisioned accounts (the default role is configured in your SAML settings). 

    To assign a user role to an IdP group:

    1. Configure your IdP to send either the names or the IDs of the SSO groups in the attribute userGroups.  We recommend that you send the ID because it is guaranteed to uniquely identify the group.
    2. In ControlUp, go to Global Settings > SAML Single Sign On > SSO Groups.
    3. Click Create SSO Group.
    4. In the Group Name/ID field, enter either the group name or ID, depending on which one you configured your IdP to send in the userGroups attribute. The value you enter in this field must exactly match what your IdP sends in SAML assertion.
    5. In the Display Name field, enter a name for the group. This is the name that appears when assigning roles to the group. 
    6. Click Save.
    7. In your Roles settings, select a role and go to Groups > Add/Remove Groups to add the group to the role.
    8. Save the changes to the user role.

    Use Case Examples

    If your IdP is listed, follow the instructions under your IdP. If not, follow the steps below to set up SAML with any IdP.

    3rd party Identity Provider applications
    We have provided these use case examples for your benefit but do not take responsibility for the screenshots, content, and functionality of these 3rd party applications.

    Azure Active Directory

    Prerequisites:

    • Must have an Azure Enterprise account.
    • Azure Active Directory (AD) must be configured.
    • Must have the necessary permissions to create the application.

    Setup in Azure AD

    1. In Azure AD, go to Enterprise Applications > New application.
    2. Select Create your own application.
    3. Enter a name for the application, select Integrate any other application you don't find in the gallery, and click Create.
    4. After your application is created, click Set up single sign on.
    5. Select SAML as the single sign on method.
    6. In section 1 -Basic SAML Configuration, click Edit and copy the following values from the ControlUp SAML settings page. Note that the Assertion Logout URL is optional and required only if you are using single logout.
    7. If you use ControlUp for VDI & DaaS, then you must edit section 2 - Attributes & Claims to add the sAMAccountName and distinguishedName attributes. After making the changes, your Attributes & Claims section should look like this:
    8. Optionally, if you want to use IdP-initiated SSO or assign roles to ControlUp users based on IdP user groups, you must set up additional attributes in section 2 - Attributes & Claims. See the attribute table below for details.
    9. In section 3 -SAML Certificates, download the Certificate (Base64) and upload it in the IdP Signing Certificate field on your DEX SAML settings page. Note that Azure AD must be configured to sign the SAML assertion.
    10. In section 4 - Set up (your application name), copy the following values from Azure AD and paste them in the DEX SAML settings page.
    11. In the DEX SAML settings page, set the Default Role for DEX user accounts automatically provisioned when a new user signs in with SAML.
    12. Click Apply to save all your changes on the DEX SAML settings page.

    OKTA

    Prerequisite for VDI & DaaS

    Note
    This section is required only if you are using SAML to sign in to your VDI & DaaS environment.

    If you are using SAML to sign in to your VDI & DaaS environment, then you must configure Okta to send the required attributes from Active Directory. Not all of these attributes are added to your Okta user profiles by default when you setup the Active Directory integration with Okta.  

    If the required attributes are not already in your Okta user profiles, then you need to map the Active Directory attributes to your Okta user profiles.

    To map the required Active Directory attributes to your Okta user profile:

    1.  In Okta, go to Profile Editor and select the Okta User (default) user profile. SAML-Okta-Prereq-1
    2. Click Add Attribute.SAML-Okta-Prereq-2
    3. Add three new attributes:
      1. Display name = "Distinguished Name", Variable name = "dn".
      2. Display name = "SAM Account Name", Variable name = "samAccountName".
      3. Display name = "User Principal Name", Variable name = "userName". SAML-Okta-Prereq-4
    4. After saving the attributes, go back to your profiles and select your Active Directory.SAML-Okta-Prereq-5
    5. Click Mappings.SAML-Okta-Prereq-6
    6. Map the following Active Directory attributes to the new Okta user profile attributes you just created, and click Save Mappings.SAML-Okta-Prereq-7

    Set up the SAML Application in Okta

    1. Sign in to the Okta admin dashboard with a user who has the Create App Integration and go to Applications.SAML-Okta-1
    2. Click Create App Integration.SAML-Okta-2
    3. Select SAML 2.0 as the sign-in method and click Next.SAML-Okta-3
    4. Enter an App name of your choosing and click Next.SAML-Okta-4
    5. Under SAML Settings, fill out the following fields using values from your DEX SAML settings page.
      1. In the Single sign-on URL field, enter the Endpoint/Assertion Login URL from DEX.
      2. In the Audience URI field, enter the Relying Party Trust Identifier from DEX.SAML-Okta-5
    6. Optionally, if you want to use single logout:
      1. Click Show Advanced Settings.
      2. Download the Signing Certificate from DEX SAML settings and upload it into the Signature Certificate field in Okta.
      3. In the Single Logout URL field, enter the Assertion Logout URL from DEX.
      4. In the SP Issuer field in Okta, enter the Relying Party Trust Identifier from DEX.
    7. In the Map attributes, add the attributes depending on whether you are using SAML to sign in to your VDI & DaaS environment. 
      • If you are using SAML to sign in to your VDI & DaaS environment, add the following attributes. Note that the UPN, sAMAccountName, and distinguishedName attributes are based on the attribute mappings described in the prerequisite section above. Ensure that the Values in the attribute statements refer to the correct attributes in your Okta user profiles.SAML-Okta-VDIAttributes
      • If you are not using SAML to sign in to your VDI & DaaS enviornment, add the following attributes.SAML-Okta-DEXonlyAttributes
    8. Optionally, if you want to use IdP-initiated SSO or assign roles to ControlUp users based on IdP user groups, you must set up additional attributes. See the attribute table below for details.
    9. At the bottom of the page, click Next.SAML-Okta-7
    10. Select I'm an Okta customer adding an internal app and click Finish.SAML-Okta-8
    11. Under the Sign On tab, click View SAML setup instructions.SAML-Okta-9
    12. This page shows three values that you must copy or download and add to your DEX SAML settings page.SAML-Okta-10
      1. Copy the value Identity Provider Single Sign-On URL and paste it into the field IdP Login URL in DEX.
      2. Copy the value Identity Provider Issuer and paste it into the field Entity/Issuer ID in DEX.
      3. Click Download certificate and upload the certificate under the field IdP Signing Certificate in DEX. Note that Okta must be configured to sign the SAML assertion.

    After performing the steps above, you can now sign in to ControlUp with SAML using the SAML URL. You can find the SAML URL at the top of your DEX SAML settings page

    Troubleshooting

    If SAML isn't working correctly after following the procedure above, it's possible that the SAML assertion isn't sending the correct information. To preview the SAML assertion, edit the application and go back to the page where you added the attribute statement, and click Preview the SAML Assertion. Note that your Okta user must be assigned to the application to preview the assertion.SAML-Okta-troubleshooting

    Compare the generated SAML assertion against the attribute table above and make sure that:

    • The Attribute Name of each attribute is written exactly as it appears in the attribute table.
    • The AttributeValue of each attribute contains the correct information about the user.

    DUO

    Prerequisites:

    • You have a DUO account with the necessary permissions to Protect an Application.

    Set up the SAML application in DUO

    1. Go to Applications > Protect an application.
    2. Search for Generic SAML Service Provider and click Protect.
    3. Under the Metadatasection, copy the following values and paste them into the fields in the DEX SAML settings page:
      1. Copy the Entity ID and paste it into the Entity/Issuer ID field in DEX.
      2. Copy the Single Sign-On URL and paste it into the IdP Login URL field in DEX.
      3. Copy the Single Log-Out URL and paste it into the IdP Logout URL field in DEX.
    4. Under the Downloads section, click Download certificate and upload the certificate into the IdP Signing Certificate field in DEX. Note that DUO must be configured to sign the SAML assertion.
    5. Copy the following values from the DEX SAML settings page and paste them into the fields in DUO under the Service Provider section:
      1. Copy the Relying Party Trust Identifier from DEX and paste it into the Entity ID field in DUO.
      2. Copy the Endpoint/Assertion Login URL from DEX and paste it into the Assertion Consumer Service (ACS) URL field in DUO.
      3. Copy the Assertion Logout URL from DEX and paste it into the Single Logout URL field in DUO.
    6. Under the SAML Response section:
      1. Set the NameID format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
      2. In the NameID attribute field, enter UserPrincipalName.
    7. In the Map attributes, add the attributes depending on whether you are using SAML to sign in to your VDI & DaaS environment. 
      • If you are using SAML to sign in to your VDI & DaaS environment, add the following attributes:
      • If you are not using SAML to sign in to your VDI & DaaS environment, add the following attributes. Note that the image below assumes that you are using Active Directory as your authentication source in DUO. If you are using a different authentication source, enter the correct attribute name from your authentication source in the IdP Attribute fields.DUO-DexAttributes
    8. Optionally, if you want to use IdP-initiated SSO or assign roles to ControlUp users based on IdP user groups, you must set up additional attributes. See the attribute table below for details.
    9. In the DEX SAML settings page, set the Default Role for DEX user accounts automatically provisioned when a new user signs in with SAML.
    10. Scroll to the bottom of the page and click Save.

    After performing the steps above, you can now sign in to ControlUp with SAML using the SAML URL. You can find the SAML URL at the top of your DEX SAML settings page.

    Configure SAML SSO with DEX and Your IdP

    This section describes how to set up SAML SSO with DEX with any IdP. ControlUp requires that the SAML assertion is signed and contains the correct user attributes. Check your IdP's documentation for specific instructions on how to add a SAML service provider.

    To open DEX SAML settings, go to Global Settings > SAML Single Sign On.

    Step 1 - Configure DEX Settings

    This table lists fields that you need to fill out in your DEX SAML settings.

    Field in DEX SAML settingsRequiredNotes
    IdP Login URLYesCopy the login URL from your IdP and paste it here.
    Your IdP might call this:
    • Login URL
    • Single sign on URL
    IdP Logout URLNoif you want to use single log out (SLO), copy the logout URL from your IdP and paste it here. SLO is not supported on all IdPs.
    Your IdP might call this:
    • Logout URL
    • Single log out URL
    IdP Signing CertificateYesDownload the X.509 signing certificate from your IdP and upload it here.

    Note: You must ensure that your IdP uses the certificate to sign the SAML assertion.
    Entity/Issuer IDYesCopy the entity/issuer ID from your IdP and paste it here.
    Your IdP might call this:
    • Entity ID
    • Issuer ID
    • Issuer URL
    • Azure AD Identifier
    Default RoleYesSet the default role assigned to DEX user account automatically provisioned when a new user signs in with SAML. You can select from the default roles or a custom role.

    For added security, we recommend that you set the default role to one with limited permissions, such as Viewer. Learn more about users and permissions.


    Step 2 - Configure IdP Settings

    This table lists the fields that are already filled out in your DEX SAML settings. You need to take the information from these fields and add it in your IdP.

    Field in DEX SAML settingsRequiredNotes
    Relying Party Trust IdentifierYesCopy this value from DEX SAML settings and paste it into your IdP.
    Your IdP might call this:
    • Identifier
    • Entity ID
    • Relying Party Identifier
    • Audience URI

    If you want to sign in with SAML to multiple ControlUp organizations using the same IdP tenant, edit this value to make it unique for each organization.

    Endpoint Assertion/Login URLYesCopy this value from DEX SAML settings and paste it into your IdP.
    Your IdP might call this:
    • Reply URL
    • Assertion Consumer Service (ACS) URL
    • Trusted URL
    • Single sign on URL
    Assertion Logout URL
    NoIf you want to use single logout (SLO), copy this value from DEX SAML settings and paste it into your IdP.
    Signing CertificateIf it is required by your IdPIf your IdP requires it, download the X.509 certificate from ControlUp and upload it to your IdP.

    Azure AD, Okta, and DUO for example, do not require that you upload this certificate.


    Step 3 - Configure User Attributes in Your IdP

    Configure your IdP to send the following attributes:

    Attribute NameRequiredNotes
    emailaddress OR
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    YesThe user's email address. Used to identify the user's DEX account.
    givenname OR
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    YesThe user's first name.
    surname OR
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    YesThe user's last name.
    upn OR
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn OR http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    YesThe user's UPN. Used to identify the user's VDI & DaaS account. This is required to sign in to your VDI & DaaS environment. If you don't use ControlUp for VDI & DaaS, then this attribute isn't required.
    sAMAccountNameNoThe user's sAMAccountName. Required for Automatic VDI & DaaS user account provisioning.
    distinguishedNameNoThe user's distinguished name. Required for Automatic VDI & DaaS user account provisioning.
    orgurlNoThe name of your ControlUp organization. This is required to use IdP-initiated SSO. For example, if you access your ControlUp from app.controlup.com/acmeorg, configure this attribute to send "acmeorg".
    userGroupsNoThe names or IDs of IdP user groups. Used for assigning roles to ControlUp users based on IdP groups
    email
    No
    The ID of the user's ControlUp account (in the format something@example.xyz).

    You can use this attribute to sign in with a user that doesn't have an email address. For details, visit How to Sign in With a SAML User That Doesn't Have an Email Address.



    Was this article helpful?