Task: Configure Okta (SSO) Hub Authentication

• Preliminaries
• Permissions
• Configure Authentication
• Links

Preliminaries

In this example, we will configure an Okta 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 Okta deployment.

Configure Authentication

Configuring Okta authentication for your CodeSonar hub is a three-part process:

• Part A: Set up an Okta "App Integration" for CodeSonar
• Part B: Configure the CodeSonar authentication plug-in
• Part C: Configure the Okta App Integration

Part A: Set up an Okta "App Integration" for CodeSonar

1. Sign in to your organization's Okta deployment as a user with administrative permissions.
2. Open the Admin Console.
3. From the navigation bar, select Applications > Applications.
   The Applications page will be displayed.
4. Click Create App Integration.
   A Create a new app integration dialog will open.
5. Select SAML 2.0, then click Next.
   The Create SAML Integration page will be displayed.
6. On the General Setting tab, provide a meaningful App name (such as "CodeSonar") so that you can identify the app later, then click Next.
   (You don't need to provide information for any of the other General Settings.)
   The Configure SAML tab will be displayed.
7. Enter information in the Configure SAML tab as follows. You will update these settings later, after you have configured the authentication plug-in on the hub.
   1. Single sign on URL: the base URL for your hub. For example, http://myhub.example.com:7340.
   2. Audience URI (SP Entity ID): also the base URL for your hub. For example, http://myhub.example.com:7340.
   3. In the Attribute Statements section, click Add Another and add a new attribute statement named email with value user.email.
   4. In the Attribute Statements section, click Add Another and add a new attribute statement named user, with value user.login.
   5. Do you want to use Okta groups to assign CodeSonar roles to hub user accounts?
      You can configure Okta to provide the authentication plug-in with a list of some or all of the Okta groups a user belongs to, or a filtered version of this list. The plug-in will treat each Okta group name on the list as if it is a CodeSonar role name.
      • NO: Go on to the next step.
      • YES: In the Group Attribute Statements section, click Add Another and add a new group attribute statement.

        Name:	roles
        Filter:	A filter that should be applied to the list of the user's Okta groups in order to produce the list that will be provided to the authentication plug-in. For example: [Matches regex] .* A list containing all the user's Okta groups. [Equals] ProjectX Either a list containing only the "ProjectX" group or an empty list, depending on whether or not the user belongs to "ProjectX".

        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 the corresponding Okta user is no longer member of the Okta groups with those names, those roles are removed from the hub user account.
        • For each assigned Okta group whose name is also the name of a CodeSonar role, that role is added to the hub user account. (Okta groups whose name is not the name of a CodeSonar role are ignored.)
        To take full advantage of the group→role mapping feature, ensure you have CodeSonar roles that correspond to all the Okta groups you want to reflect. See the RBAC: Roles page for more information on creating roles and assigning permissions.
   6. Click Next.
8. Select I'm an Okta customer adding an internal app and click Finish.
9. Switch to the Sign On tab for the new app. You will need the information from this tab in Part B.
10. 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 Okta Authentication, 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 Okta tab in the CodeSonar Sign In page. Tabs for SSO 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 has no effect and the selector is not active.
   	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 Okta 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
   	either...
   	Metadata URL	Copy and paste the URL associated with the the Okta Identity Provider metadata link.	This is generally more convenient than manually entering IdP metadata, but requires that your hub is able to make requests to the Okta server. In particular, you will not be able to use this option if your system is configured so that the hub cannot make outgoing connections. If available, you can obtain the values of this field from your Okta instance. Switch to the Sign On tab for the new app you created in Part A. Scroll to the SAML Signing Certificates section. In the table of certificates, click Actions to expand the menu of available actions. Depending on your browser, you may be able to copy the URL as follows. Right-click on View IdP Metadata, then select Copy link address from the menu that pops up. or Click View IdP Metadata to open the link, then copy its URL from the browser URL bar.
   	...or all of the following.
   	Entity ID	Copy and paste the value from the Okta Identity Provider Issuer field.	Obtain the values of these fields from your Okta instance: Switch to the Sign On tab for the new app you created in Part A. Click View SAML setup instructions.
   	Single Sign On URL	Copy and paste the value from the Okta Identity Provider Single Sign-On URL field.
   	IdP Signing Certificate	Copy and paste the value from the Okta X.509 Certificate field.
   Other SSO Configuration
   	Requests	unselected	The hub will sign requests sent to Okta. Do not select unless the hub is configured with a SSL/TLS hub server certificate and HTTPS is enabled. If you select this, perform the following additional configuration steps in Okta. Save a copy of the hub server certificate (but not its private key) so that you can upload it to Okta. Navigate to the Configure SAML tab for your CodeSonar App Integration and click Show Advanced Settings. In the Signature Certificate row, click Browse Files and then browse to your copy of the hub server certificate. Click the checkbox next to Signed Requests to select it. Click Next, then Finish.
   	Signed Responses	unselected	The hub will require that requests sent to Okta are signed. If you select this, perform the following additional configuration steps in Okta. Navigate to the Configure SAML tab for your CodeSonar App Integration and click Show Advanced Settings. In the Response row, select Signed from the pull-down menu. Click Next, then Finish.
   	Encrypted Responses	unselected	The hub will require that responses from Okta are encrypted. Do not select unless the hub is configured with a SSL/TLS hub server certificate and HTTPS is enabled. If you select this, perform the following additional configuration steps in Okta. Save a copy of the hub server certificate (but not its private key) so that you can upload it to Okta. Navigate to the Configure SAML tab for your CodeSonar App Integration and click Show Advanced Settings. In the Assertion Encryption row, select Encrypted from the pull-down menu. Additional fields will be displayed. In the Encryption Certificate row, click Browse Files and then browse to your copy of the hub server certificate. Click Next, then Finish.

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: Configure the Okta App Integration.

Part C: Configure the Okta App Integration

1. Sign in to your organization's Okta deployment as a user with administrative permissions.
2. Open the Configure SAML tab for your CodeSonar App Integration:
   1. From the navigation bar, select Applications > Applications.
      The Applications page will be displayed.
   2. Click the name of the app integration you created in Part A.
      The page for your app integration will open.
   3. Switch to the General tab, if it is not already open.
   4. Scroll to the SAML Settings section and click Edit.
      The Edit SAML Integration page will open.
   5. Click Next to move to the Configure SAML tab.
3. Update the information in the Configure SAML tab using the information shown in the CodeSonar Authentication Services table entry for your new service.

   Populate Okta "Configure SAML " field...	... with the information from CodeSonar "Setting up this SAML Integration in Your IdP" field
   Single sign on URL	Assertion Consumer Service URL
   Audience URI (SP Entity ID)	SP Entity ID

4. Click Next, then click Finish.
   The Sign On tab for your app integration will be displayed.
5. Assign users or groups to the CodeSonar app integration. Users who are not assigned (or members of groups that are assigned) will not be able to use Okta for hub authentication.
   1. Switch to the Assignments tab.
   2. Select Assign to People or Assign to Groups from the Assign menu. An assignment dialog will open.
   3. Use the dialog to specify one or more users/groups that can use this integration. When you are finished, click Done.
   4. If necessary, repeat to make further assignments.
6. Try out the new service.
   1. Sign out of the Administrator account.
   2. Sign in with your Okta 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 Okta] Make any necessary changes to the App Integration 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 Okta] Make sure the following values are up to date in the SAML Settings for the CodeSonar App Integration.
   • Single sign on URL
   • Audience URI (SP Entity ID)

Links

• Typical CodeSonar Tasks
• CodeSonar GUI Reference