IBM InfoSphere Streams Version 4.1.0

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, InfoSphere® 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 InfoSphere 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.
Note: This scenario applies to the InfoSphere Streams REST API only when you are accessing it from a browser and did not already log on by using the Streams Console in the same browser session.

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 InfoSphere 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 InfoSphere 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. 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, enter the streamtool getzk -d domain-id 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 InfoSphere 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.ibm.com
Organizational unit	OU	InfosphereStreams
Organization	O	IBM
City	L	Raleigh
State	ST	NC
Country	C	US

The following pattern specifies that InfoSphere 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, InfoSphere 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 InfoSphere Streams tests for a user ID of RobertSmith@Rochester@MN.

The following pattern specifies that InfoSphere Streams constructs the user ID from a portion of the DN email address value:

${EMAILADDRESS,(us.ibm.com),us}

To construct the user ID based on this pattern, InfoSphere Streams performs the following operations:

Extracts the EMAILADDRESS value (resmith@us.ibm.com).
Replaces us.ibm.com with us.

The result is that InfoSphere Streams tests for a user ID of resmith@us.