Setting up SSO with StackHawk simplifies the login process for your users, helps contribute to an enhanced security posture, and ultimately can streamline your access management to the platform.
StackHawk and SSO
StackHawk seamlessly integrates with various SSO/SAML providers, provided they meet standard requirements. When you're ready to integrate, just contact StackHawk Support and share the necessary details about your SSO/SAML integration.
Before anything, you will need to set up StackHawk as a service provider in your SSO / SAML platform. Doing so will allow you to generate the necessary information required to connect them with StackHawk. For more info on provisioning StackHawk as a service provider in your IDP, check out our guide here!
Getting Set Up
The following information is needed by StackHawk to integrate with your SSO / SAML platform. When reaching out to our Support team, please provide them with the following data.
XML Metadata
To integrate StackHawk with your chosen SSO/SAML provider, generate a metadata XML document from the provider. This document includes entity descriptors, signature details, public keys, and more. It enables StackHawk to authenticate and connect with your SSO/SAML provider, ensuring legitimacy and permission for user authentication.
Identity Provider Entity ID
The entity ID serves as a unique identifier, pinpointing a specific entity within the SAML authentication and authorization protocol. (this should also be contained within the metadata XML)
SSO Identifier
When a user attempts to log in via SSO, they will need a Unique Identifier that is already designated within StackHawk to allow us to know who they are and what organization they are a part of. Typically, this is set to your company domain. (Everything past the @ in your email Ie: @stackhawk.com).
When logging in via SSO, users are presented with two options. They can enter their work email address or their organization's Single Sign-On Identifier. If this is set to your company domain, you could log in by entering your email or by placing your domain in the Identifier box.
In cases where you might have users that do not share the same single company domain, you can work with our Support team to create a unique identifier that is specific to your organization and can be used alternatively to your domain name.
Using SSO With StackHawk
Once the SSO/SAML integration is set up and verified, you will no longer need to use the "Invite Users" option from within the user interface to add colleagues to your organization. Auto-Provisioning is supported for users with valid SSO integrations and users will be prevented from logging directly into app.stackhawk.com once set up.
For users that have had an existing login to your StackHawk Organization prior to your configuration of SSO. Their default authentication method will be converted when they first use SSO to log in. This is irreversible, and they will not be able to log in via other authentication methods once converted.
If a user is attempting to log in to your StackHawk organization for the first time via SSO and has a "Stand-Alone" StackHawk account that uses an email address with your SSO Identifier. This will ultimately cause issues when trying to Auto Provision them. Reach out to our Support Team, and they will be happy to help get it corrected!
When new users are added to your account through Auto-Provisioning, they will default to having a Member Role. To have a different permission set, an Admin user will need to adjust those permissions from within the user interface after the account is created.
IDP Integration Details
The following information will be needed to set up StackHawk as a provider in your SSO/SAML environment. To get specific instructions for your SSO provider, check out our guide here!
StackHawk's SAML endpoint URL is https://auth.stackhawk.com/saml/SSO
If the SAML provider requires an audience URI, use
com:stackhawk:kaakaww:spSet email as the primary identifier:
The user name ID format in the identity provider should correspond to the user's email address
Example email identifier:
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
While email is the primary identifier, the first name (SAML:
user.firstNameorfirstName, depending on IDP vendor) and last name (SAML:user.lastNameorlastName, depending on IDP vendor) identifiers should be present as well
Additional Resources
If you have any specific questions regarding the setup of a SAML/SSO integration with StackHawk, please reach out to our Support Team! We would be more than happy to help!
You can contact us by emailing support@stackhawk.com or by chatting in through the chat widget on our website!