SAML 2.0 - Integrating SAST with Keycloak

Mend SAST supports SAML 2.0 integration for your organization. This note shows step-by-step how to implement this if your SAML 2.0 Identity Provider (IdP) is Keycloak.

1. If you don't have a Keycloak server and want to practice, do the following (otherwise, skip to step 2):

   1. Create an Amazon Linux 2 EC2 instance and assign an Elastic IP to it.

   2. Follow instructions here to install Docker in the EC2 instance: look at the "Installing Docker on Amazon Linux 2" section of https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-container-image.html

   3. To create a Keycloak instance, run the following:

      CODE

      docker run -d -p 80:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin --name keycloak http://quay.io/keycloak/keycloak:17.0.1   start-dev

      1. NOTE: this command maps to port 80 because as of this writing, the SAST’s UI won’t accept an “IdP metadata URL” field value with a port in the URL. Case 92565 has been opened about this.

   4. Keycloak requires TLS connections by default. To turn off this HTTPS requirement, run the following (this does so for the default “master” realm; you’ll do this for the realm you create later):

      CODE

      docker exec -it keycloak bash
      cd /opt/keycloak/bin/
      ./kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin
      ./kcadm.sh update realms/master -s sslRequired=NONE

   5. Log in to the Keycloak Admin Console by going to http://<elastic-ip-address> and clicking on Administration Console (use “admin”/”admin” as name/password; you supplied these values in step c):

      

   6. It’s highly recommended that you change the admin password now by choosing “Manage Account” from your avatar menu in the upper-right corner, then clicking on the “Signing In” link on the next page.

   7. Create a “realm” for the SAST integration by doing the following:

      1. On the admin console, hover over the word "Master" in the upper-left corner (i.e. the realm menu), and click on the "Add Realm" button that comes up:

         

      2. Type "WS-SAST" (or whatever name you like) and click Create

   8. Now, to turn off the HTTPS requirement for this new realm, do all the sub-steps under step d above, but replacing the last step with:

      CODE

      ./kcadm.sh update realms/WS-SAST -s sslRequired=NONE

   9. Create at least one test user by doing the following:

      1. Click on "Users" on the left-hand menu

      2. Click the "Add User" button

      3. Set Username to an email address, fill out name, email, and any other field you need, and click Save

2. Log in to the Keycloak Admin Console as an administrator, if you haven’t already (either a real one or the practice one you created above):

   

3. If you're not already there, switch to the right realm (e.g. WS-SAST) by clicking on the Realms drop-down above the left-hand menu:

   

4. Click on Clients in the left hand menu, then click the “Create” button on the right to create a new client (i.e. a new SSO application):

   

5. On the General Settings tab:

   1. For Client type, choose SAML

   2. For the client ID:
      - WhiteSource: https://<your-instance>.whitesourcesoftware.com/sast/saml/metadata
      - Mend: https://<your-instance>.mend.io/sast/saml/metadata

Note: The client ID field must end with “/sast/saml/metadata“

6. Click “Next”

7. On the Login Settings tab:
   a. Set "Root URL" to:
   - WhiteSource: https://<your-instance>.whitesourcesoftware.com/sast
   - Mend: https://<your-instance>.mend.io/sast

Note: The Root URL must end with “/sast”.

b. Set “Home URL” to “/”

c. Set "Valid Redirect URIs" to "/*"

d. Set "Master SAML Processing URL" to "/saml/acs"

8. Click “Save”

9. On the Mappers tab:
   a. Click Create:

   

10. On the resulting page:

    1. For name, type something like "Map username to email address"

    2. For Mapper Type, choose User Property

    3. For Property, type "email"

    4. For SAML Attribute Name, type "username"

    5. Click Save

       

11. Be sure to click Save again at the bottom of the Mappers tab. If you don’t do this, your changes in steps 7 and 8 above won’t be saved.

12. Now, you need to get the “Entity ID” and “IdP Metadata URL” from this realm of Keycloak, to supply it to the Mend UI SAML section in the next section. Click on the “Realm Settings” entry in the left side menu. You will be doing a couple of things with the “SAML 2.0 Identity Provider Metadata” hyperlink on the bottom of this page (for later use in the Mend side of the setup):

    

    1. Left click on the “SAML 2.0 Identity Provider Metadata” link, and save (in your favorite text editor) the value of the “entityID” field in the XML document that comes up:

       

    2. Now, RIGHT-click on the same “SAML 2.0 Identity Provider Metadata” link, and choose “Copy Link” (“Copy Link Address” in Chrome) in the menu that comes up. Then paste this link in your favorite text editor and save it.

Next, switch to the Mend SAST UI. Take the following steps:

1. Log into Mend SAST as an administrator and select the org in the upper-right corner that you're going to configure for single sign-on:

   

2. Now select the "Administration" option on the left hand side, and check the "Enable SAML Authentication" box:

   

3.  Fill out the following fields:

   1. For "Entity ID", supply the "entityID" value that you saved in step 9a above.

   2. For "Domain", put the email domain for the users that will log into Mend SAST via Keycloak; e.g. "http://megacorp.com "

   3. For "IdP Metadata URL", copy the URL you saved in step 9b above.

   4. For "Root URL", simply put the root URL of the Mend SAST app (most likely "https://saas.whitesourcesoftware.com/sast " or "https://saas.mend.io/sast ")

Note: The Root URL must end with “/sast”.

e. For "Username Attribute" field, type "username".  (This is the value you entered under the Mappings tab in our Keycloak setup above.)

f. Choose an appropriate role for those users who don't have a group assigned by the SAML mapping.

g. Mapping of SSO users to Mend SAST® roles can be done in the Role Mapping section using attributes. If no role mapping is configured or matched, the configured Default Role will be assigned to logged in users.

h. Mapping of SSO users to Mend SAST® groups can be done in the Group Mapping section using attributes. If no group mapping is configured or matched, the default "SSO Users" group will be assigned to logged in users.

i. Mapping of SSO users to Mend SAST® Organizations can be done in the Organization Mapping section using attributes. If no group mapping is configured or matched, the org level at which you clicked “Enable SAML Authentication” will be assigned to logged in users.

Now, to test the integration, you can do the following:

1. Go to the sign-on page for the appropriate Mend SAST presence.

   

2. Type your email address in the Username field, leave the Password field blank, and click the “SSO LOG IN” button. You should be logged into Mend SAST, after perhaps needing to authenticate if you haven’t yet. Note that you should only be given the privileges to see scans, applications, and other items for the SAST organization to which the SAML settings have been applied. E.g. if OrgB is a child of OrgA, and you checked “Enable SAML Authentication” when you had OrgB selected, then you should only be able to see scans etc. within OrgB.