How to Configure SAML SSO Integration with JupiterOne

Single sign-on is supported using a custom authentication client configured within a J1 account. This feature is available to all Enterprise customers.

Supported Features

• SP-initiated SSO

  Service Provider-Initiated (SP-initiated) SSO means when the service provider (SP) initiates SAML authentication. SP-initiated SSO is triggered when you try to access a resource in J1.

• JIT (Just In Time) Provisioning

  Users are created and updated instantly using the SAML attributes sent as part of the SAML response coming from the Identity Provider (IdP). The user is created during the initial sign-in to J1 and updated during subsequent sign-ins.

note

IdP-initiated SSO is currently unsupported due to a limitation of Amazon Cognito.

Configuring SSO

You must be a member of the Administrators group to perform configurations.

1. In your JupiterOne workspace, navigate to Settings > Security & Access.

2. Enable the Single Sign On (SSO) toggle.

3. You will be provided the SSO URL and Audience URI (SP Entity ID) for you to provide your IdP SSO application.

4. Copy the SSO URL and Audience URI and enter them where necessary for your IdP SSO application. In your IdP account, add a new SAML application and name it JupiterOne.

   1. Copy the SSO URL and Audience URI values in the SAML settings.
   2. Use the same JupiterOne single sign-on URL string value for Recipient URL and Destination URL.
   3. Leave the Default Relay State field empty.
   4. Select EmailAddress for the name ID format.
   5. Select Email or Username for the application username.
   6. See the next section for details on attribute mappings.

5. Complete the configuration of the SAML application in your IdP account, and copy the identity provider metadata link. For example, in Okta, you can find this link on the Sign On tab of the application, under Metadata details > Metadata URL. ​

6. Go back to the JupiterOne single sign-on settings, and paste the identity provider metadata link in the SAML Metadata File field. Alternatively, you can enter the SAML Metadata manually if you so choose. Simply select Type the SAML Metadata file manually and enter the metadata into the provided text field.

7. Save your settings to complete the configuration. Next time you access your JupiterOne account using your organization custom URL (for example, https://your_company.apps.us.jupiterone.io), you are redirected to your SAML IdP for authentication.

Attribute Mappings

JupiterOne supports the following SAML attribute mappings:

• email: User email address (required)
• family_name: User last name
• given_name: User first name
• name: User display name
• group_names: Dynamically assigns the user to the specified groups within JupiterOne.

J1 highly recommends that if you are a large organization, you should use the JupiterOne1 API to create group names and then use the group_names attribute to more easily synchronize all username data with J1 on a regular basis. You can use the group_names attribute to equate to a filtered list of groups that match the names of the J1 groups (case-sensitive). For example, create a group name to contain all the users who have administrative privileges in J1.

note

Users without a group_names mapping are assigned to your workspace's configured default groups (the Users group, unless you have changed it). This fallback can be turned off in Settings > Security & Access with the Assign default groups to SSO users without group claims switch; when it is off, a sign-in with no group_names claim does not create a user or change any group memberships. See Admin settings for details.

Okta Configuration

To configure SSO for Okta, you must have administrator access. In addition, ensure you can access the SSO URL and your Audience URI before proceeding.

1. In the Okta Admin Console, go to Applications > Applications and click Create App Integration.

2. Select SAML 2.0 and click Next.

3. Enter a name in the App name field, such as JupiterOne, and click Next.

4. In the SAML Settings section:

   • In the Single sign-on URL field, enter your SSO URL. Leave Use this for Recipient URL and Destination URL selected.
   • In the Audience URI (SP Entity ID) field, enter your Audience URI.
   • In the Name ID format field, select EmailAddress.
   • In the Application username field, select Email.

5. Click Next.

6. On the Feedback step, select This is an internal app that we have created, and click Finish.

7. On the app's Sign On tab, go to Attribute statements and click Add expression for each of the following. Only email is required.

   Name	Expression
   email	user.profile.email
   family_name	user.profile.lastName
   given_name	user.profile.firstName
   name	user.profile.displayName

8. To send group_names, first create the jupiterone_groups app attribute (see Okta Group Attribute Configuration). The expression editor cannot reference app user attributes, so expand Show legacy configuration, click Edit under Profile attribute statements, add group_names with the value appuser.jupiterone_groups, and click Save.

9. Under Metadata details on the Sign On tab, click Copy next to Metadata URL.

10. Paste the link into the SAML Metadata Document URL field in JupiterOne.

11. Click Save in the top right of the window to save your configuration. A green confirmation message displays in the lower-left corner of the screen.

Okta Group Attribute Configuration

JupiterOne recommends adding a custom group attribute to the JupiterOne app profile in your IdP account (such as Okta). In Okta, go to Directory > Profile Editor, open the JupiterOne User profile, and click Add Attribute. Enter jupiterone_groups for the Display name and Variable name, set Attribute type to Group, and click Save.

An example in Okta:

You can then use this custom app attribute to assign group memberships to your users based on their IdP group assignments. Set the value on the groups assigned to the app: on the app's Assignments tab, click Assign > Assign to Groups, click Assign next to a group, enter a comma-separated list of JupiterOne group names in jupiterone_groups, and click Save and Go Back.

An example in Okta:

Microsoft Entra ID Configuration

To configure SSO for Microsoft Entra ID (formerly Azure AD), you must be able to create enterprise applications in your tenant. In addition, ensure you can access the SSO URL and your Audience URI before proceeding.

1. In the Microsoft Entra admin center, go to Entra ID > Enterprise apps and click New application.

2. Click Create your own application, enter a name such as JupiterOne, select Integrate any other application you don't find in the gallery (Non-gallery), and click Create.

3. In the app, go to Single sign-on and select SAML.

4. Click Edit on Basic SAML Configuration:

   • Under Identifier (Entity ID), click Add identifier and enter your Audience URI.
   • Under Reply URL (Assertion Consumer Service URL), click Add reply URL and enter your SSO URL.
   • Click Save.

5. Click Edit on Attributes & Claims. Delete the default claims under Additional claims, then click Add new claim for each of the following. Leave Namespace empty. Only email is required.

   Name	Source attribute
   email	user.mail
   family_name	user.surname
   given_name	user.givenname
   name	user.displayname
   group_names	user.assignedroles

   

6. On the Single sign-on page, under SAML Certificates, copy the App Federation Metadata Url.

7. Paste the link into the SAML Metadata Document URL field in JupiterOne, and click Save.

Entra ID Group Assignment

The user.assignedroles → group_names claim sends the app roles assigned to a user, and JupiterOne maps each role to the JupiterOne group with the same name (case-sensitive).

To create an app role for each JupiterOne group:

1. Go to Entra ID > App registrations, open the JupiterOne app (under All applications), and click App roles.

2. Click Create app role. Enter the JupiterOne group name, such as Administrators, in Display name and Value, select Users/Groups for Allowed member types, enter a description, and click Apply.

To assign a role, go back to the enterprise app, open Users and groups, click Add user/group, select the users or groups, select the role, and click Assign.

info

Read Microsoft's documentation for more information on adding app roles and assigning them to users and groups.

Google Workspace Configuration

Before beginning a configuration through Google Workspace, ensure you have access to the SSO URL and your audience URI. Go to the Google Admin Console.

1. From the Add App dropdown menu, select Add custom SAML app.
2. In the App name field, enter JupiterOne.
3. Click DOWNLOAD METADATA to download an XML metadata file to use later.
4. Paste your SSO URL in the ACS URL field.
5. In the Entity ID field, paste your Audience URI. In the Name ID format field, select EMAIL, and select Primary email in the Name ID field.
6. When mapping directory attributes, ensure you use the following names in the App attributes fields. group_names is optional.

• Primary email > email
• Last name > family_name
• First name > given_name

6. Paste the downloaded XML metadata file contents into the SAML Metadata File field.

Current Limitations

IdP-initiated sign-on flow is not supported

JupiterOne uses Amazon Cognito service to manage authentication, including SSO. Cognito currently does not support IdP-initiated sign-on. This means you can not click on the app icon in your IdP account (such as JumpCloud, Okta, OneLogin). Instead, you must initiate single sign-on by going to your JupiterOne vanity (custom) URL or your account sign-in URL:

JupiterOne vanity URL:

https://<your_j1_subdomain>.apps.us.jupiterone.io

JupiterOne account login URL:

https://login.us.jupiterone.io/account/<your_j1_account_id>

These URLs redirect to your configured SSO provider for authentication.

You can find your J1 account ID by running the following query:

Find jupiterone_account as a return a.accountId

Workaround

If your SSO provider supports configuring a bookmark or secure web authentication (SWA) app, you can work around this limitation by doing the following:

• Hide the app icon to users for the configured JupiterOne SAML SSO app.
• Configure a Bookmark/SWA app with your JupiterOne account URL and assign it to the same users and groups that are assigned the JupiterOne SAML app.

Troubleshooting

Different SSO providers have varying UIs and nomenclature, therefore, ultimately the SAML response and attribute statement should look similar.

Common Problems

Infinite Redirect Loop

An infinite redirect loop can occur if the SAML subject is incorrect or missing or if the required SAML attribute email (case-sensitive) is not present.

SAML Subject

A common problem during SSO configuration is an incorrect SAML subject. Here is an example of a correct subject:

<saml2:Subject>
    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">john.smith@example.com</saml2:NameID>
    ...
</saml2:Subject>

SAML Attribute Statement

Another common problem during SSO configuration is an incorrect SAML attribute statement. An example of a correct attribute statement is:

<saml2:AttributeStatement>
    <saml2:Attribute Name="email">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">john.smith@example.com</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="family_name">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">Smith</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="given_name">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">John</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute Name="group_names">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">Administrators,Users</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>

Viewing the SAML Response

To view the SAML response, you can use browser plugins to capture the POST to /saml2/idpresponse. For example, in the Chrome browser the plugin, you can use SAML-tracer to decode and view the SAML response and, therefore, the SAML attribute statement.

The following is an example of what SAML-tracer looks like after logging in by SSO. The SAML tab is active to view the XML. Calls that have SAML are also flagged with a yellow SAML tag on the right of the HTTP request.