Skip to main content

Configuring SAML Integration

To add a new external SAML v2.0 provider, perform the following:

Click on SAML v2.0

Select_SAML.png

The Add identity provider configuration window opens.

Configuring a new SAML Server

Note

Mandatory fields are marked with red_asterix.png

App Settings

This configuration section refers to the IAM (Broker) side.

Below are all the configuration options that exist in this section.

Parameter

Description

Default

Notes

Redirect URI

Client redirect URI

IDP Initiated flow URI

Used when log in process is expected to start from the IDP side

Alias

The alias that uniquely identifies the identity provider. It is also used to build the redirect URI

Display Name

The name that will be presented in the identity provider’s table

Enabled

On

Store Tokens

Determine if to save the token in Checkmarx One DB in an encoded format, after the users' authentication

Off

Stored Tokens Readable

Determine if to save the token in Checkmarx One DB in a Decoded format, after the users' authentication

Off

Trust Email

Off

  • On: The provided email is not verified even if verification is enabled for the relm.

  • Off: The provided email is verified.

Account Linking Only

Off

  • On: Users cannot log in through this provider, they can only link to this provider. This is useful if you don't want to allow login from the provider but want to integrate with the provider.

  • Off: Users can log in through this provider.

Hide on Login Page

Determine if to hide the external provider icon in the Checkmarx One log in page

Off

GUI order

Set the external providers icons order in the Checkmarx One log in page

  • 1 is the highest value.

  • This is useful when using several external providers.

First Login Flow

Alias of the authentication flow, which is triggered after the first login with this IDP.

First broker login

Post Login Flow

Alias of the authentication flow, which is triggered after each login with this IDP

Useful for additional verification of each user authenticated with this IDP

Sync Mode

Default sync mode for all mappers.

Determines when user data will be synced using the mappers.

  • legacy - Keep the behavior before this option was introduced.

  • import - Import the user only once during the first login with this IDP.

  • force - Always update the user during every login with this IDP.

SAML Settings

This configuration section refers to the external provider side (not the client).

Below are all the configuration options that exist in this section.

Parameter

Description

Default

Notes

Single Sign-On Service URL

The URL that is used for SAML SSO log in authentication requests

Single Logout Service URL

The URL that is used for external provider log out authentication requests

For a user to log out from the external provider (When performing log out from Checkmarx One), you need to perform the following:

  • Single Logout Service URL needs to be filled with the log out URL address.

  • Backchannel Logout option needs to be enabled.

Backchannel Logout

In case this option is enabled, it supports logging out from the identity provider when logging out from Checkmarx One

Off

NameID Policy Format

Specifies the URI reference corresponding to a name identifier format, or in other words, how to send the details in the SAML XML assertion format

Persistent

Optional Values: Persistent, Email, Kerberos, X.509 Subject Name, Windows Domain Qualified Name, Unspecified

Principal Type

Specifies which part of the SAML assertion XML will be used to identify and track external user identities

Subject NameID

  • Optional Values: Subject NameID, Attribute [Name], Attribute [Friendly Name]

  • If Attribute [Name] / Attribute [Friendly Name] is selected, an additional Principal Attribute field will be added.

HTTP-POST Binding Response

Indicates how the external provider returns the information to the client

Off

  • On: Use POST for Binding Response.

  • Off: HTTP-Redirect Binding will be used (GET)

HTTP-POST Binding for AuthnRequest

Indicates which SAML binding should be used when the client requests authentication from the external provider

Off

  • On: Use POST for Binding Response.

  • Off: Redirect Binding will be used (GET)

HTTP-POST Binding Logout

Indicates which SAML binding should be used for logging out from the external provider

Off

  • On: Use POST for Binding Response.

  • Off: HTTP-Redirect Binding will be used (GET).

  • If value is On, the system will use the Single Logout Service URL value for logging out.

Want AuthnRequests Signed

Indicates whether the identity provider expects a signed AuthnRequest

Off

In case this value is On, 2 additional fields will be added:

  • Signature Algorithm: Which signature algorithm to use for signing documents. Optional values are: RSA_SHA256 (Default), RSA_SHA1, RSA_SHA512, DSA_SHA1

  • SAML Signature Key Name: Signed SAML documents contain identification of signing key in the KeyName element. Optional values are: Empty value (Default), None, KEY_ID, CERT_SUBJET

Want Assertions Signed

Indicates whether this service provider expects a signed Assertion

Off

Want Assertions Encrypted

Indicates whether this service provider expects an encrypted Assertion

Off

Force Authentication

Indicates if to force the user’s authentication, even if the user is already logged in to the external provider

Off

Validate Signature

Enable/disable signature validation of SAML responses

Off

If this value is On, an additional Validating X509 Certificates field will be added. This is an indication of the certificate in PEM format that must be used for checking signatures.

Multiple certificates can be entered, separated by a comma.

Allowed clock skew

Clock skew in seconds that is tolerated when validating identity provider tokens

zero

Import from URL

Import metadata from a remote identity provider SAML entity descriptor

Import from file

Import metadata from a file

If the import is being performed using a file, there is a need to click the Select file button, and to select the requested file.

Configuring a SAML Provider with Azure Active Directory (AD)

This page provides details about SSO configuration on Checkmarx One when using Azure Active Directory.

Instructions

  1. Log in to Checkmarx One using your Tenant, Username and Password.

  2. Click on the Identity_and_Access_MGMT.png icon

  3. In the Identity and Access Management screen click on 6235525678.png icon

  4. Select SAML v2.0

    6235525732.png

  5. Copy the redirect URI

    Redirect_URI.png

  6. On the Azure webapp, set Identifier and Reply URL fields according to the copied Redirect URI.

    • Identifier = A portion of the Redirect URI (until the tenant name).

    • Reply URL = Redirect URI.

      Note

      To create a new Azure webapp go to Enterprise Applications → Create your own application → Integrate any other application you don't find in the gallery (Non-gallery).

      6235525726.png

  7. On Azure, copy the App Federation Metadata Url

    6235525723.png

  8. On Checkmarx One, use the copied link to import the metadata.

    Perform the following:

    1. Copy the URL to Import from URL field.

    2. Click Import

    3. Click Save

      6235525720.png

  9. Check Checkmarx One SAML configuration.

    This is how SAML settings should look like:

    SAML_Settings2.png
    6235525714.png

  10. On Azure, check that the claims are correctly configured.

    6235525711.png
    6235525708.png

  11. In Checkmarx One, create a mapper for the Username

    1. Click on Mappers tab.

    2. Click Create

      6235525705.png

    3. Fill the information and click Save

      Username_Mapper2.png

  12. Create a FirstName Mapper.

    Firstname_Mapper.png

  13. Create a Surname Mapper.

    Surname_Mapper.png

  14. Create an Email Mapper.

    Email_Mapper.png

  15. Create a Role Mapper.

    Role_Mapper.png

Warning

For this example, the Role claim configured on Azure is a constant “ast-viewer”.

This will map all users to assume the ast-viewer role.

Azure can send other values on this claim.

You will need to add a mapper for each value, to convert the azure claim value into a Checkmarx One role.

Explore other Mapper Types for other ways to map roles.

Importing Groups

Checkmarx One can also import groups from Azure AD.

Create the GroupMapper:

6235525687.png

On Azure, add a group claim.

6235525684.png

Warning

This azure configuration example will return the group ID's. Check Azure AD documentation on how to provide a friendly name.

Related article: How To Work Around The Azure SAML Group Claim Limitations

If the integration is being done for groups that are not created within Checkmarx One, using the Entra ID group name, users can use the sAMAccountName as the source attribute instead of the Group ID and configure the Entra ID group name.

Troubleshooting

A good way to troubleshoot issues with the configuration is to only configure one mapper, for example a Given Name.

When the information is incomplete, the user will be prompted to enter the user’s missing data.

SAML_Login.png

In the image above, we can check that Checkmarx One is being able to retrieve the First Name correctly.

This form is only shown when the user logs in for the first time.

Configuring a SAML Provider with OKTA

This page provides details about SSO configuration with SAML on Checkmarx One using OKTA.

Instructions

Start Creating a new Identity Provider via Checkmarx One

  1. Log in to Checkmarx One using your Tenant, Username and Password.

  2. Hover over the Settings.png icon and select Identity and Access Management.

  3. In the Identity and Access Management screen click on 6235526044.png

  4. Select SAML v2.0

    6235526041.png

  5. In the Add identity provider page, copy the Redirect URI

    Image_027.png

Create an Application in OKTA

  1. Log in to the OKTA console using an admin account.

  2. In the OKTA home page, click on Applications

  3. In the Applications page, click Create App Integration

    6235526035.png

  4. The Create a New Application Integration popup opens.

  5. In the Create a New Application Integration, perform the following:

    1. Select SAML 2.0

    2. Click Next

      6235526032.png

  6. In the Create SAML Integration page, perform the following:

    1. Configure the App name

    2. Click next

      6235526029.png

  7. In the Single sign on URL field, paste the Redirect URI (copied in first step).

    6235526026.png

  8. In the Audience URI (SP Entity ID) field, paste the Entity ID using the following procedure:

    1. In Checkmarx One, in the Add identity provider page in the Endpoints field, click on the Metadata link.

      Image_026.png

    2. The Service Provider Metadata will be opened in an XML file in a new tab.

    3. From the XML file copy the Entity ID.

  9. Go to Attribute Statements section configure the base mapper fields:

    1. First Name

    2. Last Name

    3. Email

    4. Role

      Note

      Make sure to set value with “user.” prefix for First Name, Last Name and Email.

      For Role, set the ast-viewer value.

      6235526023.png

  10. Add Groups Attribute Statement (Optional):

    1. Under the Group Attribute Statements, create a new statement named “Groups”.

    2. Select the filter option that best describes your use-case.

      Note

      Configuring “.*” will import all the groups.

      6235526020.png

  11. After setting Attribute and Group Statements, scroll down to the bottom and click Next

  12. Select if you are a customer or partner and click Finish

    6235526017.png

  13. In the Sign On tab, click on Identity Provider metadata link.

    6235526014.png

  14. This will open a new tab with the App Federation Metadata URL, copy the URL

    6235526011.png

Finish Creating Identity Providers via Checkmarx One

  1. In Checkmarx One, use the copied link to import the metadata, by performing the following:

    1. Copy the URL to Import from URL field.

    2. Click Import

    3. Click Save

      6235526008.png

  2. Check the Checkmarx One SAML configuration.

  3. This is how SAML settings should look:

    App_Settings_OKTA.png
    6235526002.png

  4. Click on Mappers tab and click Create

    6235525999.png

  5. Create a First Name Mapper.

    First_Name_Mapper_OKTA.png

  6. Create a Last Name Mapper.

    Last_Name_Mapper_OKTA.png

  7. Create an Email Mapper.

    Email_Mapper_OKTA.png

  8. Create a Role Mapper.

    Role_Mapper_OKTA.png

  9. Create the GroupsMapper (Optional) - If you added the attribute statement in the OKTA configuration.

    Groups_Mapper_OKTA.png

Warning

For this example, the Role claim configured on OKTA is a constant “ast-viewer”.

This will map all users to assume the ast-viewer role.

OKTA can send other values on this claim.

You will need to add a mapper for each value, to convert the OKTA claim value into a Checkmarx One role.

Explore other Mapper Types for other ways to map roles.

Identity Provider Initiated Flow

Azure Identity Provider Initiated Flow

Preconditions

Login into Keycloak and into Azure, set up providers according to Configuring a SAML Provider with Azure Active Directory (AD)

Set up Identity Provider in Keycloak and Azure

  1. Fill out Identifier (Entity ID) field in Azure.

    • In Keycloak side, in Service provider settings copy the part of field Redirect URI

      Copy_URL.png

    • In Azure, in Identifier (Entity ID) field, pass the part of copied URL (without the ending part “/broker/checkmarxsaml/endpoint“)

      https://{KEYCLOAK_URL}/auth/realms/{REALM}

      Fill_Identifier_field.png

  2. Fill in the Reply URL field in azure

    • In Keycloak side, in Service provider settings copy the content of Redirect URI and IDP Initiated flow URI fields

      Redirect_URI___IDP_Initiated_flow_URI_Fields.png

    • In Azure, in Reply URL (Assertion Consumer Service URL) field, add both fields from the previous step

      Reply_URL_Field.png

  3. Click Save

Set up Fields Mapping

  1. In Azure

    • SAML-based Sign-on → Attributes & Claims → Edit

    • In the table select Required claim → Claim name → Unique User Identifier (Name ID) and click Unique User Identifier (Name ID)

    • In the opened Manage claim screen find and click Choose name identifier format → Name identifier format

    • In the dropdown select Email or Persist and Save

      Azure_Name_Identifier_Format_Claim.png

  2. In Keycloak provider settings, find SAML Settings-> NameID Policy Format section

    In the dropdown, select the same value as it was selected in azure in previous step (Email or Persist)

    Name_ID_Policy_Format_Field.png

Login using Azure Identity Provider Initiated Flow

  1. In azure, create a new user

  2. Login into Microsoft Azure as the created user

  3. View Account → My Apps → select the app

    Test_Azure_Initiated_Flow.png

OKTA Identity Provider Initiated Flow

Preconditions

Login into Keycloak and into OKTA, set up providers according to Configuring a SAML Provider with OKTA

Set up Identity Provider in Keycloak and OKTA

  1. Fill out Audience URI (SP Entity ID) field in OKTA

    • In Keycloak side, in Service provider settings copy the part of the IDP Initiated Flow URI field

      Copy_URL2.png

    • In OKTA > Audience URI (SP Entity ID) field, pass the part of copied URL (without the ending part “/broker/oktasaml/endpoint“)

      https://{KEYCLOAK_URL}/auth/realms/{REALM}

      Audience_URI.png

  2. Fill in Single sign on URL field in OKTA

    • In Keycloak side, in Service provider settings copy the content of IDP Initiated flow URI field

      IDP_Initiated_Flow_URI_Field.png

    • In OKTA > Single sign on URL field, pass the copied URL from the previous step

      Single_Sign_On_URL.png

  3. Click Save

Login using OKTA Identity Provider Initiated Flow

  1. Login into OKTA

  2. OKTA apps → My end user dashboards

  3. Select app

    Login_Using_OKTA_IDP_Initiated_Flow.png
In this section: