Configuring the Security Token Service
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:
- 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. - In the Save As window, assign a name to the certificate and click Save.
- On the Security Token Service Configuration Console, click Site SSL.
- In the SSL Configuration page, select the SSL certificate that matches the certificate that you defined in IIS. Then click User Store Connection.
- 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 claim Choose this option Based on the domain user, submitted in this format: [email protected] Authenticate 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 [email protected], the UPN (User Principle Name) would be [email protected]
- If the account is [email protected], the UPN would be [email protected]
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 [email protected], the system returns user for this attribute.
Based on the user’s email address and UPN, submitted in this format: [email protected] LDAP 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: [email protected] 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.
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.Field Description Connection String Enter 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
Filter Here 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 Type Select 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 Credentials Enter 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. - 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
- Add or remove relying parties as needed.
- Click Logging.
- In the Logging Configuration page, make entries in the
following fields to specify how information is logged.
Field Description Log Level This 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. File Enter the file name and path for the log file or click Browse to select it. Maximum # Log Files The number you enter specifies how many log files to retain at one time. The default is 10. Maximum Log File Size The 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. - 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.
Previous topic Starting the Configuration Console Next topic Testing the service