How to configure SAML SSO in SecurityScorecard Platform

In this article:

How does it work

SAML Single-Sign-On flow is as follows:

1. The user attempts to access the SecurityScorecard Platform by entering its email in the login page.
2. SecurityScorecard Platform redirects the user to the Identity Provider (IdP) for authentication.
3. The user logs in to the IdP using their credentials.
4. The IdP verifies the user's credentials and generates a SAML assertion.
5. The IdP redirects the user to SecurityScorecard Platform, passing the SAML assertion, along with a request for access to the SecurityScorecard Platform.
6. The SecurityScorecard Platform extracts the relevant information from the SAML assertion and uses that information to grant the user access to SecurityScorecard Platform.

Pre-requisites

- Your IdentityProvider Administrator, for the configuration of any IdentityProvider settings.

- Administrator User on SecurityScorecard Platform, for the configuration of SecurityScorecard Platform.

- A user on SecurityScorecard Platform, for testing purposes.

Accessing SecurityScorecard Platform SAML configuration

1. Login using the SecurityScorecard Administrator user:

https://platform.securityscorecard.io/

2. Go to "My Settings" accessible click on the profile icon on the top right hand corner of the page.

https://platform.securityscorecard.io/#/my-settings/my-profile

3. On the bottom left hand corner, Click on "Single Sign-On (SSO)".

https://platform.securityscorecard.io/#/my-settings/sso

This page displays the initial information relative to the SAML Service Provider (SP).

METADATA URL (also known as SP metadata xml):
This URL links to a .xml document containing the SPSSODescriptor of SecurityScorecard Platform. This describes the Service Provider. It also include information about the SAML endpoints, bindings, and certificates that are used by the SecurityScorecard Platform.
https://platform-api.securityscorecard.io/v1/saml/metadata/service-provider

Depending of the Identify Provider used, it may be necessary to save this .xml document and upload it in the IdP during its configuration. Contact your IdP administrator for confirmation.

ASSERTION CONSUMER SERVICE (also known as ACS, Single sign-on URL, SAML Post URL location):

This endpoint receives and processes SAML assertions from the identity provider (IdP) via HTTP-POST requests. The ACS is responsible for extracting the relevant information from the SAML assertion, such as the user's attributes or the authentication event, and using that information to grant the user access to the protected resource.
https://platform-api.securityscorecard.io/v1/saml/responses

ENTITY ID (also known as Audience URI, SP Entity ID):

The SAML entity ID is a URL, used as unique identifier to identify the entity in SAML messages and metadata.
https://platform-api.securityscorecard.io/saml2/service-provider

Known limitations

SAML 2.0 is supported.
SHA-1 and SHA-256 are supported.
Request signature is optional.
HTTP-POST binding is supported.
Response signature is required.
Request and response encryptions are not supported.
Using Multiple Identity Providers is not supported.
Mixed authentication methods (Username/Password and SAML) are not supported.
Only 1 SAML configuration can be active, only 1 Identity Provider can be configured.
Customising the Attributes used for matching and their order is not supported.
We recommend enabling 2FA in the IdentityProvider rather than in SecurityScorecard Platform when SAML is enabled.
SAML single logout (SLO) is not supported.

Configuring the SP details into the IdentityProvider (AzureAD, ADFS, OneLogin, Okta etc.)

Providing the details above, please consult your IdentityProvider administrator for importing the SecurityScorecard Platform ServiceProvider configuration into your Identity Provider (IdP). 

SecurityScorecard Platform identifies users using their email (here: myemailonsecurityscorecard@mycompany.com) . As such, the IdP must provide a SAML assertion for that value. SecurityScorecard Platform decrypts the SAML assertion and looks for that value in the following immutable order:

1. NameID, example:

<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
SPNameQualifier="https://platform-api.securityscorecard.io/saml2/service-provider">
myemailonsecurityscorecard@mycompany.com
</saml:NameID>

if not present or in a NameIDFormat other than emailAddress, it fallbacks looking for

2. email, as an attribute, example:

<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue>myemailonsecurityscorecard@mycompany.com</saml:AttributeValue>
</saml:Attribute>

if not present, it falls back looking for

3. mail, as an attribute, example:

<saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue>myemailonsecurityscorecard@mycompany.com</saml:AttributeValue>
</saml:Attribute>

if not present, it falls back looking for

4. username, as an attribute, example:

<saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue>myemailonsecurityscorecard@mycompany.com</saml:AttributeValue>
</saml:Attribute>

if not present, the login will be denied and fails. See https://support.securityscorecard.com/hc/en-us/articles/7683216098843--User-not-found-error-appears-when-you-test-the-SAML-login

ADFS Outgoing Claim Type: It doesn’t need to be values from the dropdown. “Select or Type to add more”, you may need to in those NameID, email, mail, username.

Note: The user may use any other identifier to log in to the IdP, as long as the its identity is for the email in SecurityScorecard platform. For example: a user may enter myemailonsecurityscorecard@mycompany.com in SecurityScorecard platform on the login page. The user is then redirected to its IdP page, where the IdP credentials may be for username A43876-EMEA-BU4. The IdP must provide a SAML response with an Assertion that contains myemailonsecurityscorecard@mycompany.com in one of the 4 fields mentioned above. The screenshot above indicates "E-Mail Address" as LDAP Attribute, but this is just an example, please check with you AD administrator where myemailonsecurityscorecard@mycompany.com is actually stored.

Configuring your IdP details into SecurityScorecard Platform

Click on Start Configuration Wizard on SecurityScorecard Platform.
https://platform.securityscorecard.io/#/my-settings/sso

The SAML Configuration Wizard opens. It is divided in 4 steps:

1. Upload the SAML IdP Metadata file in xml format. This file is IdP specific, generated and provided by the IdP. Please consult your IdentityProvider administrator to retrieve this information.
Example of SAML IdP Metadata xml file , Okta Knowledge Base article

2. The Idp Single Sign-On URL and the IdP Issue URI are provided by your IdP.

If it is included in the IdP metadata xml provided in step 1 earlier, those will be automatically filled in. In case of doubt, please consult your IdentityProvider administrator to retrieve this information.

Example with OKTA as IdP:
Idp Single Sign-On URL: https://dev-2143763.okta.com/app/dev-21050dsijdks_securityscorecard1_1/exk4rbsnj2RamfbtN5d7/sso/saml
IdP Issue URI: http://www.okta.com/exk4rbsnj2RamfbtN5d7

3. Select the Request Binding, Signing and Signature Algorithm that your IdP supports.

If it is included in the IdP metadata xml provided in step 1 earlier, those will be automatically filled in. You can also find this info directly in the IdP metadata xml , in the <SingleSignOnService Binding="[...]> tag in <IDPSSODescriptor>. 

Request Binding: HTTP Redirect or HTTP POST

Request Signing: Sign Auth Requests

Request Signature Algorithm: SHA-256 or SHA-1

In case of doubt, Please consult your IdentityProvider administrator to retrieve this information.

4. Upload the Certificate used by your IdP to sign Responses. 

There could be multiple certificates. If it is included in the IdP metadata xml provided in step 1 earlier, those will be automatically filled in. The screenshot below is taken after uploading an OKTA IdP metadata xml containing the certificate. PEM base64 encoded x509 certificate file and DER binary files are accepted. 

In case of doubt, please consult your IdentityProvider administrator to retrieve this information.

Click on "Submit" to save the configuration.

Enabling SAML on SecurityScorecard Platform

After configuration is done in both IdP and SecurityScorecard Platform, you may proceed with step 3. In order to finally enable SAML on a successful login test is required.

Once successful, you can enable SAML on your SecurityScorecard Account for all users.

Bypass or per-user SAML exception

It is possible to exempt some users from the SAML authentication. To avoid or reduce the downtime if SAML authentication is failing, you may allow admins or specific users to bypass the SAML requirement. Administrators can configure it in the SAML configuration page. Changes are applied instantly.

Troubleshooting

For troubleshooting, please submit a Support case providing the SecurityScorecard Platform email, the timestamp (with timezone) and screenshot of the issue encountered, as well as the SAMLResponse (can be gathered using SAML-tracer Chrome extension for example). 
This 3rd party tool may also help while troubleshooting: https://www.samltool.com/

Example of SAMLResponse

In the example below, NameID Format is unspecified, so it is skipped, never mind its value.
Attribute Name "email" is passed by the IdP, so it is used by SecurityScorecard Platform.
Additionally, "name" and "username" are provided by the IdP but not used as per priority order defined in the Configuring the SP details into the IdentityProvider section of this article.

[.....REDACTED....]
<ns2:Status>
<ns2:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</ns2:Status>
[.....REDACTED....]
<ns2:Assertion xmlns:ns2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_63cbcdb47350c81c8014feb91deb7327d799" IssueInstant="2022-08-26T18:42:41Z" Version="2.0">
<ns2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://idp.example.com/</ns2:Issuer>
[.....REDACTED....]
<ns2:Subject>
<ns2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">A43876-EMEA-BU4</ns2:NameID>
<ns2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<ns2:SubjectConfirmationData InResponseTo="_6ba2042ca76a817b16de" NotOnOrAfter="2022-08-26T18:44:41Z" Recipient="https://platform-api.securityscorecard.io/v1/saml/responses"/>
</ns2:SubjectConfirmation>
</ns2:Subject>
<ns2:Conditions NotBefore="2022-08-26T18:41:41Z" NotOnOrAfter="2022-08-26T18:44:41Z">
<ns2:OneTimeUse/>
<ns2:AudienceRestriction>
<ns2:Audience>https://platform-api.securityscorecard.io/saml2/service-provider</ns2:Audience>
</ns2:AudienceRestriction>
</ns2:Conditions>
<ns2:AuthnStatement AuthnInstant="2022-08-26T17:07:37Z" SessionIndex="Y7ybY7Wlb78dkDEEnwLKu0HGAJ" SessionNotOnOrAfter="2022-08-26T18:44:41Z">
<ns2:AuthnContext>
<ns2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ns2:AuthnContextClassRef>
</ns2:AuthnContext>
</ns2:AuthnStatement>
<ns2:AttributeStatement>
<ns2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<ns2:AttributeValue>myemailonsecurityscorecard@mycompany.com</ns2:AttributeValue>
</ns2:Attribute>
<ns2:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<ns2:AttributeValue>myemailonsecurityscorecard@mycompany.com</ns2:AttributeValue>
</ns2:Attribute>
<ns2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<ns2:AttributeValue>myemailonsecurityscorecard@mycompany.com</ns2:AttributeValue>
</ns2:Attribute>
</ns2:AttributeStatement>
</ns2:Assertion>