Task: Configure Keycloak (OIDC) Hub Authentication

• Preliminaries
• Permissions
• Other Requirements
• Configure Authentication
• Links

Preliminaries

In this example, we will configure a Keycloak OIDC 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.
  
  • The hub user account username will match the Keycloak user email.
    Keycloak users without a configured email address will not be able to use this service for hub authentication.
  • 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.

Other Requirements

• You will need administrative permissions for your organization's Keycloak deployment.
• Your hub must be able to make outgoing connections. In particular, it must be able to connect to your Keycloak server.

Configure Authentication

Configuring Keycloak OIDC authentication for your CodeSonar hub is a four-part process:

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

Part A: 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 OpenID Connect from the Client type menu, then populate the remainder of the form.

   Populate Keycloak "Add Client" field...	with...
   Client ID	A short identifier for the client. You may wish to choose a meaningful identifier such as csonar_hub.
   Name	A meaningful name so that you can identify the service later.

5. Click Next to go on to the Capability config tab.
   If you want to change any of the default settings on this tab, do so now.
6. Click Next to go on to the Login settings tab.
   Do not enter anything in this tab. You will finish setting up these values in Part D.
7. Click Save.
8. Select Clients from the navigation bar.
   Your new client will now be displayed in the table.
9. Go on to Part B: Get Keycloak configuration information.

Part B: 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. Use your browser functionality to copy the URL associated with the OpenID Endpoint Configuration link.
   Depending on your browser, you may be able to do this as follows.
   • Right-click on OpenID Endpoint Configuration, then select Copy link address from the menu that pops up.
     or
   • Click OpenID Endpoint Configuration to open the link, then copy its URL from the browser URL bar.
   You will need this URL in part C: either save it now, or leave the Realm Settings page open so you can copy the URL directly at configuration time.
4. Go on to Part C: Configure the CodeSonar authentication plug-in.

Part C: 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 OIDC server.
   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 OIDC from the Type menu.
   The Configuration section of the Add Service form will update to display form fields for required OIDC configuration information.
8. Enter a suitable name, such as Keycloak OIDC, 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.
   OIDC configuration
   	OIDC Discovery URL	The URL from the Keycloak OpenID endpoint configuration (you recovered this in part B).
   	Client ID	The Client ID you set for your Keycloak client in part A.
   	Client Secret	see notes	Leave empty unless you set Client authentication to On when you created the Keycloak client in Part A. If Client authentication is On, enter the Client Secret for your Keycloak client. To find this in Keycloak: Select Clients from the navigation bar. Click the Client ID of your new client. The Client details page will open, showing the Settings tab. Change to the Credentials tab. Copy the value in the Client Secret field.
   	User Claim	email	The hub user account username will match the Keycloak user email. Keycloak users without a configured email address will not be able to use this service for hub authentication.
   	Role Claim	empty	If you want to use Keycloak roles to assign CodeSonar roles to hub user accounts, contact CodeSecure support for assistance.
   	Extra Scopes	empty	The email claim does not require any extra scopes.

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 URI labeled Your OpenID Connect server will need our redirect_uri listed here.
    Copy this URI: you will need it in Part D.

11. Go on to Part D: Finish configuring your Keycloak client.

Part D: Finish configuring your Keycloak client

1. Sign in to your organization's Keycloak deployment as a user with administrative permissions.
2. Navigate to the settings for your Keycloak client.
   1. Select Clients from the navigation bar.
   2. Click the Client ID of your new client.
      The Client details page will open, showing the Settings tab.
3. Scroll down to the Access settings section.
4. In the Valid redirect URIs field, paste the URI that you copied in part C.
5. Click Save.

Try out your new authentication service.

On your CodeSonar hub:

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

Links

• Typical CodeSonar Tasks
• CodeSonar GUI Reference