Before you start

  • Read the "Limitations section" on Set Up SAML for Single Sign-On.
  • If you plan to manage Sumo role assignments on Okta, before you proceed, make sure that you have: 
    • Configured an Okta group for each Sumo role, with the same name as the Sumo role. For example, you should have an “Administrator” group in Okta, just as you have an “Administrator” role in Sumo.
    • Assigned your Sumo users to the appropriate Okta groups, based on the Sumo roles you want to assign to each user.  

Step 1: Configure basic SAML settings in Okta

  1. Log in to your Okta organization as a user with administrative privileges.
  2. Click Admin.
    admin-button.png
  3. Click Add Applications.
    add-applications.png
  4. Click the Create New App shortcut.
    create-new-app.png
  5. On the Create a New Application Integration page, select the SAML 2.0 option, then click Create.
    new-app-int.png
  6. General Settings.
    • App Name. Enter a name for the Sumo Logic integration app.
    • App Logo. (Optional) Upload the logo you want to appear for the app in the Okta portal.
    • Visibility. Use these options if you don’t want the Sumo Logic integration app to appear to users in the Okta portal or mobile app.
    • Click Next.
      general-settings.png
  7. In the General section under SAML Settings:
    1. Single sign on URL. Paste in this placeholder URL:
      http://example.com/saml/sso/example-okta-com
      You will get the actual URL to enter when you perform Step 2: Configure SAML in Sumo, and enter them when you perform Step 3: Complete SAML configuration in Okta.
    2. Use this for Recipient URL and Destination URL. Click the checkbox.
      saml-settings-general.png
  8. Audience URI (SP Entity ID). Enter the domain name of the Sumo Logic deployment that your Sumo account resides in. For example:
    https://service.us2.sumologic.com
  9. In the Attribute Statements section under SAML Settings add three attribute statements:
    1. For Name, enter ”firstName” and select user.firstName from the Value pulldown.
    2. For Name, enter ”lastName” and select user.lastName from the Value pulldown.
    3. For Name, enter ”Email” and select user.email from the Value pulldown.
      attribute-statements.png

Step 2: Configure Okta to send role assignments to Sumo (Optional)

In this step, you configure Okta to send group membership information in the SAML assertions it sends, so that Sumo can assign roles to a user at each logon. This allows you to manage Sumo role assignments in Okta. If you don’t want manage Sumo roles in Okta, click Next at the bottom of the Create SAML Integration page and proceed to Step 3 below.

These instructions assume that:

  • You have configured a set of groups on Okta whose names match the names of the roles defined in Sumo.
  • You have assigned each user in Okta to the Okta groups that maps to the roles you want the user to have.

There are two sides to the configuration. You'll configure a Group Attribute Statement in Okta and a Roles Attribute in Sumo Logic, eachh with the same value. Okta will include that attribute value in the SAML assertions it sends to Sumo. 

group-attributes.png

  1. Name. Enter something like “Sumo_Role” and make a note of it. Later, when you configure SAML in Sumo Logic, you’ll enter the same value in the Roles Attribute field. 
  2. Name Format. Leave unspecified.
  3. Filter. In the left-side field, choose one of the options from the pulldown, to select the type of match expression you are going to enter:
    1. Starts with. Useful of all the names of the Okta groups with Sumo users all begin with the same string.
    2. Equals. Useful if there is a single Okta group for Sumo users.
    3. Contains. Useful if all the names of the Okta groups with Sumo users all contain the same string.
    4. Matches regex. Use this option if you can’t specify your groups using any of the other filter types.  
  4. In the right-side field, enter a string or regular expression, depending on the filter type you chose. In the screenshot above, the filter type is Matches regex, and the regex Foo|A.* will match the Okta group “Foo” and groups whose names begin with the letter “A”.
  5. Click Next at the bottom of the Create SAML Integration page to proceed.

Step 3: Enter Okta feedback info

In Step 3 "Feedback", select I'm an Okta customer adding an internal app, and This is an internal app that we have created, then click Finish.
feedback.png

Step 4: View Okta SAML settings for Sumo

In this step, you view the SAML settings generated by Okta that you’ll need when complete the SAML configuration in Sumo.

  1. On Sign On Methods section appears. Click View Setup Instructions.settings.png
  2. The page displays the information you need to do Step 5: Configure SAML in Sumo. Keep the page open.
    config-instructions.png

Step 5: Configure SAML in Sumo

This section has instructions for configuring basic SAML in Sumo Logic.

  1. Go to Administration > Security > SAML.
  2. Click Add Configuration.
    sumo-saml-config-list.png                                                                                            
  3. The Add Configuration page appears.
    sumo-saml-config.png
  4. Configuration Name. Enter a name to identify the SSO policy (or another name used internally to describe the policy).
  5. Debug Mode. Select this option if you'd like to view additional details if an error occurs when a user attempts to authenticate. For more information, see View SAML Debug Information.
  6. Issuer. Paste in the Identity Provider Issuer that Okta presented in Step 4: View Okta SAML settings for Sumo.
  7. X.509 Certificate. Paste in the certificate that Okta presented in  that was presented in the Step 4: View Okta SAML settings for Sumo.
  8. Attribute mapping. Select Use SAML Subject.
  9. Roles Attribute. (Required if you performed the steps in Step 2: Configure Okta to send role assignments in Sumo). If you specify the Roles Attribute option, Sumo Logic assigns roles to a user every time the user logs in. Roles are configured by your Okta  administrator and assigned as part of the SAML assertion.
    1. Click the Roles Attribute checkbox. The Roles Attribute field appears.
    2. Roles Attribute. Enter the Group attribute name, for example "Sumo_Role", you defined in Step 2: Configure Okta to send role assignments in Sumo.
  10. On-demand provisioning. If you configure this feature, Sumo Logic will create a new user’s account the first time the user accesses Sumo Logic using Okta. For instructions, see On-Demand Provisioning.
  11. Logout Page. When a Sumo user logs out of Sumo Logic or if the user’s session times out, they will be redirected to the logout page you specify. For example, you could redirect users to their Okta homepage, substituting your Okta domain in the following URL:
    https://YourOktaDomain.onelogin.com/app/UserHome
  12. Click Save
  13. To view the details of your configuration, select it the Configuration List. Keep the panel open. When you complete the Okta configuration in Step 3 below, you will copy the Authentication Request and Assertion Consumer values into Okta.

Step 6: Complete SAML configuration in Okta

  1. Go back to the Okta Admin Panel.
  2. Go to the General tab.
  3. Under SAML Settings, click Edit
    edit-saml-settings.png
  4. The General Settings page appears. Click Next
  5. The Edit SAML Integration pane appears.
    edit-saml-integration.png
  6. Single Sign On URL. Change to the Assertion Consumer URL from your Sumo Logic SAML settings, which you obtained in the last step of Step 2: Configure SAML in Sumo.
  7. Use this for Recipient URL and Destination URL.  Deselect the checkbox.
  8. Recipient URL and Destination URL. Enter the Authentication Request URL from your Sumo Logic SAML settings, which you obtained in  the last step of Step 2: Configure SAML in Sumo into both fields.
  9. Audience URI (SP Entity ID). This field is not required unless you configure SP-initiated authentication. For more information see SP-initiated login.
  10. Click Next and then Finish.

Sumo Logic is now linked with Okta. 

Step 7: Add Okta users to the Sumo Logic app in Okta 

  1. Click the Directory tab. Click the user you want to add to the app.
    directory.png
  2. Click Assign Applications.
    assign-applications.png
  3. Click Assign on the row for the application to which you want to add the user.
    assign-applications2.png
  4. Click Save and Go Back.
    assign-applications3.png
  5. Click Done.

The Sumo Logic app you configured should now appear on the user’s Okta work page. To check that the integration works, have the user click the app icon, and verify that they are logged onto Sumo Logic. 
 

Configure optional SAML features

Configure SP-initiated SSO

This configuration enables a Sumo user to initiate login from the Sumo Logic web app. Sumo redirects the user to Okta with a SAML AuthnRequest with the information that Okta needs to authenticate the user. Okta replies to Sumo with a SAML Assertion. 

  1. On the Sumo Add Configuration page, click the SP Initiated checkbox. 
    sp-settings.png
  2. Login Path. Enter a unique identifier for your org. You can specify any alphanumeric string (with no embedded spaces), provided that it is unique to your org. (You can't configure a Login Path that another Sumo customer has already configured). The identifier is used to generate a unique URL for user login. For example, if you enter
    yourcompanyname

    If you enter a Login Path that is not unique across all Sumo orgs, Sumo issues this error: 
    SP Initiated login path in use. Please enter a different path.
     
  3. Authn Request URL.  Paste in the Identity Provider Single Sign-On URL that Okta presented in Step 4: View Okta SAML settings for Sumo.

Configure On-Demand Provisioning

If you configure on-demand provisioning, Sumo Logic automatically creates a user account the first time a user logs on to Sumo on using Okta single single-on.  When user clicks the Sumo Logic app in Okta, Okta sends a SAML assertion to Sumo with the info necessary to create the user account, and to assign that user to Sumo roles. 

To configure on-demand provisioning, you supply the First Name and Last Name attributes Okta uses to identify users, and the Sumo roles you want to assign to the accounts created.

  1. Click the On Demand Provisioning checkbox.
    on-demand-provisioning.png
  2. First Name. Enter: 
    FirstName 
  3. Last Name. Enter:
    LastName 
  4. On Demand Provisioning Roles. Specify the Sumo RBAC roles you want to assign when user accounts are provisioned. (The roles must already exist in Sumo.) If you enter multiple roles, put commas in between them. For example:
    Analyst, CollectorManager

Lock down SAML

Check SAML usage

If you intend to require Sumo users to sign-in using SAML, as described in the following section, Require SAML for sign-in, it is a best practice to first check whether some users are still logging in directly, instead of using SAML. You can run the following query to see, for a particular time range, whether users signed in using SAML or with their username and password:

_index=sumologic_audit action=login | count by class, sourceuser 

The query results show, for each user that has accessed Sumo over the time range, the number of times they have logged in using SAML or by entering a Sumo username and password. In the class column:

  •  "SAML" indicates the user signed in using SAML.  
  •  "SESSION" indicates the user authenticated by entering a username and password.  

If the same user accessed Sumo using both methods (SAML and direct logon) during the time range, the query results will include a row for each method, showing how many times each method was used. 

saml-use-query.png

Require SAML for sign-in

After you create a SAML configuration, you can require users to sign in using SAML and prevent users from bypassing SAML with a username and password for login. Before you do so, follow the instructions in Check SAML Usage.

Check SAML Usage

If you intend to require Sumo users to sign-in using SAML, as described in the following section, Require SAML for sign-in, it is a best practice to first check whether some users are still logging in directly, instead of using SAML. You can run the following query to see, for a particular time range, whether users signed in using SAML or with their username and password:

_index=sumologic_audit action=login | count by class, sourceuser 

The query results show, for each user that has accessed Sumo over the time range, the number of times they have logged in using SAML or by entering a Sumo username and password. In the class column:

  •  "SAML" indicates the user signed in using SAML.  
  •  "SESSION" indicates the user authenticated by entering a username and password.  

If the same user accessed Sumo using both methods (SAML and direct logon) during the time range, the query results will include a row for each method, showing how many times each method was used. 

saml-use-query.png

Require SAML for sign-in 

Click Require SAML Sign In to require users to sign in using SAML.

require-saml.png

Sumo automatically adds your account under Allow these users to sign in using passwords in addition to SAML as a whitelisted user as a preventative measure to ensure you’re still able to access Sumo if you run into issues.

Having only one user able to bypass SAML may not be convenient or practical if you have a global company or a large team. You can add additional whitelisted users by clicking the (+) icon by Allow these users to sign in using passwords in addition to SAML:

allow-users.png

We do not recommend denying all users password access to Sumo even if you want to enforce log in by SAML. If you attempt to delete your last remaining whitelisted user, you will receive a warning that this is not a recommended practice:

prevent-password-based-login.png

SAML lockdown limitations

There are two user account changes an admin cannot perform when the Require SAML Sign In option is selected:

  • You cannot change a user's login email address when SAML is locked down.
  • If a user's account has been locked as a result of too many failed login attempts, you cannot unlock the account while SAML is locked down.

To change a user's login email address or unlock a user account, you must toggle off the Require SAML Sign In option, make the update, and then turn Require SAML Sign In back on.