Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
How to Configure SAML SSO Integration with JupiterOne - AskJ1 Community
<main> <article class="userContent"> <p>Single sign-on is supported using a custom authentication client configured within a J1 account. This feature is available to all Enterprise customers.</p> <h2 data-id="supported-features">Supported Features</h2> <ul><li><p><strong>SP-initiated SSO</strong></p> <p>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.</p></li> <li><p><strong>JIT (Just In Time) Provisioning</strong></p> <p>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.</p></li> </ul><p><strong>Note</strong>: IdP-initiated SSO is currently unsupported due to a limitation of Amazon Cognito.</p> <h2 data-id="configuring-sso">Configuring SSO</h2> <p>You must be a member of the Administrators group to perform configurations.</p> <ol><li><p>Sign in to your JupiterOne account.</p></li> <li><p>Go to the <strong>Single Sign On</strong> setup from the Settings menu <img src="https://us.v-cdn.net/6035534/uploads/Y6I8KPLFAPVW/gear.png" alt="" class="embedImage-img importedEmbed-img"></img>. <br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/S8ORRC1QWYKQ/sso-select.png" alt="sso-menu" class="embedImage-img importedEmbed-img"></img></p> <p></p></li> <li><p>Click <strong>Configure</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/N5J1RBBWWRJ2/j1-configure-sso.png" alt="configure-sso" class="embedImage-img importedEmbed-img"></img></p> <p></p></li> <li><p>In the J1 Single Sign-on page, copy the following two variables to use when adding J1 as an application in your SAML IdP account:</p> <ul><li>SSO URL</li> <li>Audience URI (SP Entity ID)<br> </li> </ul><p><img src="https://us.v-cdn.net/6035534/uploads/5K0VQARU3GY0/sso-setup-page.png" alt="sso-setup-page" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>In your IdP account, add a new SAML application and name it JupiterOne.</p> <ul><li>Copy the SSO URL and Audience URI values in the SAML settings.</li> <li>Use the same J1 single sign-on URL string value for Recipient URL and Destination URL.</li> <li>Leave the Default Relay State field empty.</li> <li>Select EmailAddress for the name ID format.</li> <li>Select Email or Username for the application username.</li> <li>See the next section for details on attribute mappings.</li> </ul></li> <li><p>Complete the configuration of the SAML application in your IdP account, and copy the identity provider metadata link.</p> <p>In Okta, you can find this link on the <strong>Sign On</strong> tab of the application, under View Setup Instructions.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/NVPS8P49ODRF/okta-idp-metadata.png" alt="okta-idp-metadata" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Go back to the JupiterOne single sign-on page, and paste the identity provider metadata link in the SAML Metadata File field.</p></li> <li><p>Enter a client name, such as Okta.</p></li> <li><p>Under Allowed OAuth Flows, select the <strong>Authorization code grant</strong> and <strong>Implicit Grant</strong> checkboxes.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/AS30T5LM3TQB/j1-sso-client-oauth-flows.png" alt="allowed-oauth-flows" class="embedImage-img importedEmbed-img"></img></p> <p><br> Save your settings to complete the configuration. Next time you access your JupiterOne account using your organization custom URL (for example, <a href="https://your_company.apps.us.jupiterone.io)" rel="nofollow">https://your_company.apps.us.jupiterone.io)</a>, you are redirected to your SAML IdP for authentication.</p></li> </ol><h2 data-id="attribute-mappings">Attribute Mappings</h2> <p>JupiterOne supports the following SAML attribute mappings:</p> <ul><li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">email</code>: User email address (required)</li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">family_name</code>: User last name</li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">given_name</code>: User first name</li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">name</code>: User display name</li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">group_names</code>: Dynamically assigns the user to the specified groups within JupiterOne.</li> </ul><p>J1 highly recommends that if you are a large organization, you should use the <a rel="nofollow" href="../../jupiterone-api.md">J1 API</a> to create group names and then use the <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">group_names</code> attribute to more easily synchronize all username data with J1 on a regular basis. You can use the <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">group_names</code> 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.</p> <p><strong>NOTE:</strong> Users without <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">group_names</code> mapping are assigned to the <strong>Users</strong> group within your J1 account, by default.</p> <h2 data-id="okta-configuration">Okta Configuration</h2> <p>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.</p> <ol><li><p>From the Okta Applications menu, select <strong>Create App Integration</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/PHT6GTQV9GIO/okta-create-app-integration.png" alt="Okta-Create-App-Integration" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Select <strong>SAML 2.0</strong> and click <strong>Next</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/2LYYR75DIR83/okta-saml-select.png" alt="okta-saml-select" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Enter a name in the <strong>App Name</strong> field. The name JupiterOne is used in the example below, and click <strong>Next</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/JCXFILTL8TNW/okta-sso-general-settings.png" alt="okta-sso-general-settings" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>In the SAML Settings sections:</p> <ul><li>In the Single sign on URL field, enter your SSO URL.</li> <li>In the Audience URI (SP Entity ID) field, enter your Audience URI.</li> <li>In the Name ID format field, select EmailAddress.</li> <li>In the <em>Application username</em> field, select Email.</li> </ul><p><img src="https://us.v-cdn.net/6035534/uploads/F4X88SXYH8DB/okta-saml-settings.png" alt="okta-saml-settings" class="embedImage-img importedEmbed-img"></img></p></li> <li><p>Configure the attribute mappings in the Attribute Statements section. Only the email attribute is mandatory.</p> <ul><li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">email</code> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">user.email</code></li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">family_name</code> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">user.lastName</code></li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">given_name</code> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">user.firstName</code></li> <li><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">name</code> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">user.displayName</code></li> <li><p><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">group_names</code> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">appuser.jupiterone_groups</code> where <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">jupiterone_groups</code> is optional naming. <br> </p> <p>You must configure the group attribute in the Profile Editor in the <strong>Directory</strong> menu, and then assign it after completing the configuration.<br> </p></li> </ul><p><img src="https://us.v-cdn.net/6035534/uploads/4B4GAFNS13R0/okta-saml-mapping.png" alt="okta-saml-mapping" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>After mapping the attributes, click <strong>Next</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/RTI8E0HIWXH2/okta-saml-next.png" alt="okta-saml-next" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>In the Feedback menu, select <em>I'm an Okta Customer adding an internal app</em>, and click <strong>Finish</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/CNSS6XDX7THR/okta-saml-feedback.png" alt="okta-saml-feedback" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>In the Settings section of the Sign On menu, right-click the <strong>ddd</strong> link and select <strong>Copy Link Address</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/08UUGSKB3SGV/okta-metadata-link.png" alt="okta-metadata-link" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Paste the link into the SAML Metadata Document URL field.</p> <p></p> <p><img src="https://us.v-cdn.net/6035534/uploads/GHCHUA5S5DHQ/okta-metadata-field.png" alt="okta-metadata-field" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Click the floppy disk icon to save your configuration. A green confirmation message displays in the lower-left corner of the screen.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/TZSQNOBUE49I/okta-sso-save.png" alt="okta-sso-save" class="embedImage-img importedEmbed-img"></img><br> <br> </p></li> </ol><h3 data-id="okta-group-attribute-configuration">Okta Group Attribute Configuration</h3> <p>JupiterOne recommends adding a custom group attribute to the JupiterOne profile in your IdP account (such as Okta). You can add the attribute with the Profile Editor for the app. Provide a name for the custom group attribute. such as jupiterone_groups.</p> <p>An example in Okta:</p> <p><img src="https://us.v-cdn.net/6035534/uploads/1TI9LG491JCJ/okta-app-profile-editor.png" alt="okta-app-profile-editor" class="embedImage-img importedEmbed-img"></img></p> <p>You can then use this custom app attribute to assign group memberships to your users based on their IdP group assignments. The actual value for the attribute is typically configured on the groups assigned to the app.</p> <p>An example in Okta:</p> <p><img src="https://us.v-cdn.net/6035534/uploads/OG8Y4ANX78VJ/okta-app-group-assignment.png" alt="okta-app-group-assignment" class="embedImage-img importedEmbed-img"></img></p> <h2 data-id="azure-ad-example">Azure AD Example</h2> <p>An example of an attribute mapping configuration in Azure AD:<br><img src="https://us.v-cdn.net/6035534/uploads/BRNCVR11PAO0/sso-azure-user-attr-claims.png" alt="azure-ad-attribute-mappings" class="embedImage-img importedEmbed-img"></img></p> <p>An example of group assignment in Azure AD:</p> <p><img src="https://us.v-cdn.net/6035534/uploads/WHCG0BVWS1IN/sso-azure-auto-assign-groups.png" alt="azure-ad-app-group-assignment" class="embedImage-img importedEmbed-img"></img></p> <p>By adding the user.assignedroles -> group_names mapping to Azure AD, the app roles assigned to the user are mapped to the groups in JupiterOne that have the same name as the group/role. Read <br><a rel="nofollow" href="https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps">https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps</a><br> for more information on adding app roles and assigning them to users and groups.</p> <p>In Azure AD, go to <a href="https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps>" rel="nofollow">https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps></a>, click JupiterOne, and then click <strong>Manifest</strong>.</p> <p>Add an entry to appRoles that is similar to:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">{ "allowedMemberTypes": [ "User" ], "description": "Administrators", "displayName": "Administrators", "id": "e6421657-3af5-4488-831f-7989175e3e35", "isEnabled": true, "lang": null, "origin": "Application", "value": "Administrators" } </pre> <p>Assigning an app role to a user in Azure AD:</p> <p><img src="https://us.v-cdn.net/6035534/uploads/5R0TRTJ1371B/sso-azure-app-user-and-groups.png" alt="User assigned Azure AD App role" class="embedImage-img importedEmbed-img"></img></p> <h2 data-id="google-workspace-configuration">Google Workspace Configuration</h2> <p>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:</p> <p><img src="https://us.v-cdn.net/6035534/uploads/ILBN32GYQY0L/sso-google-prestep.png" alt="j1-sso-config-initial" class="embedImage-img importedEmbed-img"></img></p> <p>The IdP configuration page on the Google Admin Console is at: <a rel="nofollow" href="https://admin.google.com/ac/apps/unified?hl=en">https://admin.google.com/ac/apps/unified?hl=en</a>.</p> <ol><li>From the <strong>Add App</strong> dropdown menu, select <strong>Add custom SAML app</strong>.<br> </li> </ol><p><img src="https://us.v-cdn.net/6035534/uploads/0I7HKOY9W5GF/sso-google-add-app.png" alt="sso-google-add-app" class="embedImage-img importedEmbed-img"></img></p> <ol start="2"><li><p>In the App name field, enter JupiterOne.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/O5M0OI7HIES4/sso-google-app-details.png" alt="sso-google-app-details" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Click <strong>DOWNLOAD METADATA</strong> to download an XML metadata file to use later.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/T43CJ20E54DD/sso-google-idp-details-metadata.png" alt="sso-google-idp-details-metadata" class="embedImage-img importedEmbed-img"></img><br> </p></li> <li><p>Paste your SSO URL in the ACS URL field.</p></li> <li><p>In the Entity ID field, paste your Audience URI. In the Name ID format field, select <strong>EMAIL</strong>, and select <strong>Primary email</strong> in the Name ID field.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/MVE3FBQLVNOV/sso-google-service-povider.png" alt="sso-google-service-povider" class="embedImage-img importedEmbed-img"></img><br> <br> </p></li> <li><p>When mapping directory attributes, ensure you use the following names in the App attributes fields. group_names is optional.</p> <ul><li><p><em>Primary email</em> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">email</code></p></li> <li><p><em>Last name</em> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">family_name</code></p></li> <li><p><em>First name</em> > <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">given_name</code></p></li> </ul><p><img src="https://us.v-cdn.net/6035534/uploads/6C92MIENOYUD/sso-google-attibute-mapping.png" alt="sso-google-attibute-mapping" class="embedImage-img importedEmbed-img"></img></p></li> <li><p>Paste the downloaded XML metadata file contents into the SAML Metadata File field.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/ZJKVS2C4J4L5/sso-google-poststep.png" alt="sso-google-poststep" class="embedImage-img importedEmbed-img"></img><br> </p></li> </ol><h2 data-id="removing-users">Removing Users</h2> <p>When you unassign or remove a user from the JupiterOne app within your IdP, the user can no longer log in to your JupiterOne account because the authentication is done by your IdP. However, the user memberships remain in the Groups. You can manually remove them from the groups in JupiterOne.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/QFQC0PZF86XT/j1-remove-user.png" alt="remove-user" class="embedImage-img importedEmbed-img"></img></p> <h2 data-id="current-limitations">Current Limitations</h2> <h3 data-id="idp-initiated-sign-on-flow-is-not-supported">IdP-initiated sign-on flow is not supported</h3> <p>J1 uses Amazon Cognito service to manage authentication, including SSO. Cognito currently does <em>not</em> support IdP-initiated sign-on. This means you can <em>not</em> 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:</p> <p>JupiterOne vanity URL:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0"><a href="https://<your_j1_subdomain>.apps.us.jupiterone.io" rel="nofollow">https://<your_j1_subdomain>.apps.us.jupiterone.io</a> </pre> <p>JupiterOne account login URL:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0"><a href="https://login.us.jupiterone.io/account/<your_j1_account_id&gt" rel="nofollow">https://login.us.jupiterone.io/account/<your_j1_account_id&gt</a>; </pre> <p>These URLs redirect to your configured SSO provider for authentication.</p> <p>You can find your J1 account ID by running the following query:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">Find jupiterone_account as a return a.accountId </pre> <p><strong>Workaround</strong></p> <p>If your SSO provider supports configuring a bookmark or secure web authentication (SWA) app, you can work around this limitation by doing the following:</p> <ul><li>Hide the app icon to users for the configured JupiterOne SAML SSO app.</li> <li>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.</li> </ul><h2 data-id="troubleshooting">Troubleshooting</h2> <p>Different SSO providers have varying UIs and nomenclature, therefore, ultimately the SAML response and attribute statement should look similar.</p> <h3 data-id="common-problems"><strong>Common Problems</strong></h3> <p><strong>Infinite Redirect Loop</strong></p> <p>An infinite redirct loop can occur if the SAML subject is incorrect or missing or if the required SAML attribute <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">email</code> (case-sensitive) is not present.</p> <p><strong>SAML Subject</strong></p> <p>A common problem during SSO configuration is an incorrect SAML subject. Here is an example of a correct subject:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0"><saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">john.smith@example.com</saml2:NameID> ... </saml2:Subject> </pre> <p><strong>SAML Attribute Statement</strong></p> <p>Another common problem during SSO configuration is an incorrect SAML attribute statement. An example of a correct attribute statement is:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0"><saml2:AttributeStatement> <saml2:Attribute Name="email"> <saml2:AttributeValue xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema" rel="nofollow">http://www.w3.org/2001/XMLSchema</a>" xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>" xsi:type="xs:anyType">john.smith@example.com</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute Name="family_name"> <saml2:AttributeValue xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema" rel="nofollow">http://www.w3.org/2001/XMLSchema</a>" xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>" xsi:type="xs:anyType">Smith</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute Name="given_name"> <saml2:AttributeValue xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema" rel="nofollow">http://www.w3.org/2001/XMLSchema</a>" xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>" xsi:type="xs:anyType">John</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute Name="group_names"> <saml2:AttributeValue xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema" rel="nofollow">http://www.w3.org/2001/XMLSchema</a>" xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance" rel="nofollow">http://www.w3.org/2001/XMLSchema-instance</a>" xsi:type="xs:anyType">Administrators,Users</saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement> </pre> <p><strong>Viewing the SAML Response</strong></p> <p>To view the SAML response, you can use browser plugins to capture the POST to <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">/saml2/idpresponse</code>. For example, in the Chrome browser the plugin, you can use <a rel="nofollow" href="https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en">SAML-tracer</a> to decode and view the SAML response and, therefore, the SAML attribute statement.</p> <p>The following is an example of what SAML-tracer looks like after logging in by SSO. The <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">SAML</code> tab is active to view the XML. Calls that have SAML are also flagged with a yellow <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">SAML</code> tag on the right of the HTTP request.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/L21GUX3ZCEPG/saml-tracer-example.png" alt="SAML-tracer" class="embedImage-img importedEmbed-img"></img></p> </article> </main>
.png)