---
title: "SSO/SAML Integration"
description: "Configure SSO/SAML integration with Okta, Azure AD, Google, OneLogin, or other identity providers"
url: https://docs.stackhawk.com/platform/sso-saml-integration/
---

# SSO/SAML Integration

> **Note:** *This feature is available on the StackHawk [Scale plan](https://www.stackhawk.com/pricing).*

## SSO Support Through SAML Integration

The StackHawk platform includes a [Service Provider-Initiated sign in flow](https://developer.okta.com/docs/concepts/saml/#understanding-sp-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). Please reach out to StackHawk support for assistance setting up SSO/SAML for your organization.

For setup with your auth provider, support will request three values:

1. The **SSO identifier** - this is your user’s auth domain as part of the login email, eg. `stackhawk.com`
2. The **IDP Entity ID** - This is the unique identifier for SAML login within the service provider.
3. The **SAML IDP Metadata XML** - This is a XML file with the information necessary for StackHawk to interact with SAML-enabled identity service providers.

### User Conversion

StackHawk uses email addresses to uniquely identify users. Many times, early users of your StackHawk organization created their accounts with their work emails through one of our other identity providers (email/password, Google auth, GitHub auth).

If you used your work email to make your account before you integrated SAML SSO with StackHawk, your account will be converted to your company’s SAML IDP the first time you login to StackHawk via SAML SSO.

> **Warning:** Please note, this identity provider conversion is one-way and irreversible. Please reach out to support if you encounter any issues.

You will also be able to see a record of the successful identity provider conversion in your [organization’s audit logs](https://app.stackhawk.com/settings/auditlog).

![Successful SAML SSO conversion audit log](https://docs.stackhawk.com/images/platform/sso-saml/saml-sso-conversion-audit-log.png)

## 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 IDP-specific sections below for detailed provisioning guidance.

### Step 2: Download the XML Metadata

Once provisioned, download the associated [SAML Metadata XML document](https://en.wikipedia.org/wiki/SAML_metadata) for provisioning by StackHawk Support.

## Provisioning the StackHawk Platform

Once the XML Metadata has been generated, [contact StackHawk Support](https://docs.stackhawk.com/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 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)

> **Warning:** Case matters when entering an email address or SSO Identifier—`CompanyName` and `companyname` are not equivalent.

## Provisioning Guidance for Specific IDPs

### Okta

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

1. Add the [StackHawk integration](https://www.okta.com/integrations/stackhawk/#overview) 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`

### Azure Active Directory (AAD)

[Microsoft Entra](https://www.microsoft.com/en-us/security/business/microsoft-entra) is the new name for Azure Active Directory.

The Microsoft Entra equivalent to a SSO Service Provider is an [Enterprise Application](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal).

For the associated Enterprise Application in the [Entra Admin Center](https://entra.microsoft.com/):

1. Create a new Active Directory Enterprise Application if it does not already exist, and select its properties.

2. Select **Single sign-on** (under Manage)

3. Select **SAML**

4. 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

5. Note the **Azure AD Identifier** (which may start with <https://sts.windows.net>); this is the IDP entity ID.

6. 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)

7. 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`)

8. 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

9. Select **users and groups**

10. Add the appropriate users and groups for access to the Enterprise Application

11. Navigate back to Single sign-on and download the **Federation Metadata XML** (under SAML Signing Certificate)

Share with support your Azure domain, the Azure AD Identifier as the IDP Entity ID collected in Step 5, and the Federation Metadata XML as the SAML IDP metadata XML collected in step 10.

### Google

To set up Google for SAML-based SSO login (as opposed to the **Login with Google** flow):

1. Add a custom SAML application in [admin.google.com](https://admin.google.com)

2. Set the following in the **Service Provider Details** section:

   - ACS URL = `https://auth.stackhawk.com/saml/SSO`
   - Entity ID = `com:stackhawk:kaakaww:sp`
   - Name ID = `Basic Information --> Primary email`
   - Name ID format = `Unspecified`

3. In **Attribute Mapping**, create these attribute pairs:

   - Basic Information = `First Name`; App attributes = `firstName`
   - Basic Information = `Last Name`; App attributes = `lastName`

4. Once the application has been created, go to **Apps—>Web and Mobile Apps—>Select the StackHawk SAML application—>Download Metadata**

### OneLogin

OneLogin’s SAML terminology in the **Applications** configuration:

- The SSO URL is referred to as **ACS (Consumer) URL**; for StackHawk, that’s `https://auth.stackhawk.com/saml/SSO`
- Enter `https://auth.stackhawk.com/saml/SSO` in the **Recipient** field as well
- Enter `com:stackhawk:kaakaww:sp` in the **Audience (Entity ID)** field
- Enter `https://auth.stackhawk.com/sso` in the **Login URL** field
- Enter `Service Provider` in the **SAML initiator** field
- Enter `Email` in the **SAML nameID format** field
- Enter `Specific` in the **SAML Issuer Type** field