You can authenticate your Demisto users using SAML 2.0 authentication and Okta as the identity provider. First, you have to define Demisto authentication in your Okta account, then create a SAML 2.0 instance in Demisto.
SAML 2.0 Overview
This definition of SAML 2.0 is taken from the SAML 2.0 page in Wikipedia.
Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for exchanging authentication and authorization data between security domains. SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a principal (usually an end user) between a SAML authority, named an Identity Provider, and a SAML consumer, named a Service Provider. SAML 2.0 enables web-based authentication and authorization scenarios including cross-domain single sign-on (SSO), which helps reduce the administrative overhead of distributing multiple authentication tokens to the user.
These parameters are part of the configuration process.
|User Agent||User's browser|
Add Demisto as an Okta Application
There are several steps you need to complete.
- Create Okta Groups for Demisto Users
- Define the Okta application for Demisto authentication
- Configure the SAML 2.0 integration in Demisto
- Map Okta groups to Demisto roles
Create Okta Groups for Demisto Users
To authenticate Demisto users with Okta, you need to have at least one Okta group that defines Demisto users, which will eventually be mapped to Demisto roles. There are two common methods for grouping and mapping users:
- Create a single Okta group for all users, for example, Demisto All Users.
- Create an Okta group for each business unit, for example, Demisto IT, Demisto Analysts, Demisto Admins.
How to create and add users to an Okta group
- Log in to Okta, and click the Admin button.
- Select Users > Groups.
- Click the Add Group button, and enter a meaningful name and description for the group.
The name and description should enable you to easily identify the users of that group.
- To add users to the group, click the group name and add the necessary users, and click Save.
Define the Okta application for Demisto authentication
To create a new application, log in to Okta and click the Admin button.
Click the Applications tab, and then click the Add Application button.
For platform type, select Service, and click Next.
Complete the Application Settings, and click Create.
Field Value Platform Web Sign on method SAML 2.0
In the General Settings section, enter a name for the application, and click Next.
In the SAML Settings section, configure General parameters.
Parameter Value Single sign on URL
Audience URI (SP Entity ID)
Default RelayState Keep this field empty. Name ID format EmailAddress. The Demisto username will be the user's email address, as defined in Okta. Application username Okta username
In the SAML Settings section, configure Attribute Statements parameters.
Parameter Name format Value FirstName Unspecified user.firstName LastName Unspecified user.lastName Unspecified user.email login Unspecified user.login Phone Unspecified user.primaryPhone
In the SAML Settings section, configure Group Attribute Statements parameters.
This is where you define which groups to associate with Demisto, which will be mapped to Demisto roles. In this example, we created a group that includes all uses in a single group called Everyone.
Complete the Feedback configuration.
- Select the I’m an Okta customer adding an internal app option.
- Select the This is an internal app that we have created checkbox.
Configure the SAML 2.0 Integration in Demisto
Before you configure an instance of the SAML 2.0 integration in Demisto, access the Okta Setup Instructions and Identity Provider metadata in Okta. The values of several integration parameters are located here, such as Identity Provider Single Sign-On URL.
In Demisto, navigate to Settings > Integrations > Servers & Services.
Search for SAML 2.0.
Click Add instance to configure a new integration instance.
Attribute Description Name A meaningful name for the integration instance. Service Provider Entity ID Also known as an ACS URL. This is the URL of your Demisto server, for example:
IdP metadata URL URL of your organization's IdP metadata file. IdP metadata file Your organization's IdP metadata file . IdP SSO URL URL of the IdP application that corresponds to Demisto. Attribute to get username Attribute in your IdP for the user name. Attribute to get email Attribute in your IdP for the user's email address. Attribute to get first name Attribute in your IdP for the user's first name. Attribute to get last name Attribute in your IdP for the user's last name. Attribute to get phone Attribute in your IdP for the user's phone number. Attribute to get groups Attribute in your IdP for the groups of which the user is a member. Groups delimiter Groups list separator. Default role Role to assign to the user when they are not a member of any group. RelayState Only used by certain IdPs. If your IdP uses relay state, you need to supply the relay state. Sign request and verify response signature Method for the IdP to verify the user sign-in request using the IdP vendor certificate. Identity Provider public certificate Public certificate for your IdP. Identity Provider private key Private key for your IdP, in PEM format. Created locally by the user who wants to use SAML. The public key is uploaded to Okta. Do not map SAML groups to Demisto roles SAML groups will not be mapped to Demisto roles
Click Test to validate the URLs, token, and connection.
Go back to the instance settings, and click Get service provider metadata, to verify that the settings are successful.
Map Okta Groups to Demisto Roles
It is important that when you specify the Okta group in Demisto to map to a role that you use the exact group name as it appears in Okta. Alternatively, you can specify .*, which will pass all Okta groups to the relevant Demisto roles (this is not recommended).
- In Demisto, navigate to Settings > Users & Roles > Roles.
- To create a new role, click the +New button.
- Enter a meaningful name for the role.
- Select the permissions to grant to the role.
- In the SAML Roles Mapping section, specify one or more SAML groups to map to the Demisto role.