Let the platform do the work
SugarClubContact+1 (877) 842-7276

Configuring SSO With Okta Using SAML

Overview

Sugar and SugarIdentity allows single sign-on authentication using Okta and SAML so that it can be integrated with a connected system using a single user ID and password. This article walks through configuring Okta to allow external authentication using SAML 2.0.

If you are using SugarLive in Sugar Serve, you can also set up SSO in SugarLive using SAML 2.0. To do so, you will also need to configure Okta as an identity provider for Amazon Web Services (AWS). Refer to this article on Okta's website for details on this setup.

For more information about external authentication methods, refer to the following pages:

Prerequisites

  • Your organization must have an active Okta account. For information on setting up an Okta account for your organization, please refer to their website at https://www.okta.com/.
  • Your Sugar or SugarIdentity users should be users in your organization's Okta account.
  • You must have access to an Okta administrator account in order to complete the steps in this article. For more information regarding the administrator role, please refer to this Administrators documentation on Okta's website.
  • You must be familiar with Okta and how to set up the SSO configurations that meet your organization's needs. 
  • You must be a Sugar administrator to configure the SAML settings for your instance. For instances that do not use SugarIdentity, SAML is configured in Sugar. For instances that use SugarIdentity, SAML is configured in SugarIdentity.

Steps to Complete

The following sections cover how to configure Okta to allow external authentication. Please refer to the appropriate section below depending on whether your Sugar instance uses SugarIdentity or not. 

Configuring Okta With SugarIdentity

Creating SAML Integration in Okta

Use the following steps to create a new SAML integration for SugarIdentity in Okta:

  1. Navigate to https://developer.okta.com in your web browser.
  2. Open up the Create SAML App Integrations documentation on the Okta Docs website and follow steps 1 - 5 in the Create an Integration section. We will configure the SAML settings in the next step. 
  3. On the Configure SAML step, configure the fields in the General section as follows. Click the Show Advanced Settings link to display additional fields (e.g., Response, Single Logout URL) listed below. 
    Note: Replace {your_region} in the URLs with your tenant region (e.g., us-west-2) found on the Tenant Settings page in SugarIdentity.  
    • Single Sign-On URL: Enter the Assertion Consumer Service URL obtained from SugarIdentity.
      Note: If you have configured SAML authentication for SugarIdentity before December 1, 2020, and would like your users to be able to initiate the log in to Sugar from their Okta dashboard, please update this field using the steps in the Reconfiguring SAML Authentication Using ACS URL for SugarIdentity article. You will then need to obtain the metadata file mentioned in Step 6 below to import the file and reconfigure SAML Authentication in SugarIdentity.  
    • Use this for Recipient URL and Destination URL: Enabled
    • Audience URI (SP Entity ID): https://login-{your_region}.service.sugarcrm.com/saml/metadata
    • Default RelayState: [blank]
    • Name ID format: EmailAddress
    • Application Username: Email
    • Response: Signed
    • Assertion Signature: Signed
    • Signature Algorithm: RSA-SHA256
    • Digest Algorithm: SHA256
    • Assertion Encryption: Unencrypted or Encrypted
      Note: If encrypted, Okta will prompt for the encryption certificate; upload SP public key there.
    • Enable Single Logout (optional): Enable the checkbox to allow the application to initiate Single Logout
      • Single Logout URL: https://login-{your_region}.service.sugarcrm.com/saml/logout
      • SP Issuer: https://login-{your_region}.service.sugarcrm.com/saml/metadata
    • Signature Certificate: Upload your public key certificate
    • Authentication Context Class: PasswordProtectedTransport
    • Honor Force Authentication: Yes
  4. Click "Next" to save your SAML settings.
  5. In the next step, complete the SAML setup in Okta by clicking the Finish button.
  6. Before leaving Okta, access the Sign On section of your new application's settings. Click the Copy link for the Metadata URL and paste the URL in a new browser tab to open the xml. 
  7. Save this page to your computer from your browser as metadata.xml (File > Save Page As). The metadata file will be needed later when configuring SAML in SugarIdentity.

Mapping Attributes for Okta

If you wish to have the attributes (e.g., email, title) from Okta map to the SugarIdentity user fields, you will need to set up the attribute mapping in Okta. Once the attribute mapping is configured, going forward, when a new Okta user is created or the user's attributes are modified in Okta, these changes will sync to SugarIdentity when the user logs in to Sugar. If you have configured SCIM for Okta, then the changes will automatically sync to SugarIdentity in real-time. For more information on setting up the attribute mapping, please refer to the Configuring SAML Attribute Mapping for SugarIdentity article.

Assigning the SugarCRM App to Okta Users

In order for SugarIdentity users to leverage Okta's login capability with Sugar, you must assign the SugarCRM app from the Creating SAML Integration in Okta section to your organization's users in Okta. For information on assigning applications to users in Okta, please refer to the Assign application to users documentation in Okta.

Once you have assigned the SugarCRM app to Okta users, you can then configure SAML authentication in SugarIdentity.

Configuring Okta Without SugarIdentity

Creating SAML Integration in Okta

Use the following steps to create a new SAML integration for Sugar in Okta:

  1. Navigate to https://www.okta.com/ in your web browser and log in with your admin credentials. 
  2. Click "Admin" on the upper right of the home page.
    Okta Admin
  3. Next, click "Add Applications" from the Shortcuts menu on the right.
    Okta Applications
  4. Click "Create New App" on the Add Application page. 
    Okta AddApplication CreateNewApp
  5. Once the "Create a New Application Integration" window opens, select "SAML 2.0" and then click the Create button.
    Okta CreateNewAppIntegration SAML2.0 1
  6. Enter an app name of your choice (e.g., SugarCRM Application) on the General Settings step, then click "Next". 
    Okta CreateSAMLIntegration GeneralSettings 
  7. On the SAML Settings step, click the Show Advanced Settings link then enter the following values into the corresponding fields:
    Note: Replace {your-sugar-url} with your Sugar instance's domain.
    • Single sign on URL: http://{your-sugar-url}/index.php?module=Users&action=Authenticate
    • Audience URI (SP Entity ID): php-saml
    • Name ID format: EmailAddress
    • Application username: Email
    • Assertion Encryption (optional): Select "Encrypted" to encrypt the SAML assertion as an added layer of security then complete the related fields (Encryption Algorithm, Key Transport Algorithm, Encryption Certificate) that appear accordingly.
    • Enable Single Logout (optional): Enable the checkbox to allow the application to initiate Single Logout
      • Single Logout URL: http://{your-sugar-url}/index.php?module=Users&action=Logout
      • SP Issuer: php-saml
    • Signature Certificate: Locate the certificate that will be used to verify the digital signatures, then upload the file.
      Note: Administrators can generate the certificate using OpenSSL.
    Okta CreateSAMLIntegration SAMLSettings
  8. Click "Next" to save your SAML settings.
  9. Download the metadata file which will be needed later when you configure SAML authentication in Sugar.

Assigning the SugarCRM App to Okta Users

In order for Sugar users to leverage Okta's login capability with Sugar, you must assign the SugarCRM app from the Creating SAML Integration in Okta section to your organization's users in Okta. For information on assigning applications to users in Okta, please refer to the Assign application to users documentation in Okta.

Once you have assigned the SugarCRM app to Okta users, you can then configure Sugar to work with Okta. For more information on configuring Sugar for SAML authentication, refer to the Password Management documentation. 

Application

Once you have configured Okta and completed the SAML configuration in SugarIdentity or Sugar, going forward, when a user navigates to Sugar they will be redirected to Okta's login page to enter their Okta credentials. Once the user's login credentials are authenticated in Okta, they will be directed back to their Sugar instance and be automatically logged in. The user can also launch their Sugar account from Okta by clicking the SugarCRM app from their dashboard. Their Sugar instance will open in a new browser tab, and the user will be authenticated and automatically logged in.