Task: Configure Azure AD (SSO) Hub Authentication

• Preliminaries
• Permissions
• Configure Authentication
• Links

Preliminaries

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

Important Note: single sign-on with Azure AD can only be configured for HTTPS hubs.
You can enable HTTPS for your hub from the Configure HTTPS page in the Web GUI.

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 Azure AD deployment.

Configure Authentication

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

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

Part A: Set up an Azure AD "Enterprise Application " for CodeSonar

1. Sign in to your organization's Azure AD deployment as a user with administrative permissions.
2. Select Azure Active Directory.
3. From the left navigation pane, select Enterprise applications
   The All Applications page will be displayed.
4. Select New Application from the menu at the top of the page.
5. Click Create your own application.
   A Create your own application form will open.
6. Provide a meaningful name for your application (such as "CodeSonar").
7. Select Integrate any other application you don't find in the gallery (Non-gallery).
8. Click Create.
   The Overview page for your new application will be displayed.
9. Click the name of your new application select it.
10. Select Single sign-on, then click SAML when prompted to select a single sign-on method.
    The SAML-based Sign-on page will be displayed.
11. In the Basic SAML Configuration section, click Edit and set the fields as follows.
    You will update these settings later, after you have configured the authentication plug-in on the hub.
    1. Identifier (Entity ID) : the base URL for your hub. For example, https://myhub.example.com:7340.
    2. Reply URL (Assertion Consumer Service URL) : the base URL for your hub. For example, https://myhub.example.com:7340.
    3. Sign on URL : the URL of your hub Sign In page. For example, https://myhub.example.com:7340/sign_in.html.
    Once you have set the fields, click Save.
12. In the Attributes & Claims section, click Edit and add two claims with Add new claim:

    Name	Source	Source Attribute
    email	Attribute	user.mail
    user	Attribute	user.userprincipalname

13. Do you want to use Azure AD groups to assign CodeSonar roles to hub user accounts?
    You can configure Azure AD to provide the authentication plug-in with a list of some or all of the Azure AD groups a user belongs to, or a filtered version of this list. The plug-in will treat each Azure AD group name on the list as if it is a CodeSonar role name.
    • NO: Go on to the next step.
    • YES:
      1. In the Attributes & Claims section, select Edit and then Add a group claim.
         The Group Claims dialog will open.
      2. Select All groups, or a different selection if you want to provide a specific subset of the Azure AD groups a user belongs to.
         If you select Groups assigned to the application, you will need to assign relevant groups to the applciation.
      3. Expand the Advanced options section of the dialog.
      4. Select Customize the name of the group claim.
      5. Enter roles in the Name field.
      6. [Optional] If you want to filter the set of groups, select Filter groups and use the fields to specify your filter conditions.
      7. 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 the corresponding Azure AD user is no longer member of the Azure AD groups with those names, those roles are removed from the hub user account.
      • For each assigned Azure AD group whose name is also the name of a CodeSonar role, that role is added to the hub user account. (Azure AD 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 Azure AD groups you want to reflect. See the RBAC: Roles page for more information on creating roles and assigning permissions.
14. 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: https://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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD App Federation Metadata URL link.	This is generally more convenient than manually entering IdP metadata, but requires that your hub is able to make requests to the Azure AD 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 value of this field from your Azure AD instance. Select Single sign-on in the left pane menu to navigate to the SAML-based Sign-on page. In the SAML Signing Certificate section, copy the value of the App Federation Metadata URL field.
   	...or all of the following.
   	Entity ID	You will need to manually extract these values from the App Federation metadata. Navigate to the Set up single sign-on with SAML page. In the SAML Signing Certificate section, copy the value of the App Federation Metadata URL field. Obtain the XML from the copied URL in a web browser and extract the required values as specified for each field. (Note: required values are specified as XPath strings.) Entity ID: the value of XML attribute /EntityDescriptor/@entityID Single Sign On URL: the value of XML attribute /EntityDescriptor/IDPSSODescriptor/SingleSignOnService[@Binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect]/@Location IDP Signing Certificate: the value of XML element /EntityDescriptor/IDPSSODescriptor/KeyDescriptor[@use=signing]/KeyInfo/X509Data/X509Certificate
   	Single Sign On URL
   	IdP Signing Certificate
   Other SSO Configuration
   	Requests	unselected	The hub will sign requests sent to Azure AD. If you select this, perform the following additional configuration steps. On your CodeSonar hub, download the hub server certificate from the hub Configure HTTPS page. Convert the downloaded hub server certificate to .cer format. If you don't have openssl installed locally, use $CSONAR/third-party/openssl/inst/bin/openssl (openssl.exe on Windows). openssl x509 -inform PEM -in ssl_cert.pem -outform DER -out ssl_cert.cer In Azure AD, do the following. Select Single sign-on in the left pane menu to navigate to the SAML-based Sign-on page.. Scroll to the SAML Certificates section, and click Edit next to the Verification certificates heading. The Verification certificates dialog will open. Select Require verification certificates. Click Upload certificate and import your converted ssl_cert.cer. Click Save to save your changes.
   	Signed Responses	unselected	The hub will require that requests sent to Azure AD are signed. If you select this, perform the following additional configuration steps in Azure AD. Select Single sign-on in the left pane menu. Scroll to the SAML Certificates section, and click Edit next to the Token signing certificates heading. The SAML Signing Certificate dialog will open. Set Signing Option to Sign SAML Response. Click Save to save your changes.
   	Encrypted Responses	unselected	The hub will require that responses from Azure AD are encrypted. If you select this, perform the following additional configuration steps. If you haven't already downloaded the hub server certificate and converted it to .cer format, do it now. On your CodeSonar hub, download the hub server certificate from the hub Configure HTTPS page. Convert the downloaded hub server certificate to CER format. If you don't have openssl installed locally, use $CSONAR/third-party/openssl/inst/bin/openssl (openssl.exe on Windows). openssl x509 -inform PEM -in ssl_cert.pem -outform DER -out ssl_cert.cer In Azure AD, do the following. Select Token encryption in the left pane menu. The Token encryption page will open. Select Import Certificate and import the hub server certificate. Once the certificate is imported, click ... next to the certificate thumbprint status, then select Activate token encryption from the menu that opens.

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 Azure AD App Integration.

Part C: Configure the Azure AD App Integration

1. Sign in to your organization's Azure AD deployment as a user with administrative permissions.
2. Navigate to your CodeSonar application.
3. Click Single sign-on in the left pane menu.
   The SAML-based Sign-on page will open.
4. In the Basic SAML Configuration section, click Edit.
   The Basic SAML Configuration will open.
5. Populate the fields as follows.

   Populate Azure AD "Basic SAML " field...	... with the information from CodeSonar "Setting up this SAML Integration in Your IdP" field
   Identifier (Entity ID)	SP Entity ID
   Reply URL (Assertion Consumer Service URL)	Assertion Consumer Service URL

6. Save your changes.
7. Assign users or groups to the CodeSonar application. Users who are not assigned (or members of groups that are assigned) will not be able to use Azure AD for hub authentication.
   1. Click Users and Groups in the left pane menu.
   2. Click Add user/group.
      The Add Assignment dialog will open.
   3. Use the dialog to specify one or more users/groups that can use this application to perform SSO hub authentication with Azure AD.
   4. If necessary, repeat to make further assignments.
8. Try out the new service. On your hub:
   1. Sign out of the Administrator account.
   2. Sign in with your Azure AD 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 Azure AD] Make any necessary changes to the CodeSonar application.
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 Azure AD] Make sure the following values are up to date in the Basic SAML Configuration for the CodeSonar application.
   • Identifier (Entity ID)
   • Reply URL (Assertion Consumer Service URL)

Links

• Typical CodeSonar Tasks
• CodeSonar GUI Reference