Configuring connection between KUMA and Active Directory Federation Services

To configure domain authentication in KUMA and ensure that users can log in to KUMA using their accounts without specifying a user name and password, first create a connection group and configure the rules in ADFS or make sure that the necessary connection groups and rules already exist.

After configuration, the Sign in via ADFS button appears on the KUMA login page.

The Sign in via ADFS button is hidden on the KUMA login page in the following conditions:

• The FreeIPA option is selected in the Authorization type drop-down list.
• The AD/ADFS option is selected in the Authorization type drop-down list and the settings for ADFS are not specified or the Disabled check box is selected for ADFS settings.

You can connect only to one ADFS domain. To do so, you must configure a connection to the domain controller.

To configure a connection to an ADFS domain controller:

1. In the application web interface, select Settings → Domain authorization.
2. In the Authorization type drop-down list, select AD/ADFS.
3. In the Active Directory Federation Services settings block, in the Client ID field, enter the KUMA ID from the Client ID field in the ADFS.
4. In the Relying party identifier field, enter the KUMA ID from the Relying party identifiers field in the ADFS.
5. Enter the Connect Metadata URI from the Connect Metadata URI field. This parameter consists of the host where the ADFS resides (https://adfs.example.com), and the endpoint setting (/adfs/.well-known/openid-configuration).

   For example, https://adfs.example.com/adfs/.well-known/openid-configuration).

6. Enter the ADFS redirect URL from the Redirect URL field in the ADFS. The value of the Redirect URL field in the ADFS is defined when the Application group is configured. In the ADFS, you must indicate the KUMA FQDN and the </sso-callback> substring. In KUMA, the URL must be indicated without the substring, for example: https://kuma-example:7220/
7. If you want to configure domain authentication for a user with the KUMA general administrator role, use the General administrators group field to specify the DistinguishedName of the Active Directory Federation Services group containing the user.

   If the user belongs to several groups within the same tenant, the role with the least privileges is used.

   Filter input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

8. Click the Save button.

A connection with the Active Directory Federation Services domain controller is now configured.

For domain authentication, add the groups for the KUMA user roles.

You can specify the groups only for the roles that require the configuration of domain authentication. You can leave the rest of the fields empty.

To add groups of user roles:

1. In the application web interface, select Settings → Domain authorization.
2. In the Role groups settings block, click the Add role groups button.
3. In the Tenant drop-down list, select the tenant of the users for whom you want to configure domain authentication.
4. In the fields for the following roles, specify the DistinguishedName of the domain group. The users of this domain group must have the capability to perform authentication with their domain accounts:
   • Operator.
   • First line analyst.
   • Analyst.
   • Administrator.

   Group input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

   You can specify only one domain group for each role. If you need to specify multiple groups, you must repeat steps 2–4 for each group while indicating the same tenant.

5. If necessary, repeat steps 2–4 for each tenant for which you want to configure domain authentication with the following roles: operator, first line analyst, analyst, and tenant administrator.
6. Click the Save button.

The groups of user roles will be added. The defined settings will be applied the next time the user logs in to the KUMA web interface.

After the first authentication of the user, information about this user is displayed under Settings → Users. The Login and Password fields received from the domain cannot be edited. The user role will also be unavailable for editing. To edit a role, you will have to change the user role groups. Changes to a role are applied after the next authentication of the user. The user continues working under the current role until the current session expires.

If the user name or email address is changed in the domain account properties, these changes must be manually made in the KUMA account.

Configuring connection in Active Directory Federation Services

This section provides instructions on how to create a new connection group and configure rules for the created connection group in Active Directory Federation Services (ADFS).

The ADFS role must already be configured on the server.

Creating a new connection group

1. In Server Manager, in the Tools menu, select ADFS Management.

   In ADFS, select the Application groups section and in the Actions section click Add Application Group.

2. In the Add Application Group Wizard window that opens, in the Welcome section Name field, specify the name of the new connection group. Example: new-application-group.

   In the Template field, in the Client-Server applications group, select Native application accessing a web API.

   Click Next to proceed to the next step of creating and configuring a connection group.

3. In the Native application section that opens, the Name and

    Client Identifier

   fields are filled in automatically.

   Specify the value of the Client Identifier field in KUMA, when configuring domain authentication.

   In the

    

   Redirect URI field, enter the URI for redirection from ADFS with the /sso-callback substring, and click Add. Example: https://adfs.example.com:7220/sso-callback

   Click Next to proceed to the next configuration step.

4. In the Configure Web API section that opens, in the

   Identifiers

   field add the trusted party ID and click Add. It can be any arbitrary value. Example: test-demo

   Specify the value of the Identifier field in KUMA, in the Relying party identifiers field, when configuring domain authentication.

   Click Next to proceed to the next configuration step.

5. In the Apply Access Control Policy section that opens, select the Permit everyone policy value.

   Click Next to proceed to the next configuration step.

6. In the Configure Application Permissions section that opens, the Client application field is filled in automatically.

   In the Permitted scopes field, select the check box for the allatclaims and openid options.

   Click Next to proceed to the next configuration step.

7. In the Summary section that opens, check the settings.

   If the settings are correct and you are ready to add a group, click Next.

A new group is added. You can proceed to configure the rules for the created group.

Adding rules for a connection group

1. In Server Manager, in the Tools menu, select ADFS Management.

   In ADFS, select the Application groups section and select the required connection group from the list. Example: new-application-group.

2. In the Application groups window, in the Actions section, click Properties.

   In the new-application-group Properties window that opens, in the Applications section, double-click new-application-group - Web API.

   In the new-application-group - Web API Properties window that opens, open the

   Issuance Transform Rules

   tab and click Add rule.

   In the Add Transform Claim Rule Wizard window that opens, in the Choose Rule Type section, select Send LDAP Attributes as Claims from the drop-down list.

   Click Next to proceed to the next configuration step.

3. In the Configure Claim Rule section, specify the rule name in the Claim rule name field. Example: rule-name-01.

   In the Attribute store drop-down list, select Active directory.

   In the Mapping of LDAP attributes to outgoing claim types field, map the following fields:

   LDAP Attribute	Outgoing Claim Type
   User-Principal-Name	UserPrincipalName
   Display-Name	displayName
   E-Mail-Addresses	Mail
   Is-Member-Of-DL	MemberOf

   Click Finish to complete the configuration.

4. Go to the new-application-group - Web API Properties window, open the

   Issuance Transform Rules

   tab and click Add rule. In the Add Transform Claim Rule Wizard window that opens, in the Choose Rule Type section, select Send claims using a custom rule from the drop-down list.

   Click Finish to continue the configuration.

5. In the Configure Claim Rule section, specify the rule name in the Claims rule name field. Example: rule-name-02.

   In the Custom rule field, specify the following settings: 

   c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("ObjectGUID"), query = ";ObjectGUID;{0}", param = c.Value);

   Click Finish to complete the configuration.

6. The system proceeds to the new-application-group - Web API Properties window and the Issuance Transform Rules tab.

   To apply the rules, on the Issuance Transform Rules tab that opens, click Apply or OK.

The configuration of groups and rules in ADFS is completed. You can proceed to configure domain authentication in KUMA.

Troubleshooting the Access denied error

When you try to log in to KUMA using ADFS, the Access denied or Insufficient rights pop-up message may appear. The KUMA Core log shows the Data source certificate has been changed error.

This error indicates that the ADFS certificate is changed. To fix the error and resume domain authentication, update the certificate thumbprint saved in KUMA.

To update the certificate thumbprint on an Astra Linux or Oracle Linux host:

1. Contact Technical support to obtain the adfs_fingerprint_changer_tool binary file.
2. Place the received adfs_fingerprint_changer_tool binary file in any folder on the host with the KUMA Core. For example, /root/kuma-ansible-installer.
3. On the host with the KUMA Core, start the command line interpreter and use the cd command to go to the folder containing the adfs_fingerprint_changer_tool file.

   For example, you can enter the following command and press Enter:

   cd /root/kuma-ansible-installer

4. To grant the permissions to run a binary file and run the binary file, sequentially execute the following commands:

   chmod +x adfs_fingerprint_changer_tool

   ./adfs_fingerprint_changer_tool

To update the certificate thumbprint on a Kubernetes host:

1. Contact Technical support to obtain the adfs_fingerprint_changer_tool binary file.
2. Place the received adfs_fingerprint_changer_tool binary file in any folder on the computer of an administrator with access to the Kubernetes cluster and execute the following commands:

   k0s kubectl cp <path to adfs_fingerprint_changer_tool> $(k0s kubectl get pod -l app=core -n kuma -o name | cut -d/ -f2):/tmp/ -c mongodb -n kuma

   k0s kubectl exec $(k0s kubectl get pod -l app=core -n kuma -o name) -c mongodb -n kuma -- bash -c "chmod a+x /tmp/adfs_fingerprint_changer_tool && /tmp/adfs_fingerprint_changer_tool"

After you run the binary file, the certificate thumbprint is updated and the domain authentication by means of ADFS is again available.