Task: Configure Keycloak (SSO SAML) Hub Authentication

• Preliminaries
• Permissions
• Configure Authentication
• Links

Preliminaries

In this example, we will configure a Keycloak SSO SAML authentication service such that:

• Hub user accounts will be automatically created for users who are authenticated through the service but do not already have corresponding hub accounts.
  
  • For each of these automatically created accounts, the template user will be alex: the account will be created with the same Default Role, Email Alerts? setting, User Roles set, and Visibility Defaults as alex has at the time the new account is created.
  • Hub user accounts that are automatically created on behalf of third-party authentication services always have the special Enabled role.
• Authentication for any satellite hubs will be performed by the primary hub.

Permissions Needed For This Task

• G_MANAGE_USERS (needed to access the Authentication Services page).
• User control over the hub user accounts that you want to use as the template user and authorizing user for your new authentication service.
  • G_ADMINISTER_USERS
    or
  • G_MANAGE_USERS and ROLE_ADMINISTER R for every role R that the user is assigned.

It is sufficient to authenticate as a user with the special Administrator role, which immutably has the necessary permissions. In particular, it is always sufficient to authenticate as special user Administrator.

You will also need administrative permissions for your organization's Keycloak deployment.

Configure Authentication

Configuring Keycloak SSO SAML authentication for your CodeSonar hub is a three-part process:

• Part A: Get Keycloak configuration information
• Part B: Configure the CodeSonar authentication plug-in
• Part C: Create a new Keycloak client

Part A: Get Keycloak configuration information

1. Sign in to your organization's Keycloak deployment as a user with administrative permissions.
2. From the navigation bar, select Realm Settings (under Configure).
3. Can your hub make requests to the Keycloak server? (In particular, the answer will be "no" if your system is configured so that the hub cannot make outgoing connections.)
   • YES: You can configure the plug-in to recover identity provider metadata automatically from the metadata URL.
     1. Use your browser functionality to copy the URL associated with the SAML 2.0 Identity Provider Metadata link.
        Depending on your browser, you may be able to do this as follows.
        • Right-click on SAML 2.0 Identity Provider Metadata, then select Copy link address from the menu that pops up.
          or
        • Click SAML 2.0 Identity Provider Metadata to open the link, then copy its URL from the browser URL bar.
     2. You will need this URL in part B: either save it now, or leave the Realm Settings page open so you can copy the URL directly at configuration time.
   • NO: You will need to manually enter several pieces of identity provider metadata.
     
     1. Click SAML 2.0 Identity Provider Metadata to open the link.
        If your browser is configured to download XML directly rather than rendering it to the browser window, open the downloaded XML file.
     2. Read the required metadata from the XML as follows.

        Required Metadata	XML entity
        Entity ID	Attribute entityID of the top-level md:EntityDescriptor element. It will be an URL of the form http://keycloak-server/auth/realms/realm-name.
        Single Sign On URL	Attribute Location of the md:SingleSignOnService element with Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect". It will be an URL of the form http://keycloak-server/auth/realms/realm-name/protocol/saml.
        IdP Signing Certificate	The contents of element ds:X509Certificate.

     3. You will need this metadata in part B: either save your extracted data now, or leave theXML file open so you can copy the data directly at configuration time.
4. Go on to Part B: Configure the CodeSonar authentication plug-in.

Part B: Configure the CodeSonar authentication plug-in

1. Sign in to the hub.
   1. Click the Sign In link in the GUI page header:
      The Sign In page will open.
   2. Sign in as Administrator, or another user with sufficient permissions.
2. Click the Settings icon in the page header to view the Settings page.
3. If you haven't already configured a public URL for your hub, do so now: it will be used to generate information that will identify your hub to the SSO service.
   1. Change to the HTTP tab.
   2. Enter the URL you wish to use in the Public URL field. Make sure it includes the protocol and port.
      For example: http://myhub.example.com:7340
   3. Click Update to save your changes.
4. Change to the User Administration tab.
5. Click the Authentication Services link in the tab.
   The Authentication Services page will open.
6. Scroll down to the Add Service form.
7. Select SSO SAML from the Type menu.
   The Configuration section of the Add Service form will update to display form fields for required SSO SAML configuration information.
8. Enter a suitable name, such as Keycloak SSO SAML, in the Service Name field.
9. Fill in the remaining configuration fields as follows.

   Field		Value	Notes
   Standard Plug-in Configuration Fields
   	Priority	10	The Priority value controls the relative position of the sign in with Keycloak tab in the CodeSonar Sign In page. Tabs for authentication services with lower Priority values are ordered before those for services with higher priority values. The tab with the lowest Priority value is displayed by default.
   	Usage	Global	If you are running a primary hub with satellites, authentication for the primary hub and all satellite hubs will be performed by the primary hub. If you do not have satellite hubs, this setting will have no effect.
   	Create new user accounts automatically	selected	If the service successfully authenticates a user who does not already have a hub account, one will be automatically created.
   	Template User (for new accounts)	alex	Existing user alex will be the template user for any hub user accounts that are automatically created by the service. Hub accounts that were not automatically created by the service are not affected, even if users sign into them using this service. There is no effect on Keycloak user information.
   	Auth User	see notes	This must be a hub user account that has user control over the designated Template User. The authentication service will only be able to perform hub operations that this account has permission to perform. In general, we recommend setting as follows. CodeSonar SaaS: the hub user account that you are using to configure the authentication service. otherwise: special user Administrator.
   IdP Metadata: enter the metadata you recovered in part A.
   	either...
   	Metadata URL	The URL from the Keycloak SAML 2.0 Identity Provider Metadata (you recovered this in part A).	This is generally more convenient than manually entering IdP metadata.
   	...or all of the following.
   	Entity ID	The values that you extracted from the Keycloak metadata XML.
   	Single Sign On URL
   	IdP Signing Certificate
   Other SSO Configuration
   	Requests	unselected	do not select
   	Signed Responses	unselected	The hub will require that responses from Keycloak are signed.
   	Encrypted Responses	unselected	do not select

10. Click Add Service.
    The authentication service will be installed. When installation has finished, the table of current services will update to show an entry for the new service, including a Setting up this SAML Integration in Your IdP section. You will need the information from this table in Part C.
11. Go on to Part C: Create a new Keycloak client.

Part C: Create a new Keycloak client

1. Sign in to your organization's Keycloak deployment as a user with administrative permissions.
2. From the navigation bar, select Clients (under Manage).
   The Clients page will be displayed.
3. Click the Create client button (at top left of the table of clients).
   The Create client form will be displayed.
4. Select SAML from the Client type menu, then populate the remainder of the form.

   Populate Keycloak "Add Client" field...	with...
   Client ID	the SP Entity ID from the CodeSonar "Setting up this SAML Integration in Your IdP" section.
   Name	a meaningful name so that you can identify the service later.

5. Click Next to go on to the Login settings tab, then do the following.
   1. Copy the Assertion Customer Service URL from the CodeSonar "Setting up this SAML Integration in Your IdP" section.
   2. Enter your plug-in's Assertion Consumer Service URL in the Keycloak client Master SAML Processing URL field.
   3. Enter your plug-in's Assertion Consumer Service URL in the Keycloak client Valid Redirect URIs field.
   4. Click Save.
6. Select Clients from the navigation bar.
   Your new client will now be displayed in the table.
7. Click the Client ID of your new client.
   The Client details page will open, showing the Settings tab.
8. Navigate to the Signature and Encryption section of the Settings tab.
9. Did you configure the CodeSonar authentication plug-in to require Signed Responses?
   • NO (default)
     1. Set Sign documents to Off.
     2. Set Sign assertions to On.
     3. Save your changes.
   • YES
     1. Set Sign documents to On.
     2. Set Sign assertions to Off.
     3. Save your changes.
10. Switch to the Keys tab and do the following.
    1. Set Client signature required to Off.
    2. Set Encrypt assertions to Off.
11. Switch to the Client Scopes tab.
12. If any client scopes other than the following are assigned, remove them.
    • <client_id>-dedicated, where <client_id> is the Client ID.
13. Click the <client_id>-dedicated link.
    The Dedicated scopes page will open.
14. If there are no existing mappers, click the Configure a new mapper button.
    Otherwise, click Add mapper and select By configuration from the menu that opens.

    The Configure a new mapper form will open.

15. Click User Property.
    The Add mapper page will open.
    1. Fill out the remaining fields as follows.

       Form Field	Contents
       Name	user
       Property	username
       Friendly Name	user
       SAML Attribute Name	user
       SAML Attribute NameFormat	Unspecified

    2. Click Save.
    3. Click Dedicated scopes in the page breadcrumbs to return to the Dedicated scopes page.
16. Repeat the process in steps 12-13 to create another new User Property mapper with the following values.

    Form Field	Contents
    Name	email
    Property	email
    Friendly Name	email
    SAML Attribute Name	email
    SAML Attribute NameFormat	Unspecified

17. Do you want to use Keycloak roles to assign CodeSonar roles to hub user accounts?
    • NO: Go on to the next step.
    • YES: Navigate back to the Dedicated scopes page and do the following.
      1. Click Add mapper and select By configuration from the menu that opens.
         The Configure a new mapper form will open.
      2. Click Role list.
         The Add mapper page will be open.
      3. Fill out the remaining fields as follows.

         Form Field	Contents
         Name	roles
         Role attribute name	roles
         Friendly Name	roles
         SAML Attribute NameFormat	Unspecified
         Single Role Attribute	ON

      4. Click Save.
      Each time a user signs in to the CodeSonar hub with this plug-in, their hub user account Roles will be updated as follows.
      • If the hub user account has any roles that were assigned by this plug-in at a previous login but are not now assigned to the corresponding Keycloak user, those roles are removed from the hub user account.
      • For each assigned Keycloak role whose name is also the name of a CodeSonar role, that role is added to the hub user account. (Keycloak roles whose name is not the name of a CodeSonar role are ignored.)
      To take full advantage of the role mapping feature, ensure you have CodeSonar roles that correspond to all the Keycloak roles you want to reflect. See the RBAC: Roles page for more information on creating roles and assigning permissions.
18. Try out the new service.
    1. Sign out of the Administrator account.
    2. Sign in with your Keycloak credentials.
       If everything is working correctly, the hub will sign you into a corresponding hub user account.

Changing configuration

If you need to change the configuration for the service, work through the following steps.

1. [In Keycloak] Make any necessary changes to the Client for CodeSonar.
2. [On the CodeSonar hub] Make any necessary changes to the plug-in configuration.
   1. Click the relevant entry in the table of current services to open the Edit Authentication Service page.
   2. Use the functionality on the Edit Authentication Service page to modify the plug-in configuration.
3. [In Keycloak] Make sure the following values are up to date on the client Settings tab.
   • Client ID
   • Valid Redirect URIs
   • Master SAML Processing URL

Links

• Typical CodeSonar Tasks
• CodeSonar GUI Reference