Setting the user ID pattern for certificate authentication

Certificate authentication uses client authentication to authenticate the client connection, and then extracts information from the distinguished name (DN) of the client certificate to authenticate users. By default, Teracloud® Streams checks for a user ID in the DN common name (cn) field.

  • If the user ID is valid and is authorized to access the Teracloud® Streams domain or instance, you can authenticate without having to enter a user ID and password.

  • If the user ID is not valid, you are prompted for a user ID and password.
You can use other DN field values to authenticate users by updating the pattern in the security.certificateUserRegularExpression domain property. This pattern uses a regular expression substitution, for example: ${element[, regex, replacement]}. This expression allows flexibility in constructing user IDs. For example, you can use the following patterns:
  ${element}
  ${element, regex, replacement}

About this task

The user ID pattern is a pattern that consists of reserved keywords and regular expressions. This pattern specifies the DN information that Teracloud® Streams uses to construct a user ID for certificate authentication.

Restriction: If existing client certificates do not contain user information in any of the DN fields, you must create a new client certificate to use certificate authentication.

For more information about the streamtool commands in the following procedure, enter streamtool man command-name. For more information about the security.certificateUserRegularExpression property, enter streamtool man domainproperties.

Procedure

  • To display the user ID pattern that is being used by Teracloud® Streams, enter the following command:
    streamtool getdomainproperty -d domain-id --zkconnect host:port security.certificateUserRegularExpression
    • The -d option specifies the domain identifier. If the STREAMS_DOMAIN_ID environment variable is set to this value, you do not need to specify the -d option on the command.

    • The --zkconnect option specifies the name of one or more host and port pairs for the configured external ZooKeeper ensemble. If you specify multiple host and port pairs, separate each pair with a comma. This value is the external ZooKeeper connection string. If the STREAMS_ZKCONNECT environment variable is set to this value, you do not need to specify the --zkconnect option on the command. To obtain this value, you can use the streamtool getzk command.

    The default command output shows the usage of the cn for the user name, for example: 
    security.certificateUserRegularExpression=${cn}
  • To update the user ID pattern, enter the following command: 
    streamtool setdomainproperty -d domain-id --zkconnect host:port security.certificateUserRegularExpression=EMAILADDRESS

Example

This example shows how to update the default pattern to construct the user ID from DN field values other than the default cn field value.

The client certificate in this example contains the DN information in the following table. By default, ${cn} is used for the user ID pattern, which indicates that Teracloud® Streams uses RobertSmith as the user ID for certificate authentication.

Table 1. Streams Console example: DN information in the client certificate
User information DN field DN value
Common name of the certificate owner cn RobertSmith
Email address of the certificate owner EMAILADDRESS resmith@us.teracloud.com
Organizational unit OU TeracloudStreams
Organization O Teracloud®
City L Raleigh
State ST NC
Country C US
The following pattern specifies that Teracloud® Streams constructs the user ID from the DN common name, city, and state values, and that different values are substituted for the city and state:
${cn}@${L,Raleigh,Rochester}@${ST,NC,MN}
To construct the user ID based on this pattern, Teracloud® Streams performs the following operations:
  • Extracts the cn value (RobertSmith).
  • Appends the L value (Raleigh) and replaces Raleigh with Rochester.
  • Appends the ST value (NC) and replaces NC with MN.
The result is that Teracloud® Streams tests for a user ID of RobertSmith@Rochester@MN.
The following pattern specifies that Teracloud® Streams constructs the user ID from a portion of the DN email address value: 
${EMAILADDRESS,(us.teracloud.com),us}
To construct the user ID based on this pattern, Teracloud® Streams performs the following operations:
  • Extracts the EMAILADDRESS value (resmith@us.teracloud.com).
  • Replaces us.teracloud.com with us.
The result is that Teracloud® Streams tests for a user ID of resmith@us.