› System › Additional settings › Logon and authentication › Federated security › Configure the federated security

Configure the federated security

Configure the federated security by adding the authentication provider, configuring user claims rules, specifying the SAML request to the Identity provider signed with a certificate, and adding certificates to decrypt an encrypted SAML assertion.

  1. Navigate to System > Additional settings > Logon and authentication > Federated security.
    The Federated security dialog box is displayed.
  2. The federated security is clear by default. You can enable Use federated security only when an active authentication provider is configured.
  3. Optional. Select Overwrite existing session to overwrite an existing session without displaying the overwrite confirmation message at runtime. (Default: Clear)
  4. To configure an authentication provider, select .

    The Add authentication provider dialog box is displayed.

  5. Configure the following settings on the General tab:
    1. Enter a display Name for the authentication provider.
    2. On the Endpoint type list, select one of the following options and configure the settings.

      • WS-Federation (default)

        Setting Description
        Endpoint URL

        Specify the provider's WS-Federation endpoint URL.

        Relying party

        Optional. Specify the URL for the relying party.

        If you provide the relying party identifier in the Federated Security provider as https://<servername>/TotalAgility/ for TotalAgility On-Premise / On-Premise Multi-Tenant environments and https://<servername>// for TotalAgility Azure , you need not specify the relying party URL when configuring the federated security in TotalAgility. If you provide a different relying party identifier in the Federated Security provider, make sure that the identifier provided in the Federated Security provider matches the relying party URL specified in TotalAgility. The relying party identifier is for ADFS (Active Directory Federation Services), and the APP ID URI is for Azure Active Directory. If you do not specify the relying party identifier in TotalAgility Azure, you must specify the APP ID URI.

      • SAML

        Setting Description
        Endpoint URL

        Specify the provider's SAML endpoint URL.

        Binding type

        On the Binding type list, select an authentication request type:

        • HTTP-Redirect (default): SAML request is sent as an HTTP request query string parameter.
        • HTTP-Post: SAML request is sent in the HTTP request body and the signature is embedded.

        Authentication context

        Select the authentication context to use, such as Password protected transport. (Default: Any)

        Relying party

        Optional. Specify the URL for the relying party.

        If you provide the relying party identifier in the Federated Security provider as https://<servername>/TotalAgility/ for TotalAgility On-Premise / On-Premise Multi-Tenant environments and https://<servername>// for TotalAgility Azure , you need not specify the relying party URL when configuring the federated security in TotalAgility. If you provide a different relying party identifier in the Federated Security provider, make sure that the identifier provided in the Federated Security provider matches the relying party URL specified in TotalAgility. The relying party identifier is for ADFS (Active Directory Federation Services), and the APP ID URI is for Azure Active Directory. If you do not specify the relying party identifier in TotalAgility Azure, you must specify the APP ID URI.

      • OpenID Connect

        Setting Description
        OAuth server

        Select the OAuth server that is configured with authorization code grant type, and supports PKCE flow and OpenID.

        Use this OAuth server when configuring MCP Servers for Generative AI chat control for proper OpenID Connect authentication.

        JSON web key set URL

        Specify the URL of the key publisher.

    3. Specify the Issuer identity of the provider.

      At runtime, this identity helps to verify that any claims passed to TotalAgility are from the correct provider.

    4. Specify the Sign out URL.

      When you log off the provider, the specified URL opens.

    5. Select either setting to specify the Logout option:

      • TotalAgility and Provider: Logs you out of the provider and TotalAgility.

      • TotalAgility (default): Logs you out of TotalAgility.

    6. To specify that the authentication provider is active, select Active. (Default: Clear)
    7. Relay state is used to communicate the state when the message is passed to/from the identity provider and service provider.

      • By default, TotalAgility keeps using both the query string parameters and the relay state (depending on whichever works). Relying on query string parameters in the Assertion Consumer Service (ACS) URL can cause issues with providers that require an exact match of the ACS URL.

      • If the provider supports only the relay state, you must select Relay state only. In this case, TotalAgility does not include any query string parameters in the ACS URL and will rely solely on the relay state setting. This is the recommended way to relay data between the application and provider.

        The "Relay state only" option is available only if you select "SAML" on the Endpoint type list.

  6. To provide response signature verification certificates, do the following:
    1. Select the Response validation tab.
    2. Enter the three different public keys of the provider in the Certificate1, Certificate2 and Certificate3 fields.

      To view the certificate details, such as Issued to, Issued by, and Validity period, select View certificate, enter password, and then select Get details.

      You must provide at least one certificate.
      At runtime, all three certificates are used to verify that the claims passed are from the correct provider. If validation is passed for at least one certificate, the response is considered valid.
  7. To determine how an existing user is found in TotalAgility when you log on using the authentication provider, do the following:
    1. Select the User claims mappings tab.

      User claim mappings apply if the user does not exist in TotalAgility.

    2. Match the user to the username (default) or email. Select either option for Match to:

      Option Procedure

      User name

      1. By default, the username is taken from the security token.

      2. For Name and Email address, select Enter on login to enter the name manually at runtime, or select From security token to take the name from a security token.

      Email

      1. For User name and Name, select Enter on login to enter the name manually at runtime or select From security token to take the name from a security token.

      2. The Email address is taken from the security token (Default).

    3. Select Save.
  8. To define a set of rules for specifying the TotalAgility category and groups to which a new user is added after being successfully authenticated with the provider, select the User claims rules tab, and do the following:
    If the claims or user claim rules are modified, TotalAgility automatically updates the working group and group membership of the resource.
    1. Select a Category and a Working category.
    2. Optional. Select a Working group.
    3. Select Use custom user rules and define the rule:

      1. Select .

        The Add custom user rule dialog box is displayed.

      2. Enter a rule Name for the claim.

      3. Specify the Claim type and Claim value.

      4. To specify the category the user is added to if the custom rule is satisfied, select a Category.

      5. To specify the Working category the user is added to if the custom rule is satisfied, select a category.

      6. To specify the Working group the user is added to if the custom rule is satisfied, select a group.

        • Specify at least one of the preceding optional settings for a custom user rule.

        • Whenever you create or update a group by adding or removing a user, an audit log entry is recorded that includes the username and the associated group name.

      7. Optional. To add the resource groups the user is added to if the custom rule is satisfied, select Add for Groups.

        The Add associated groups dialog box is displayed.

      8. Select the required groups to add and then select Done.

        The Add custom user rule dialog box is displayed.

        The custom user rules take precedence over the default user claim rules.

      9. Select Save.

        The rule appears in the table with the rule name and claim-type details. You can modify or delete the custom rules.

    4. The Refresh group membership on logon setting allows the group membership for a user to refresh automatically based on the user claims and user claim rules if either of these has changed since the user last logged on.

      This setting is selected by default. On upgradingTotalAgility from earlier versions, this setting is clear for the existing federated security providers.

    5. On the Process list, select a process that is configured with the "ResourceId" string variable as an initialization parameter. Alternatively, select the Create new process hyperlink to create a new process. The newly created process appears on the Business processes list page, and the system automatically adds the "ResourceId" string variable as an initialization parameter to the process.

      When a TotalAgility resource is automatically added at runtime during federated security logon, the system creates a job based on this process, passing in the resource ID.

  9. To configure and specify the SAML request to the Identity provider signed with a certificate, do the following:
    1. Select the Signature settings tab.
      This tab is available only if the Endpoint type setting on the General tab is SAML.
    2. Browse the certificate (containing private key) you want to upload to sign the SAML request.
    3. Enter the Password to decrypt the certificate.
    4. On the Algorithm list, select the algorithm you want to use for signing, such as RSA-SHA1.
      The signing algorithm must match the algorithm the identity provider is configured with.
    5. Optional. To view the certificate details, such as to whom it is issued to, who has issued it, and validity period, select View certificate, enter the password, and then select Get details.
    6. Select Save.
      The SAML request is signed.
  10. To decrypt an encrypted SAML assertion, do the following:
    1. Select the Response decryption tab.
      This tab is available only when the Endpoint type setting on the General tab is SAML.
    2. Browse the assertion certificate (containing decryption details) you want to upload for decrypting SAML assertion.
    3. Set a Password for the certificate.

      You can upload up to three assertion certificates and at least one must have the correct decryption details.

    4. Optional. To view the certificate details, such as to whom it is issued to, who has issued it, and validity period, select View certificate, enter the password, and then select Get details.
    5. Select Save.
  11. Select Save.
  12. Select Use federated security.
    If Federated security is being used on the Azure tenant and connected to an Integration server, the Integration server will also use the same security settings. You must restart the TotalAgility Application pool on the Integration server for the new Azure tenant configuration settings to take effect.
  13. Select Close.

Launch the TotalAgility Advanced Studio using Federated security

Once the authentication provider is added and Federated security is enabled, the user is redirected to configured authentication provider URL upon logging on to TotalAgility Advanced Studio.

If multiple authentication providers are configured, the user can select one and the Authentication Provider Logon page opens.

Once the user is authenticated by the provider, the user gets logged on to TotalAgility:

  • If the user exists in TotalAgility and matches a TotalAgility user using the claims mappings, the user gets logged on to TotalAgility.

  • If the user does not exist in TotalAgility, a user is added based on the user claim rules and then gets logged on to TotalAgility.

Launch the TotalAgility Advanced Studio in recovery mode

If the Federated security was configured incorrectly, you can launch the TotalAgility Advanced Studio in Recovery mode and modify the Federated security configuration.

  1. Use the following URL: http://<server name>/TotalAgility/Designer/#/logon/recovery.
  2. Specify the Recovery mode session ID and select Validate.

    The recovery mode session ID is unique and is stored in System Settings > User sessions in the TotalAgility Advanced Studio.

  3. Enter a valid Username and Password and select Login.

    To log in with recovery mode, in addition to the access permissions for TotalAgility Advanced Studio, you must also have Read write or Full control access permissions in the Access control list for the settings. See Assign access permissions to different areas of TotalAgility.