Authentication using domain accounts

To enable users to perform authentication in the KUMA web interface using their own domain account credentials, perform the following configuration steps.

1. Enable domain authentication if it is disabled.

   Domain authorization is enabled by default, but a connection to the domain is not configured.

2. Configure a connection to the domain controller.

   The following connections are available:

   • Active Directory (AD)
   • Active Directory Federation Services (ADFS)
   • FreeIPA

   The AD and ADFS connection settings can be configured at the same time.

   You can connect to one domain only.

3. Add groups of user roles.

   You can specify a domain group for each KUMA role. After performing authentication using their domain accounts, the users from this group get access to the KUMA web interface in accordance with the specified role.

   The application checks whether the user's group matches the specified filter in the following order of precedence of roles in the KUMA web interface: Junior analyst → Tier 1 analyst → Tier 2 analyst → Tenant administrator → General administrator. Upon the first match, the application assigns a role to the user and does not check any further. If a user matches two groups in the same tenant, the role with the most privileges is used. If multiple groups are matched for different tenants, the user will be assigned the specified role in each tenant.

   After their first authentication, all domain users gain access to the default space, which is specified in the Spaces permissions section.

Special considerations for logging in after configuring domain authentication

For successful authentication, the following conditions must be met:

• FreeIPA: when logging into the system, the user must capitalize the domain name in the login. Example: user@FREEIPA.COM.
• AD/ADFS: when logging into the system, the user must specify UserPrincipalName in the login. Example: user@domain.ru.

If you complete all the configuration steps but the users are not able to use their domain accounts for authentication in the KUMA web interface, it is recommended to check the configuration for the following issues:

• An email address is not indicated in the properties of the user account in Active Directory. If this is the case, an error message is displayed during the user's first authentication attempt and a KUMA account is not created.
• There is already an existing local KUMA account with the email address indicated in the domain account properties. If this is the case, the error message is displayed when the user attempts to perform authentication with the domain account.
• Domain authorization is disabled in the KUMA settings.
• An error occurred when entering the group of roles.
• The domain user name contains a space.

Enabling and disabling domain authentication

Domain authorization is enabled by default, but a connection to the domain is not configured. If you want to temporarily suspend domain authentication after configuring a connection, you can disable it in the KUMA web interface without deleting the previously defined values of settings. If necessary, you can enable authentication again at any time.

To enable or disable domain authorization of users in the KUMA web interface:

1. In the application web interface, select Settings → Domain authorization.
2. In the Authorization type drop-down list, select one of the options:
   • FreeIPA
   • AD/ADFS
3. Do one of the following:
   • To disable domain authentication, select the Disabled check box in the upper part of the workspace.
   • To enable domain authentication, clear the Disabled check box in the upper part of the workspace.
4. Click the Save button.

The selected settings are saved and applied.

Configuring connection between KUMA and FreeIPA

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

To configure a connection to a FreeIPA domain controller:

1. In the application web interface, select Settings → Domain authorization.
2. In the Authorization type drop-down list, select FreeIPA.
3. Under FreeIPA, in the Base DN field, enter the DistinguishedName of the root record to search for access groups in the FreeIPA catalog service. Record format: dc=example,dc=com.
4. In the URL field, indicate the address of the domain controller in the format <hostname or IP address of server>:<port>.

   In case of server availability issues, you can specify up to three servers with domain controllers by separating them with commas. All of the specified servers must reside in the same domain.

5. If you want to use TLS encryption for the connection with the domain controller, select one of the following options from the TLS mode drop-down list:
   • startTLS.

     When the

     startTLS

     Text exchange protocol enhancement that lets you create an encrypted connection (TLS or SSL) directly over an ordinary TCP connection instead of opening a separate port for the encrypted connection.

     Text exchange protocol enhancement that lets you create an encrypted connection (TLS or SSL) directly over an ordinary TCP connection instead of opening a separate port for the encrypted connection.

     method is used, first it establishes an unencrypted connection over port 389, then it sends an encryption request. If the STARTTLS command ends with an error, the connection is terminated.

     Make sure that port 389 is open. Otherwise, a connection with the domain controller will be impossible.

   • LDAPS.

     When using LDAPS, an encrypted connection is immediately established over port 636.

   • insecure.

   When using an encrypted connection, it is impossible to specify an IP address as a URL.

6. If TLS encryption is enabled, the Secret field becomes required and you must specify a secret of the 'certificate' type in that field. If you previously uploaded a secret, select it from the Secret drop-down list. If necessary, click the button to create a new secret of the 'certificate' type and select the secret from the drop-down list.
7. In the Timeout in seconds field, indicate the amount of time to wait for a response from the domain controller server. The default value is 0.

   If multiple addresses are indicated in the URL field, KUMA waits for the specified number of seconds for a response from the first server. If no response is received during that time, the application contacts the next server. If none of the indicated servers responds during the specified amount of time, the connection will be terminated with an error.

8. In the Custom integration secret drop-down list, select a secret with the 'credentials' type.

   If you want to upload a new secret of the 'credentials' type, click the button on the right of the Custom integration secret drop-down list. This opens the Secret window; in that window, in the Name field, enter the name of the secret that will be displayed in the list after it is saved. In the User field, specify the DistinguishedName in the following format: uid=admin,cn=users,cn=accounts,dc=ipa,dc=test. Enter the Password and click Save.

   The secret is uploaded and becomes available for selection in the Custom integration secret drop-down list.

9. 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 FreeIPA group containing the user. Additional roles for the General administrator are automatically activated in KUMA, therefore, you do not need to add them separately.

   In the case when multiple groups are specified for a user in the same tenant, the role with the highest-level permissions is used, with additional roles, if additional roles are assigned.

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

10. Click the Save button.

A connection with the FreeIPA domain controller is now configured.

You can also check the connection for the previously entered domain controller connection settings.

To check the connection to the domain controller:

1. In the application web interface, select Settings → Domain authorization.
2. In the Authorization type drop-down list, select FreeIPA.
3. Under FreeIPA, select the relevant secret in the User credentials field.

   If necessary, you can create a new secret by clicking the button or change the settings of an existing secret by clicking the button. If integration with FreeIPA is enabled, the secret selection is always reset when the page is loaded.

4. Click Test.

   After clicking the Test button, the system tests the connection with the domain and returns a notification with the test results. The system does not check if the users can log in or if the user group is configured correctly.

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. Under Administration groups, click Add role groups.
3. In the Tenant drop-down list, select the tenant of the users for whom you want to configure domain authentication. The Shared tenant is displayed in the drop-down list, but you cannot assign a role to it because the only role in the Shared tenant is the Access to shared resources additional role, and additional roles do not participate in domain authentication.
4. In the Selected roles drop-down list, specify the roles for the user. You can select multiple roles. The following values are available:
   • Tenant administrator
   • Tier 2 analyst
   • Tier 1 analyst
   • Junior analyst

   After you select the roles, a group filter field is displayed for each role. In the fields for each role, specify the DistinguishedName of the domain group. The users of this domain group must have the capability to perform authentication with their domain accounts. Group input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

   You can define a separate set of role filters for each tenant.

   If no filter is specified for a role, this means that conditions for creating an account through domain authentication are not specified for that role. Authentication with that role is impossible.

   After the first authentication under a domain account, domain user cards are created for users in the Settings → Users section. For a domain user, the ability to change the main role (General administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Junior analyst) is blocked in the user card, while additional roles can be added or removed (Access to CII, Interaction with NCIRCC, Access to shared resources), including management of additional role assignment to tenants. Roles assigned in the Domain authorization section and roles assigned in the user card supplement each other. For the General administrator, additional roles in KUMA are automatically activated, therefore you do not need to add them separately. If the General administrator role was assigned to a domain user, and the General administrator role was subsequently revoked, additional roles must be reassigned in the user card in the Settings → Users section.

   You can specify only one domain group for each role. If you want to specify multiple groups, you must repeat steps 2 to 4 for each group while specifying 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: Junior analyst, Tier 1 analyst, Tier 2 analyst, or 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 between KUMA and Active Directory

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

To configure a connection to an Active Directory 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 group of settings, in the Base DN field, enter the DistinguishedName of the root record to search for access groups in the Active Directory catalog service.
4. In the URL field, indicate the address of the domain controller in the format <hostname or IP address of server>:<port>.

   In case of server availability issues, you can specify multiple servers with domain controllers by separating them with commas. All of the specified servers must reside in the same domain.

5. If you want to use TLS encryption for the connection with the domain controller, select one of the following options from the TLS mode drop-down list:
   • startTLS.

     When the startTLS method is used, first it establishes an unencrypted connection over port 389, then it sends an encryption request. If the STARTTLS command ends with an error, the connection is terminated.

     Make sure that port 389 is open. Otherwise, a connection with the domain controller will be impossible.

   • LDAPS.

     When using LDAPS, an encrypted connection is immediately established over port 636.

   • insecure.

   When using an encrypted connection, it is impossible to specify an IP address as a URL.

6. If you enabled TLS encryption at the previous step, add a TLS certificate:
   • If you previously uploaded a certificate, select it from the Secret drop-down list.

     If no certificate was previously added, the drop-down list shows No data.

   • If you want to upload a new certificate, click the button on the right of the Secret list. In the opened window, in the Name field, enter the name that will be displayed in the list of certificates after the certificate is added. Add the file containing the Active Directory certificate (X.509 certificate public keys in Base64 are supported) by clicking the Upload certificate file button. Click the Save button.

     The certificate will be uploaded and displayed in the Secret list.

7. In the Timeout in seconds field, indicate the amount of time to wait for a response from the domain controller server.

   If multiple addresses are indicated in the URL field, KUMA waits for the specified number of seconds for a response from the first server. If no response is received during that time, the application contacts the next server. If none of the indicated servers responds during the specified amount of time, the connection will be terminated with an error.

8. To configure domain authentication for a user with the KUMA general administrator role, specify the DistinguishedName of the Active Directory group the user belongs to in the General administrators group field. Additional roles for the General administrator are automatically activated in KUMA, therefore you do not need to add them separately.

   In the case when multiple groups are specified for a user in the same tenant, the role with the highest-level permissions is used, with additional roles, if additional roles are assigned.

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

9. Click the Save button.

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

You can also check the connection for the previously entered domain controller connection settings.

To check the connection to the domain controller:

1. In the application web interface, select Settings → Domain authorization.
2. In the Authorization type drop-down list, select AD/ADFS.
3. Under Test connection, select the relevant secret in the User credentials field.

   If necessary, you can create a new secret by clicking the button or change the settings of an existing secret by clicking the button.

   The following formats for specifying a user are available in the User field: UserPrincipalName and domain\user.

4. Click Test.

   After clicking the Test button, the system tests the connection with the domain and returns a notification with the test results. The system does not check if the users can log in or if the user group is configured correctly.

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. Under Administration groups, click Add role groups.
3. In the Tenant drop-down list, select the tenant of the users for whom you want to configure domain authentication. The Shared tenant is displayed in the drop-down list, but you cannot assign a role to it because the only role in the Shared tenant is the Access to shared resources additional role, and additional roles do not participate in domain authentication.
4. In the Selected roles drop-down list, specify the roles for the user. You can select multiple roles. The following values are available:
   • Tenant administrator
   • Tier 2 analyst
   • Tier 1 analyst
   • Junior analyst

   After you select the roles, a group filter field is displayed for each role. In the fields for each role, specify the DistinguishedName of the domain group. The users of this domain group must have the capability to perform authentication with their domain accounts. Group input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

   You can define a separate set of role filters for each tenant.

   If no filter is specified for a role, this means that conditions for creating an account through domain authentication are not specified for that role. Authentication with that role is impossible.

   After the first authentication under a domain account, domain user cards are created for users in the Settings → Users section. For a domain user, the ability to change the main role (General administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Junior analyst) is blocked in the user card, while additional roles can be added or removed (Access to CII, Interaction with NCIRCC, Access to shared resources), including management of additional role assignment to tenants. Roles assigned in the Domain authorization section and roles assigned in the user card supplement each other. For the General administrator, additional roles in KUMA are automatically activated, therefore you do not need to add them separately. If the General administrator role was assigned to a domain user, and the General administrator role was subsequently revoked, additional roles must be reassigned in the user card in the Settings → Users section.

   You can specify only one domain group for each role. If you want to specify multiple groups, you must repeat steps 2 to 4 for each group while specifying 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: Junior analyst, Tier 1 analyst, Tier 2 analyst, or 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 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. Under Active Directory Federation Services, 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. Additional roles for the General administrator are automatically activated in KUMA, therefore, you do not need to add them separately.

   In the case when multiple groups are specified for a user in the same tenant, the role with the highest-level rights is used, with additional rights, if additional roles are assigned.

   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.

If, when trying to log in to KUMA via ADFS, the user gets an Access denied pop-up message, click the Reset certificate button. A new certificate will be generated automatically.

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. Under Administration groups, click Add role groups.
3. In the Tenant drop-down list, select the tenant of the users for whom you want to configure domain authentication. The Shared tenant is displayed in the drop-down list, but you cannot assign a role to it because the only role in the Shared tenant is the Access to shared resources additional role, and additional roles do not participate in domain authentication.
4. In the Selected roles drop-down list, specify the roles for the user. You can select multiple roles. The following values are available:
   • Tenant administrator
   • Tier 2 analyst
   • Tier 1 analyst
   • Junior analyst

   After you select the roles, a group filter field is displayed for each role. In the fields for each role, specify the DistinguishedName of the domain group. The users of this domain group must have the capability to perform authentication with their domain accounts. Group input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

   You can define a separate set of role filters for each tenant.

   If no filter is specified for a role, this means that conditions for creating an account through domain authentication are not specified for that role. Authentication with that role is impossible.

   After the first authentication under a domain account, domain user cards are created for users in the Settings → Users section. For a domain user, the ability to change the main role (General administrator, Tenant administrator, Tier 2 analyst, Tier 1 analyst, Junior analyst) is blocked in the user card, while additional roles can be added or removed (Access to CII, Interaction with NCIRCC, Access to shared resources), including management of additional role assignment to tenants. Roles assigned in the Domain authorization section and roles assigned in the user card supplement each other. For the General administrator, additional roles in KUMA are automatically activated, therefore you do not need to add them separately. If the General administrator role was assigned to a domain user, and the General administrator role was subsequently revoked, additional roles must be reassigned in the user card in the Settings → Users section.

   You can specify only one domain group for each role. If you want to specify multiple groups, you must repeat steps 2 to 4 for each group while specifying 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: Junior analyst, Tier 1 analyst, Tier 2 analyst, or 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 has been changed. To fix the error and resume domain authentication, in domain controller connection settings, click the Reset certificate button. A new certificate will be generated automatically.