--- id: set-up-saml title: Set Up SAML for Single Sign-On description: Follow the steps to configure SAML-based single sign-on (SSO) in Sumo Logic for secure, centralized user authentication. slug: /help/docs/manage/security/saml/set-up-saml/ canonical: https://www.sumologic.com/help/docs/manage/security/saml/set-up-saml/ --- import useBaseUrl from '@docusaurus/useBaseUrl'; ## Availability | Account Type | Account Level | |:--|:--| | Cloud Flex | Trial, Enterprise | | Credits | Trial, Essentials, Enterprise Operations, Enterprise Security, Enterprise Suite | This page has information about provisioning Security Assertion Markup Language (SAML) 2.0 to enable Single Sign-On (SSO) for user access to Sumo Logic. In addition to basic SAML configuration, you can choose optional on-demand user creation (using SAML 2.0 assertions), and designate custom login and/or logout portals. import TerraformLink from '../../../reuse/terraform-link.md'; :::tip You can use Terraform to provide a SAML configuration with the [`sumologic_saml_configuration`](https://registry.terraform.io/providers/SumoLogic/sumologic/latest/docs/resources/saml_configuration) resource. ::: ## SAML provisioning process The provisioning process works as follows: 1. Identify the service provider you will use for SSO. For example: * [AWS Single Sign-On](/docs/manage/security/saml/integrate-aws-sso/) * [Azure Active Directory (AD)](/docs/manage/security/saml/integrate-sumo-with-azure-ad/) * [Google IAM](/docs/manage/security/saml/integrate-google-iam-service/) * [Microsoft Active Directory Federation Services (ADFS)](/docs/manage/security/saml/set-up-adfs-authenticate-users/) * [Okta](/docs/manage/security/saml/integrate-sumo-logic-with-okta/) * [OneLogin](/docs/manage/security/saml/integrate-onelogin/) 1. Configure SAML parameters in Sumo Logic. 1. Configure service provider settings for Sumo Logic in the SSO system, and verify that any additional Role-Based Access Control (RBAC) roles and groups are set up. 1. When provisioning is complete, users attempting to access Sumo Logic will be authenticated through the SSO system. ## Limitations This section has key information about SAML in Sumo Logic. ### Access keys are not controlled by SAML This means that if a user has been turned off on the SSO side, their access keys would still be valid. For this reason, administrators should audit users regularly and disable access keys when necessary. ### SAML does not provide a deprovisioning mechanism  This means that if a user is deleted or disabled in the SSO database, it will not be reflected in Sumo Logic. However, these users would no longer be able to sign in to Sumo Logic via SSO. Administrators can delete these users from the **Users** page in Sumo Logic. For information about what happens when a user is deleted, and transferring a deleted user's content to another user, see [Delete a User](/docs/manage/users-roles/users/delete-user/). ### Only one certificate for each SAML configuration is currently supported Only one token-signing ADFS X.509 for each SAML configuration is currently supported. When you need to do a certificate refresh on the ADFS server, you must update the Sumo Logic certificate afterwards. ## Prerequisites Before provisioning SAML, make sure you have the following: * **An installed Identity Provider (IdP) SSO system that supports SAML 2.0.** Several SAML IdPs are available. If your organization's IdP supports SAML 2.0 you can configure SAML in Sumo Logic. Examples: Microsoft ADFS, Okta, OneLogin. * **X.509 certificate.** This certificate is used to verify the signature in SAML assertions. * **Valid email address.** An email attribute is required in the assertion: either the SAML subject or another SAML attribute per the SAML configuration. The value of the email attribute must be a valid email address. It is used to uniquely identify the user in the organization. ## Configure basic SAML in Sumo Logic Follow these steps to configure IdP-initiated login. After this procedure, you can enable optional SAML functionality, including SP-initiated login and on-demand provisioning, as described in [Optional configurations](/docs/manage/security/saml/set-up-saml/#optional-configurations). 1. [**New UI**](/docs/get-started/sumo-logic-ui). In the main Sumo Logic menu select **Administration**, and then under **Account Security Settings** select **SAML**. You can also click the **Go To...** menu at the top of the screen and select **SAML**.
[**Classic UI**](/docs/get-started/sumo-logic-ui-classic). In the main Sumo Logic menu, select **Administration > Security > SAML**. 1. Select an existing configuration, or click the plus (**+**) icon to create a new configuration.
Plus button on the Configuration List page 1. The **Add Configuration** page appears.
Add Configuration page 1. **Configuration Name**. Enter a name to identify the SSO policy (or another name used internally to describe the policy). 1. **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](/docs/manage/security/saml/view-saml-debug-information/). 1. **Issuer**. Enter the unique URL assigned to your organization by the SAML IdP. 
ADFS example: `http://adfs.myserver.tld/adfs/services/trust` 1. **X.509 Certificate**. Copy and paste your organization's X.509 certificate, which is used to verify signatures in SAML assertions. For ADFS, the certificate required is the Token-signing ADFS X.509 certificate. The certificate must include the hash text including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. 1. **Attribute Mapping**. Depending on your IdP, select:  * **Use SAML subject** * **Use SAML attribute** and type the email attribute name in the text box. 1. **Optional Settings**. See the [Optional configurations](#optional-configurations) section below for directions. * **SP Initiated Login Configuration**. See [Configure SP initiated login](#configure-sp-initiated-login). * **Roles Attribute**. See [Configure on-demand roles provisioning](#configure-on-demand-roles-provisioning). * **On Demand Provisioning**. See [Configure on-demand user account provisioning](#configure-on-demand-user-account-provisioning). * **Logout Page**. [Configure logout page](#configure-logout-page). 1. Click **Import Metadata XML** to import the metadata XML file you previously downloaded from your identity provider (IdP). (If you need to export the metadata XML from your SAML configuration later, see [Download metadata XML](#download-metadata-xml) below.) 1. If you are done configuring SAML, click **Add** to save your changes, and proceed to [Review SAML configuration](/docs/manage/security/saml/set-up-saml/#review-saml-configuration). To configure optional SAML features, see the following section.  ## Review SAML configuration 1. To view the details of your configuration, select it from the **Configuration List**. The right side of the page displays the configuration details. For any SAML configuration, you'll see an **Assertion Consumer** URL. If you configure SP-initiated login, you'll also see an **Entity ID**.
Configuration list 1. Click **View Metadata XML** to see the metadata XML file for the configuration. You can also use this button to [download the metadata XML](#download-metadata-xml). 1. Click the pencil icon to modify the configuration settings. Otherwise, click **X** to close the dialog box.  ## Optional configurations This section has instructions for configuring several optional SAML features. ### Configure SP initiated login  :::tip SP initiated login requires a custom Sumo Logic subdomain. If a custom subdomain has not yet been configured for your org, follow the instructions in [Set up account subdomain](/docs/manage/manage-subscription/create-and-manage-orgs/manage-org-settings/#set-up-a-customsubdomain). ::: This section has instructions for setting up SP initiated login. When SP initiated login has been enabled, your SAML configuration will appear as an additional authentication option within your subdomain-enabled account login page. In the steps below, you provide the information necessary for Sumo Logic to issue a SP initiated authentication request to your IdP. 1. Click **SP Initiated Login Configuration** in the **Optional Settings** section of the SAML configuration page. When you click this option, the **Authn Request URL** field appears.  1. **Authn Request URL.** Enter the URL that the IdP has assigned for Sumo Logic to submit SAML authentication requests to the IdP.  This field is required if you checked the **SP Initiated Login Configuration** checkbox.
ADFS example: `https://adfs.myserver.tld/adfs/ls/` 1. **Disable Requested Authn Context**. If you check this option, Sumo Logic will not include the RequestedAuthnContext element of the SAML AuthnRequests it sends to your Idp. This option is useful if your IdP does not support the RequestedAuthnContext element. 1. (Optional) **Sign Authn Request**. If you select this option, Sumo Logic will send signed Authn requests to your IdP. When you click this option, a Sumo Logic-provided X-509 certificate is displayed. You can configure your IDP with this certificate to verify the signature of the Authn requests sent by Sumo Logic.  :::note The X-509 certificate provided for Authn Request signing can also be used to configure encrypted assertions. For details, see your IdP documentation for instructions on how to configure encrypted assertions. ::: 1. If you are done configuring optional SAML features, click **Add** to save your changes, and proceed to [Review SAML configuration](/docs/manage/security/saml/set-up-saml/#review-saml-configuration). To configure optional SAML features, see the following section.  ### Configure on-demand roles provisioning  If you enable the **Roles Attribute** option, Sumo Logic assigns roles to a user every time the user logs in. Roles are configured by your IdP and assigned as part of the SAML assertion. For this feature, you must have: * Configured a group on your IdP for each Sumo Logic role that you want to provision, with the same name as the Sumo Logic role. For example, you should have an “Administrator” group in your  IdP, just as you have an “Administrator” role in Sumo Logic. * Assigned your Sumo Logic users to the appropriate groups in your IdP, based on the Sumo Logic roles you want to assign to each user.   1. Click the **Roles Attribute** checkbox. The **Roles Attribute** field appears. 1. **Roles Attribute.** Enter the SAML Attribute Name that is sent by the IdP as part of the assertion. For example, "Sumo_Role". :::note There are two parts to configuring on-demand roles provisioning: You configure the **Roles Attribute** on the Sumo Logic side, and you configure that same value using a option when configuring the IdP to integrate with Sumo Logic. The option or parameter you set depends on the IdP. ::: 1. If you are done configuring optional SAML features, click **Add** to save your changes, and proceed to [Review SAML configuration](/docs/manage/security/saml/set-up-saml/#review-saml-configuration). To configure optional SAML features, see the following section.  ### Configure on-demand user account provisioning If you configure on-demand provisioning, Sumo Logic automatically creates a user account the first time a user logs on to Sumo Logic. To complete this procedure, you need to supply the First Name and Last Name attributes your IdP uses to identify users. When the account is created, Sumo Logic credentials are emailed to the user. Users need both Sumo Logic credentials and SAML permissions. 1. Click the **On Demand Provisioning** checkbox. 1. **First Name Attribute**. You might need to provide the full attribute path, which can vary based on the ADFS version (the actual path can be seen in the SAML assertion). The following are examples:
`http://schemas.microsoft.com/ws/2008/06/identity/claims/givenname`   1. **Last Name Attribute**. You might need to provide the full attribute path, which can vary based on the ADFS version (the actual path can be seen in the SAML assertion). The following are examples:
`http://schemas.microsoft.com/ws/2008/06/identity/claims/surname`   1. **On Demand Provisioning Roles**. Specify the Sumo Logic RBAC roles you want to assign when user accounts are provisioned. (The roles must already exist.) 1. If you are done configuring optional SAML features, click **Add** to save your changes, and proceed to [Review SAML configuration](/docs/manage/security/saml/set-up-saml/#review-saml-configuration).   ### Configure logout page Configure a logout page if you would like to point Sumo Logic users to a particular URL after logging out of Sumo Logic or after their session has timed out. You could choose your company's intranet, for example, or any other site that you'd prefer users in your organization access. 1. Click the **Logout Page** checkbox. 1. Enter the URL of the page to which you want to direct users after logging of Sumo Logic. 1. Click **Add** to save your configuration, and proceed to [Review SAML configuration](/docs/manage/security/saml/set-up-saml/#review-saml-configuration).   ## Create multiple SAML configurations import Saml from '../../../reuse/saml.md'; ## Download metadata XML Sometimes, you may have a need to download the metadata XML from one of your SAML configurations. For example, you may need to provide the XML to an identity provider for their configuration. Following are ways to download the metadata XML. ### Download metadata XML with Download Metadata XML button Click the **Download Metadata XML** button while you [review a SAML configuration](#review-saml-configuration) to download the XML as a file named `metadata.xml`. View Metadata XML button ### Download metadata XML with the API You can get the metadata XML for a SAML configuration using the [getSamlMetadata](https://api.sumologic.com/docs/#operation/getSamlMetadata) API in the [SAML Configuration](https://api.sumologic.com/docs/#tag/samlConfigurationManagement) resource. Run the API from your API endpoint. To find your API endpoint, see [API Authentication, Endpoints, and Security](/docs/api/about-apis/getting-started/). If you need to give your identity provider a URL that contains the metadata XML for a SAML configuration, run the [getIdentityProviders](https://api.sumologic.com/docs/#operation/getIdentityProviders) API. This will give you a list of all SAML configurations in your organization and includes the metadata URL for each configuration. In the response from the API, look for `metadataURL` entries. For example: `"metadataUrl": "https://api.sumologic.com/api/v1/saml/identityProviders/00000000361130F7/metadata"` The configuration ID for the SAML configuration is embedded in the URL. In the preceding example, the configuration ID is `00000000361130F7`.