SugarCRM SupportHelp ArticlesUser Login ManagementSAML AuthenticationConfiguring SSO With Okta Using SAML

Configuring SSO With Okta Using SAML

Overview

Sugar®/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 Okta documentation
  • 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 via the SugarCloud Settings console.

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

Note: Only some SugarCloud instances use SugarIdentity. Refer to the SugarIdentity Guide to determine if yours is configured to do so. Existing customers will be notified before their instances begin using the service.

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 URLhttp://{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 Using the Applications Page 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.

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/docs/guides/ in your web browser.
  2. On the Okta Guides page, click the "OIN Partner Integrations" link in the Guides menu on the left then click "Build a Single Sign-On (SSO) integration" and choose "Create your integration". Follow steps 1-5 of the guide then click the SAML 2.0 tab and complete steps 6-9.
    Note: The steps require the use of Okta's Classic UI and not Developer Console, which can be toggled at the top of the screen.
  3. On the SAML Settings 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} with your tenant region (e.g. us-west-2) found on the Tenant Settings page in the SugarCloud Settings console.  
    • Single Sign-On URL: Enter the Assertion Consumer Service URL obtained from SugarCloud Settings
      Note: If you have configured SAML authentication for SugarIdentity before December 1, 2020, and would like your users to be able to initiate login 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
    • Allow this app to request other SSO URLs: Disabled
    • 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 URLhttps://login-{your_region}.service.sugarcrm.com/saml/logout
    • SP Issuerhttps://login-{your_region}.service.sugarcrm.com/saml/metadata
    • Signature Certificate: Upload your public key certificate
    • Authentication Context Class: PasswordProtectedTransport
    • Honor Force Authentication: Yes
    Okta CreateSAMLIntegration SAMLSettings
  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, view the Sign On section of your new application's settings. Click on the "Identity Provider metadata" link to open the xml in a new tab. 
    saml-import-idp
  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 via the SugarCloud Settings console. 

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 into 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 Using the Applications Page documentation in Okta.

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

Application

Once you have configured Okta and completed the SAML configuration in Sugar or in SugarIdentity via the SugarCloud Settings console, 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.

Last modified: 2021-07-14 21:29:32