Adding ThreatQ as a Service Provider

ThreatQ supports SAML configurations for all identity providers that are compliant with the Security Assertion Markup Language v2.

The sections listed in this topic serve as identity provider examples and include the required steps to add ThreatQ as a service provider for your IdP. Contact ThreatQ Support if your identity provider is not listed and you require assistance with configuration.

ADFS 2016

The steps below detail how to add ThreatQ as a service provider in ADFS 2016 .

From your server manager:

1. Select AD FS under the Dashboard heading.
2. Click on the Tools option and select AD FS Management.
3. Navigate to the Relying Party Trusts folder In the left-hand directory.
4. Click on the Relying Party Trusts > Add Relying Party Trust under the Actions heading.
5. Leave the Claims Aware option selected and click on Start.

   The Select Data Source section loads.
   

6. Confirm that the first radio option, Import data about the claims provider published online..., is selected.
7. Paste the Platform Connection URL located on the ThreatQ SAML page, step 4 on the Configuring SAML topic, into the Federation Metadata Address field in the following format:

   https://<your IdP hostname>/FederationMetadata/2007-06/FederationMetadata.xml

8. Click Next.

   A popup warning will appear stating that some metadata cotent was skipped.
   

9. Click Ok to proceed.
10. Continue through the next few sections by clicking Next until you reach the Ready to Add Trust page.
11. Review the information listed in the multiple tabs provided. Confirm that the proper certificates are listed under the Certificate and Signature tabs and upload any that are missing.
12. Click Next.

    The ThreatQ Relaying Party Trust has now been added. The next step to create 4 new Claims Rules for the new service provider.

    Contact your Network Administrator to receive the appropriate group mapping.

13. Click on Add Rule.
14. Select the Send LDAP Attribute as Claims claim rule template and click Next.
15. Enter a name for the rule. Example: email and UID.
16. Select the Active Directory as the Attribute Store.

    Active Directory must already be installed and enabled in order to complete this step

17. Add the following rows in the LDAP Mapping Attributes table:

    LDAP Attribute	Outgoing Claim Type	Notes
    E-Mail-Addresses	email
    Email-Addresses	uid	Email-Addresses is the recommended value.  However, you can use SAM-Account-Name as an alternative.

18. Click on OK to create the rule.
19. Click on Add Rule.
20. Select the Send LDAP Attribute as Claims claim rule template and click Next.
21. Enter a name for the rule. Example: Email.
22. Select the Active Directory as the Attribute Store.
23. Add the following row in the LDAP Mapping Attributes table:

    LDAP Attribute	Outgoing Claim Type
    E-Mail-Addresses	E-Mail Address

24. Click on OK to create the rule.
25. Click on Add Rule.
26. Select the Send LDAP Attribute as Claims claim rule template and click Next.
27. Enter a name for the rule. Example: Groups.
28. Select the Active Directory as the Attribute Store.
29. Add the following row in the LDAP Mapping Attributes table:

    LDAP Attribute	Outgoing Claim Type
    Token-Groups - Unqualified Names	SSO

30. Click on OK to create the rule.
31. Click on Add Rule.
32. Select the Transform an Incoming Claim claim rule template and click Next.
33. Enter a name for the rule. Example: Named ID Transform.
34. Complete the following fields:

    Field	Selection
    Incoming Claim Type	E-Mail Address
    Outgoing Claim Type	Name ID
    Outgoing Name ID Format	Email

35. Select the Pass through all claim value radio option.
36. Click on OK to create the rule.
37. Click OK to close the Issuance Transform Rules dialog box.

Azure AD 

ThreatQ supports SP-Initiated SSO in Azure AD.  The steps below detail how to add ThreatQ as a service provider in Azure AD. This process is required in order to complete the SAML setup.

Setting Up the SAML App

1. Log into the Azure portal with administrator permissions.
2. Go to Azure Active Directory > Enterprise applications
3. Click on +New Application then Create your own application.
4. Choose Integrate any other application you don't find in the gallery (Non-gallery).
5. Enter an application name such as ThreatQ then click Add.
6. Select Set up single sign on then choose SAML.
7. Select Edit on Basic SAML Configuration.
8. Enter the Entity ID and Reply URL(Assertion Consumer Service URL) as follows:
   

   Field	Value	Description
   ACS / Single Sign on URL	https://threatq.example.com/api/saml/acs	Assertion Consumer Service (ACS) is the ThreatQ URL + appended the “/api/saml/acs” string.
   SP Entity ID	https://threatq.example.com/api/saml/metadata	This is the ThreatQ entity ID which is the ThreatQ URL + appended with the “/api/saml/metadata” string.

9. Under Attributes & Claims, set the Unique User identifier (Name ID) format to Email Address.
10. In the Additional claims section add uid and set the value as user.mail.

    Both the username and uid attributes are required and must be mapped to the user’s Email address.

    

11. You also need to add an attribute you want to map to the roles in ThreatQ. In this example we added a Claim and created a Groups attribute and mapped it to all user.groups assigned to the application. The group id the user belongs to is then included in the SAML assertion upon login.
    

    When adding a group claim it is recommended to customize name as this is what is required to be entered on the ThreatQ side as the SAML Attribute Key. This should not contain a namespace otherwise the full claim name will need to be entered - see http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname for more information. See the example below:
    

    In the example above, Groups would be entered as the Attribute Key in ThreatQ. The Attribute Value would be one of the Group IDs (Group Object ID) assigned to the application in Step 9.

12. On the Assignments tab, verify that each of the users or groups that should have access have been assigned to the application.
13. Under SAML Signing Certificate, click the Download link for the Certificate (Base64) and the Metadata file. These files are required in steps 4 and 5 in the Configuring SAML topic.
    
14. After you complete the Configuring SAML process, add the SAML Attribute Key and SAML Attribute Value for each ThreatQ user role to the Mapping Permissions section.
    In the example below, we mapped an Azure AD Group to the Administrative Access using the group’s Object ID as the SAML attribute value.
    

    When you test the application from the Azure Portal, you will receive the following error message: SAML authenticated but missing Client ID parameter. This happens because we do not yet support IdP-initiated SSO. You must validate the authentication from the ThreatQ application.

15. In the Azure Portal, you can navigate to the User Sign-Ins under the user to view the login attempts.
    If your authentication is successful but you receive a SAML authenticated but missing group requirements message this indicates that the required attributes mapped to the TQ roles are not configured correctly.
    

Google G Suite

The steps below detail how to add ThreatQ as a service provider in Google's G Suite. This process is required in order to complete the SAML setup.

Setting Up the SAML App

1. Log into your Google Administrative Console.
2. Navigate to Apps > SAML Apps.
3. Click on the + icon located at the bottom-right on the page.
4. Select the Setup my own custom app option.
   

   The Google IdP information page loads.
   

5. Click on Next.
6. Complete the Basic Information for Your Custom App fields:

   >Field	Description	Example
   Application Name	The name of the application.	ThreatQ
   Description	What function the app will serve.	SSO for ThreatQ Platform

   
   
7. Click on Next.
8. Complete the Service Provider Details fields:

   Field	Description	Example
   ACS URL	Assertion Consumer Service is your ThreatQ URL + appended the “/api/saml/acs” string.	https://threatq.example.com/api/saml/acs
   Entity ID	The Entity ID is your ThreatQ URL + appended with the “/api/saml/metadata” string.	https://threatq.example.com/api/saml/metadata
   Name ID Format	Set this field to Email.	N/A

   
   
9. Click on Next.

   The Attribute Mapping page loads.
   

10. Click on Add New Mapping.

    The email and uid attributes must be mapped to the Primary Email field.

11. Create the email mapping:

    Attribute	Type	Google Data Field
    email	Basic Information	Primary Email

12. Click on Add New Mapping.
13. Create the uid mapping:

    Attribute	Type	Google Data Field
    uid	Basic Information	Primary Email

14. Click on Add New Mapping:
15. Create the SSOGroup mapping for ThreatQ roles:

    Attribute	Type	Google Data Field
    SSOGroup	Employee Details	< specific to your company >

    Any attribute can be used for this mapping other than Employee ID. See the Creating custom attributes using the user schema Google support article for instructions on creating custom attributes to use for role mapping.

16. Your setup should now resemble the following screenshot:
    
17. Click on Finish.
18. Locate your new app under Apps > SAML Apps, click on the vertical ellipsis, and select On for Everyone.
19. Click on the app to open its settings details.
20. Click on Service Provider Details.

    The Service Provider Details page opens.
    

21. Click on Manage Certificates.
22. Download the certificate and the IdP Metadata files that are required in steps 4 and 5 in the Configuring SAML section in the About SAML Authentication topic.

Okta

The steps below detail how to add ThreatQ as a service provider in Okta. This process is required in order to complete the SAML setup.

1. Log into the Okta web application.
2. Click on the Admin button located to the top-right of the screen.
   The Dashboard page loads.
3. Click on the Applications tab.
   The Application page loads.
4. Click on Add Application.
5. The Add Applications page loads.
6. Click on Create New App.
   The Create New Application dialog box opens.
7. Select Web from the Platform dropdown.
8. Select SAML 2.0 for the Sign on method.
9. Click on the Create button.
   The Create SAML Integration page opens with the General Settings tab selected.
10. Enter a name for the app in the App Name field.
11. Click on Next.
    The Configure SAML section loads.
12. Complete the following fields:
    

    Field	Entry/Selection	Notes
    Single sign on URL	https://< Host-name >.com/api/saml/acs	The Assertion Consumer Service (ACS) is your ThreatQ URL + appended the “/api/saml/acs” string.
    Audience URI (SP Entity ID)	https://< Host-name >/api/saml/metadata	The Audience URI is your ThreatQ URL + appended with the “/api/saml/metadata” string.
    Name ID format	EmailAddress
    Application username	Email	ThreatQ requires that this field be set to Email.

13. Scroll down to the Attribute Statements section and add the following attribute:
    

    Name	Name Format	Value
    uid	Unspecified	user.email

14. Add the required attributes to the Group Attribute Statements that will be used to map Okta groups to ThreatQ user roles. In the example image below, an attribute called SSORole was created and is mapped to all Okta group names that starts with TQ.
    

    See Okta's Custom Expression help article for additional information on assigning an attribute.

15. Click on Preview the SAML Assertion to confirm that the settings are correct.
16. Click on Next.

    The Feedback section loads.

17. Select I'm a software vendor. I'd like to integrate my app with Okta and then click on Finish.

    The Application details page loads.

18. Click on the Assignments tab.
19. Click on the Assign dropdown and select Assign to Groups.
20. Assign the app to groups that will be used to map ThreatQ roles.
21. Click on Save and Go Back.
22. Click on Done.
23. Click on the Sign On tab.
24. In the Sign On Methods section, right-click and download the Identity Provider metadata file.
25. Click on the View Setup Instructions button.

    You will be able to review URL information such as the Identity Provider Single Sign-On URL, Identity Provider Issuer, and the X.509 Certificate.

26. Click on Download Certificate. The certificate and Identity Provider metadata file downloaded in step 23 are required in steps 4 and 5 in the Configuring SAML section of the About SAML Authentication topic.