Skip to main content

Configuring the Security Token Service

Suggest edit Updated on November 10, 2021
Pega Robot Studio v21 Preview

When using the Security Token Service for authentication with Robot Manager, you must share the token-signing certificate from the Security Token Service with the Pega Platform. Follow these steps to configure the Security Token Service:

  1. Click Token Signing, and select the appropriate token-signing certificate from the list. Then click Export Public Cert.

    Configuration Console

    Note: If you are using Robot Manager, this certificate is imported to the Pega Platform.
  2. In the Save As window, assign a name to the certificate and click Save.
  3. On the Security Token Service Configuration Console, click Site SSL.
  4. In the SSL Configuration page, select the SSL certificate that matches the certificate that you defined in IIS. Then click User Store Connection.
  5. In the User Store Connection Configuration page, select the type of user store. To work with Robot Manager, you typically choose the Authenticate By Username Only option. Choose from the following options:
    If you want the system to submit a claimChoose this option
    Based on the domain user, submitted in this format: User@localdomainAuthenticate By Username Only
    When you choose this option, the system does not look up users using LDAP or Active Directory. The following are some examples:
    • If the account is user1@it.domain.com, the UPN (User Principle Name) would be user1@IT
    • If the account is user1@domain.com, the UPN would be user1@DOMAIN
    Keep in mind...
    • The domain is in all caps if you choose the Authenticate by Username Only option.
    • A more specific base directory path can speed user lookup if it limits the number of users who can be searched.
    • You can also authenticate by using the UserName attribute. For example, if the user is user@domain.com, the system returns user for this attribute.
    Based on the user’s email address and UPN, submitted in this format: user@localdomain.fulldomain.comLDAP or Active Directory
    When you choose this option, the system does not look up users using only the user name.
    Note: Choose the Authenticate By Username Only option if the user search in AD/LDAP causes performance issues. The user must still be authenticated in the Windows domain. However, rather than querying AD/LDAP for the claim attributes of UPN and email address, the system uses the domain credentials to create a pseudo User Principal Name (UPN). The usual UPN format is: username@department.company.com

    When you enable the LDAP lookup, both the email and UPN claims are provided and can be used to match a user in Robot Manager.

    When you only use AuthByUsernameOnly, the UPN is formatted as shown below and the matching UPN for users imported into Robot Manager must match accordingly.

    username@DEPARTMENT

    Note that DEPARTMENT is in all capital letters.

    If you choose the LDAP or Active Directory option, additional fields appear so you can define the Lightweight Directory Access Protocol (LDAP) connection settings.

    LDAP Connection Settings

    Your entries determine how LDAP connections are made.
    FieldDescription
    Connection StringEnter the connection string, including the user store server name or IP and base directory path. The following is an example: LDAP://(ServerName)/dc=dept,dc=customer,dc=com
    FilterHere you can specify a filter that you want to use to restrict authorized users. You can use AND (&) and OR to compound the criteria for the filter. The following is an example: (&(memberof=CN=GroupName)(objectClass=user))
    The default is (objectClass=user).
    Encode the following symbols when used in the LDAP filter in the web.config App Setting.
    • Encode ampersands (&) as &
    • Encode quotation marks (“) as "
    • Encode less than (<) symbols as <
    • Encode greater than (>) symbols as >
    Authentication TypeSelect the authentication method you want to use. You can choose from these options.
    • Application Pool Identity — Choose to connect to the user store with the user who is running the service.
    • Specific User — Choose to connect to the user store with a specific ID and password. If you choose this option, the User Credential fields appear.
    User CredentialsEnter the LDAP user name and password.
    After you make the appropriate entries, click Test Connection to ensure that you can connect. If you are unable to connect, check your entries.
  6. Click Relying Party. The Relying Party Configuration page appears.
    The Security Token Service allows for authentication with multiple relying parties. You must configure the required attributes for each party.

    Relying Party configuration

    A relying party is an external resource. The Security Token Service allows security tokens to be generated for the relying parties that you specify here. Replace this default with your permalink URL: https://myserver.pega.com/prweb
  7. Add or remove relying parties as needed.
  8. Click Logging.
  9. In the Logging Configuration page, make entries in the following fields to specify how information is logged.
    FieldDescription
    Log LevelThis field determines the amount of information the system includes in the log files. You have these choices:
    • All — This level records all output.
    • Debug — This level records error, warning, informational messages, and verbose debugging output. This option generates a large number of messages and is not recommended when used with multiple trace source selections.
    • Error — This level records error messages, indicating the application was not able to perform a task as expected. The Security Token Service is, however, still running.
    • Fatal — This level records negative events that indicate unexpected processing or an error. Only certain unhandled exceptions are reported.
    • Info — This level records error, warning, and informational messages. It includes successful milestones of application execution, regardless of whether the Security Token Service is working properly, and provides an overview of what happened.
    • Warn — This level records both error and warning messages.
    The default is Info.
    FileEnter the file name and path for the log file or click Browse to select it.
    Maximum # Log FilesThe number you enter specifies how many log files to retain at one time. The default is 10.
    Maximum Log File SizeThe number you enter specifies how large, in megabytes, a log file can be before the system starts another log file. For instance, if you enter 10 here, after the log file grows to 10 megabytes, the system starts a new log file.
    The default is 10mb.
  10. When finished, choose File > Save to save your changes. Then, close the console.Result: This completes the configuration of the Security Token Service. You can make changes to this configuration as needed. After saving the configuration, you are prompted to test the service.
Did you find this content helpful? YesNo

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us