Skip to main content

SAML SSO Configuration

How to setup SAML SP Initiated SSO

Alex Montgomery avatar
Written by Alex Montgomery
Updated over a month ago

Overview

GovWorx supports authenticating users via SAML SSO. A few details about the SSO

  • Sign on only - no provisioning - User provisioning via SSO is not supported. The user must exist in the user management area

  • Matching Users - Users are matched via email

  • SP Initiated - We only support service provider initiated SSO flows (SP Initiated).

Configuration Steps

1 - Create new SAML App in Idp

Create a new SAML app in your identity provider (IdP), download the XML Metadata to enter into GovWorx. When configuring the SAML app, use the following details

ACS URL: https://govworx.auth-fips.us-gov-west-1.amazoncognito.com/saml2/idpresponse

Entity ID: urn:amazon:cognito:sp:us-gov-west-1_hh4SObAzC

Relay State: Identity_provider=urn:amazon:cognito:sp:us-gov-west-1_hh4SObAzC&client_id=36l5odfbv61gt6vvc9ojmal13e&redirect_uri=https://app.govworx.net&response_type=code&scope=email+openid+profile

Login URL (Optional): https://app.govworx.net/login/{customerURLpath}

  • This can be found on your Settings > SSO page within CommsCoach

Required Assertions

  • NameID - We match on NameID and it is case sensitive. If you have upper case in your NameID you should be able to add a transform (both Okta and Microsoft Entra supports this)

  • email - Send the email address in an attribute called 'email'

🔧 Steps to Transform Email to Lowercase in Azure SAML SSO

  1. Go to Azure Active Directory > Enterprise Applications.

  2. Select your SAML-based application.

  3. Click on Single sign-on.

  4. Under Attributes & Claims, click Edit.

  5. Configure the claim:

    • Source: Transformation

    • Transformation Type: ToLower

    • Parameter 1: user.mail (or user.userprincipalname, depending on your setup)

  6. Click Save.

🔧 Additional Steps for ADFS SSO

  1. The following urls must be added to the Relying Party Trust's "Endpoint" list in this order:

    1. https://govworx.auth-fips.us-gov-west-1.amazoncognito.com/saml2/idpresponse?RelayState=Identity_provider%3Durn%3Aamazon%3Acognito%3Asp%3Aus-gov-west-1_hh4SObAzC%26client_id%3D36l5odfbv61gt6vvc9ojmal13e%26redirect_uri%3Dhttps%3A%2F%2Fapp.govworx.net%26response_type%3Dcode%26scope%3Demail%2Bopenid%2Bprofile

    2. https://govworx.auth-fips.us-gov-west-1.amazoncognito.com/saml2/idpresponse

  2. On the Relying Party Trust access "Edit Claim Issuance Policy...". Add the following rule to transform the NameID claim to lower case:

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(RegExReplace(c.Value, "A", "a"), "B", "b"), "C", "c"), "D", "d"), "E", "e"), "F", "f"), "G", "g"), "H", "h"), "I", "i"), "J", "j"), "K", "k"), "L", "l"), "M", "m"), "N", "n"), "O", "o"), "P", "p"), "Q", "q"), "R", "r"), "S", "s"), "T", "t"), "U", "u"), "V", "v"), "W", "w"), "X", "x"), "Y", "y"), "Z", "z"));

🔧 Additional Steps for DUO SSO

  1. You must configure DUO to Transform the Attribute being sent to CommsCoach

    1. Navigate to Attribute Transformations

    2. Select "Enable User Attribute Transformations"

    3. enter the following into the Transformation Rules* dialog box

      1. use "<Email Address>" make_lowercase

    4. Enable "Set this as my NameID attribute

    5. Save

2 - Upload to GovWorx

Open Settings -> Security -> SSO and enter the following

Email Domain: Enter the email address domain of your organization

SAML Metadata: Open the metadata file download (or copy the XML) from you Identity provider and enter it into the text box

3 - Complete Agency Info

The final box shows you the URL where you can initiate the SSO. It will be

https://app.govworx.net/{agencyUrlPath}/login

You will need to set your Agency URL Path and logo in the 'Agency Info' tab

4 - Test Login

When you browse to that path, you should see your agency logo + a button to Start SSO. That should kickoff the SAML flow with your IdP and log you into GovWorx!

Did this answer your question?