Overview

RiskTool supports Secure Assertion Markup Language (SAML), allowing users to authenticate against your corporate identity provider. For the purposes of this document we will refer to both systems as "RiskTool" throughout unless specifically mentioned (such as areas with sample code, etc.).


Prerequisites

SAML Server

  • Setup a SAML server in­-house such as OpenAM or Active Directory Federated Services.
  • Utilize a SAML service such as Okta, OneLogin, or PingIdentity.


Getting Started

  1. Login to RiskTool
Warning: Do not use users managed either through Single Sign-On or Active Directory as the user/API token pair - you must use a User managed solely through the RiskTool UI to avoid overwrites
  1. Browse to Administration > Settings
  2. Click Edit Settings 

  3. Enter a Custom URL Identifier and click Update. You should now see that your Custom URL has the identifier you entered. If you have a Custom URL already set up, click "cancel" to take you back to previous screen. 
    Warning: Your Custom URL Identifier customizes the URL for your system. This is a prerequisite for integration, allowing your users to have unique usernames. Once an identifier has been chosen, it can be modified but not removed
  4. Click SSO Configuration in the blue bar at the top 
  5. Click Edit SSO Configuration
  6. Review SSO Configuration Form 


    1. Download Service Provider Metadata -­ A Service Provider metadata file to download and/or monitor if your SAML setup supports this feature.
    2. Download SSO Setup Guide ­ 
    3. SSO bypass login URL ­ This URL is available for user accounts that are not setup for SSO. It is advised to keep one Administrator user account disconnected from SSO, allowing access if the identity provider is not functioning.
    4. Enabled -­ When set to Yes, users will be redirected to your identity provider when accessing RiskTool.
    5. SAML SSO URL - ­This is the URL we invoke to redirect users to your identity provider. ie) https://www.yourserver.com/adfs/ls/
    6. Certificate Fingerprint ­- The SHA1 fingerprint of the SAML certificate. Obtain this from your identity provider.
    7. Remote logout URL - Optional -­ This is the URL that we will return your users to after they log out. ie) https://www.yourserver.com/adfs/ls/?wa­wsignout1.0
    8. Create Users On­Demand ­- This option will create user accounts when a user first accesses the system.
    9. On­Demand User Role - ­Users created On­Demand will be associated to the selected user role.
    10. Last SSO Error Logged ­- Shows the last error RiskTool reported in relationship to SSO request/response handling. This should be checked when troubleshooting any issues.
  8. Setup SAML server using data provided in the Service Provider Metadata.

    1. NameID format ­ urn:oasis:names:tc:SAML:2.0:nameid­format:persistent
    2. Attributes Supported

      1. surname
      2. givenname
      3. emailaddress
  10. Enter SSO Configuration Information, set enabled to Yes and click Save.
  11. Test SSO

    1. Click Logout at the top of the page.
    2. You will be redirected to your identity provider.
    3. Enter credentials if prompted
    4. You will be logged into RiskTool
  13. Troubleshooting

    1. Redirection to identity provider resulted in error

      1. Confirm that the correct SAML SSO URL is setup
      2. Review Sample Request below to verify your SAML server is configured properly.
    3. Error after entering credentials

      1. Login to RiskTool and see if an error message is logged in the SSO Configuration
      2. Review Sample Response below, RiskTool is expecting response in this format.
    5. Below are examples of a RiskTool Sample Request and Response:  

RiskTool Sample Request 

<samlp:AuthnRequest AssertionConsumerServiceURL="https://customer.cyberrisktool.com/portal/saml_response"
                    Destination="https://www.id_server.com/adfs/ls/" ForceAuthn="true"
                    ID="_da27d0bb­85a9­4b2f­8e8d­4435a47fa3ed" IsPassive="false" IssueInstant="2013­08­06T15:03:53.296Z"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP­POST" Version="2<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>.0"
                    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <samlp:Issuer xmlns:samlp="urn:oasis:names:tc:SAML:2.0:assertion">https://customer.cyberrisktool.com/portal
    </samlp:Issuer>
    <saml2p:RequestedAuthnContext Comparison="minimum" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
        <saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
        </saml2:AuthnContextClassRef>
    </saml2p:RequestedAuthnContext>
</samlp:AuthnRequest>

  
RiskTool Sample Response

  

<samlp:Response ID="_8adadda3­0009­416c­81c8­c2891b5963d9" Version="2.0" IssueInstant="2013­08­06T14:56:12.541Z"
                Destination="https://customer.cyberrisktool.com/portal/saml_response"
                Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
                InResponseTo="_7f22bbd0­803e­4c4f­9d23­2193bd6b60c1" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://www.id_server.com/adfs/services/trust</Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <Assertion ID="_57a09b9a­1851­4601­b510­42dbf92e7967" IssueInstant="2013­08­06T14:56:12.541Z" Version="2.0"
               xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
        <Issuer>https://www.id_server.com/adfs/services/trust</Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml­exc­c14n#"/>
                <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig­more#rsa­sha256"/>
                <ds:Reference URI="#_57a09b9a­1851­4601­b510­42dbf92e7967">
                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped­signature"/>
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml­exc­c14n#"/>
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                    <ds:DigestValue>yqUBweA7bevbBXkAq3oLn+...</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>
                g4h5ggrV0F1QjZ8a1jQhutqq02...
            </ds:SignatureValue>
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>
                        MIIC8DCCAdigAwIBAgIQVUvdLFB...
                    </ds:X509Certificate>
                </ds:X509Data>
            </KeyInfo>
        </ds:Signature>
        <Subject>
            <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid­format:persistent">jsmith</NameID>
            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <SubjectConfirmationData InResponseTo="_7f22bbd0­803e­4c4f­9d23­2193bd6b60c1"
                                         NotOnOrAfter="2013­08­06T15:01:12.541Z"
                                         Recipient="https://customer.riskutilities.com/portal/saml_response"/>
            </SubjectConfirmation>
        </Subject>
        <Conditions NotBefore="2013­08­06T14:56:12.541Z" NotOnOrAfter="2013­08­06T15:56:12.541Z">
            <AudienceRestriction>
                <Audience>https://customer.cyberrisktool.com/portal</Audience>
            </AudienceRestriction>
        </Conditions>
        <AttributeStatement>
            <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
                <AttributeValue>Smith</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
                <AttributeValue>John</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
                <AttributeValue>[email protected]</AttributeValue>
            </Attribute>
        </AttributeStatement>
        <AuthnStatement AuthnInstant="2013­08­06T14:56:12.463Z" SessionIndex="_57a09b9a­1851­4601­b510­42dbf92e7967">
            <AuthnContext>
                <AuthnContextClassRef>urn:federation:authentication:windows</AuthnContextClassRef>
            </AuthnContext>
        </AuthnStatement>
    </Assertion>
</samlp:Response>