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).
For Azure, see here.
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 'Configure' Under your Settings > SSO settings on SecurityScorecard Platform.
The SAML Configuration can be done in 2 ways either by uploading the XML file or by manual configuration
Type 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.
- Additional information on Example of SAML IdP Metadata xml file , Okta Knowledge Base article
- 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.
Type 2. Manual Configuration
You may fill those up on the 'SAML Configuration' wizard by clicking on 'Configure your settings manually'.
Steps as outlined below.
- Fill in he IdP Single Sign-On URL and the IdP Issue URI are provided by your IdP.
-
Note: 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
-
Note: Example with OKTA as IdP:
- Select the required 'Request Binding', the 'http redirct' or 'http post' 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
- Check in 'Sign Auth Requests' to select the Request Signature Algorithm options - SHA-256 or SHA-1
- In case of doubt, Please consult your IdentityProvider administrator to retrieve this information.
- In case of doubt, Please consult your IdentityProvider administrator to retrieve this information.
- 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.
- 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 next step to test the SAML login. The page returns to SSO settings on SecurityScorecard Platform. In order to finally enable SAML on a successful login test is required under 'Status'
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>