Login Create an Account Login Create an Account
 

SSO/SAML Integration

This feature is available on the StackHawk Enterprise plan.

SSO support through SAML integration

The StackHawk platform includes a Service Provider-Initiated sign in flow that provides your users with Single Sign On (SSO) access to the StackHawk platform.

In some cases, IDP-initiated flows may be available as well (e.g., through the Okta integration).

Preparing the Identity Provider (IDP) environment

Step 1: Provision StackHawk as a Service Provider (SP)

To start the SAML integration process, configure StackHawk as an SP in your IDP.

To do so, you’ll need the following StackHawk Entity information:

  1. StackHawk’s Audience URI (aka, SP Entity ID): com:stackhawk:kaakaww:sp
  2. StackHawk’s SAML endpoint URL (aka, Assertion Consumer Service, aka ACS URL): https://auth.stackhawk.com/saml/SSO

You’ll also need the following attributes:

  1. Primary identifier: the primary identifier must be email address in order to integrate with StackHawk
    1. email identifier varies by provider (user.mail, EmailAddress, etc)
  2. First Name and Last Name identifiers – these are attribute mappings that need to be added in order to map your IDP’s first and last name source attributes to StackHawk’s firstName and lastName identifiers

Note: See the appropriate IDP-specific sections below for specific provisioning guidance.

Step 2: Download the XML Metadata

Once provisioned, download the associated SAML Metadata XML document for provisioning by StackHawk Support.

Provisioning the StackHawk Platform

Once the XML Metadata has been generated, contact StackHawk Support for additional assistance.

Support will work with you to provision the StackHawk platform with:

  1. the XML Metadata for the account(s) in question
  2. an SSO Identifier for users to enter to initiate the login from the StackHawk platform at https://auth.stackhawk.com/sso
    • typically, this will be your organization’s email domain (e.g., companyname.com); however, you can work with support to customize this, provided it’s a unique identifier

Once SAML integration is in place:

  • IDP users may need to be granted access to the SP in the IDP before they can log in
  • new SAML users may log directly into https://auth.stackhawk.com/sso – they will be auto-provisioned on the the StackHawk platform for the provisioned account
  • you should no longer utilize the Invite Members feature in the Settings page (this function is not integrated with SAML)

Note:

  • Case matters when entering an email address or SSO Identifier – CompanyName and companyname are not equivalent

Provisioning Guidance For Specific IDP’s

Okta

StackHawk has a pre-built integration with Okta. To enable it:

  1. Add the StackHawk integration directly via the Okta site
  2. From the resulting application in Okta, download the Identity Provider metadata from the Sign-On settings page

Duo

First/Last Name attribute mappings (StackHawk:Duo):

  • firstName = firstName
  • lastName = lastName

Google

Google’s SAML terminology in the Service provider details setup page:

  • The SP’s SSO URL is referred to as ACS URL; either way, for StackHawk, that’s https://auth.stackhawk.com/saml/SSO
  • Entity ID refers to the SP Entity ID, which for StackHawk is com:stackhawk:kaakaww:sp
  • Start URL is not needed
  • Google Directory attributes mapping (Google:StackHawk):
    • First name (Google Directory Attributes) = firstName (App attributes)
    • Last name (Google Directory Attributes) = lastName (App attributes)

Azure Active Directory (AAD)

SP Provisioning Process for Azure:

AAD’s equivalent to an SP is an Enterprise Application.

For the associated Enterprise Application in the Azure Active Directory Admin Center :

  1. Select Single sign-on (under Manage)
  2. Select SAML
  3. Under Basic SAML Configuration:
    1. add com:stackhawk:kaakaww:sp as the Identifier (Entity ID) – this is StackHawk’s Audience URI
    2. set https://auth.stackhawk.com/saml/SSO as the Reply URL (Assertion Consumer Service URL)
    3. Leave Sign on URL blank
  4. Note the defaulted values in Attributes & Claims
    1. there will likely already be givenname and surname entries – we’ll need to add new first name / last name entries regardless
    2. note the Unique User Identifier (required claim)
  5. Edit the Required Claim (Unique User Identifier (Name ID)) under Attributes & Claims:
    1. change the Source attribute to user.mail if it’s any other value (likely default: user.userprincipalname, or possibly samAccountId)
  6. Add two Additional claims:
    1. Claim 1: Name: firstName; Source Attribute: user.givenname
    2. Claim 2: Name: lastName; Source Attribute: user.surname
    3. Leave pre-existing surname / givenname attribute mappings in place (e.g., those associated with schemas.xmlsoap.org) – you may need these elsewhere but StackHawk needs the two above
  7. Select users and groups
  8. Add the appropriate users and groups for access to the Enterprise Application
  9. Navigate back to Single sign-on and download the Federation Metadata XML (under SAML Signing Certificate)