Workaround: OAuth consumer key issues in the Requirements Management application 4.0

Bas Bekker
Last Updated: February 20, 2013
Build Basis: Rational Requirements Composer 4.0

Summary

When you configure or upgrade the server, problems can occur that make the server unusable. To address these issues, you must troubleshoot the OAuth consumer key that is stored in Requirements Management (RM) server OAuth configuration file and the Jazz Team Server database. The RM server uses the OAuth keys to communicate with Jazz Team Server and gain access to the storage areas in the database.

More Information

Incorrect OAuth configurations typically have these symptoms:

1. Errors in the server/logs/rm.log file. For example, if you receive the following error, the consumer might not be registered: "CRJZS0033E Invalid consumer key."
2. User interface controls are disabled in the Jazz Team Server setup wizard on the RM finalize page. If the user interface controls are disabled, this message is displayed: "CRRRS3006E The user ID you are currently using is not authorized to finalize this application. Another possibility is that you are not authorized to configure already existing RM storage areas on the Jazz Team Server. The OAuth consumer key for this application should be unique and match the existing storage areas."
3. When you open the web client for the RM application, this error message is displayed: "CRJZS0033E The consumer key is not valid and the consumer may not be registered."

To determine whether problems exist with the OAuth consumer key, check the differences between the OAuth consumer keys on the Jazz Team Server database and the RM OAuth configuration file on the server.

• To view the consumer key on the database, go to https://server:9443/jts/admin#action=com.ibm.team.repository.admin.configureOAuth, and in the Authorized Keys section, check the /rm consumer key value name.
• To view the consumer key the RM OAuth configuration file, open the serverconfrmfriendsconfig.rdf file and check the <jfs:oauthConsumerKey> tag.

If you see differences, the RM application OAuth configuration is no longer synchronized with the Jazz Team Server database. This consumer key mismatch is manifested in different ways:

• The RM application has a consumer key in its serverconfrmfriendsconfig.rdf file, but an RM consumer entry is not on the database.
• The RM application does not have a consumer key in its serverconfrmfriendsconfig.rdf file, but an RM consumer entry is on the database.
• The RM application has a consumer key in its serverconfrmfriendsconfig.rdf file, and an RM consumer key entry is on the Jazz Team Server database, but the keys do not match.

Attention: If the OAuth consumer key is not on the database because you removed, or unregistered, the RM application and you register the RM application again, the re-registered application cannot access the project area data that was created in the removed application. This data cannot be recovered.

Workaround

If the RM application has a consumer key in its serverconfrmfriendsconfig.rdf file, but an RM consumer key entry is not on the database, follow these steps:

1. In the friendsconfig.rdf file, remove the friend entry. After removal, the file should look like this XML fragment:
   <rdf:RDF
   xmlns:jfs="http://jazz.net/xmlns/prod/jazz/jfs/1.0/"
   xmlns:dc="http://purl.org/dc/terms/"
   xmlns:jd="http://jazz.net/xmlns/prod/jazz/discovery/1.0/"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
   </rdf:RDF>
   
2. Restart the RM server, and run the Jazz Team Server setup wizard again.

If the RM application does not have a consumer key in its serverconfrmfriendsconfig.rdf file, but an RM consumer key entry is on the database, follow these steps to manually add the entry:

1. Create a .rdf file.
2. In the new file, copy the following contents, and then save the file as friendsconfig.rdf:
   <rdf:RDF
      xmlns:jfs="http://jazz.net/xmlns/prod/jazz/jfs/1.0/"
      xmlns:dc="http://purl.org/dc/terms/"
      xmlns:jd="http://jazz.net/xmlns/prod/jazz/discovery/1.0/"
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <jd:Friend>
      <jfs:internal>false</jfs:internal>
      <jfs:oauthConsumerSecret>samplesecretvalue</jfs:oauthConsumerSecret>
      <jfs:oauthConsumerKey>samplekeyvalue</jfs:oauthConsumerKey>
      <jfs:oauthDomain>https://server:9443/jts</jfs:oauthDomain>
      <dc:title>RRS_JFS</dc:title>
      <jd:rootServices rdf:resource="https://server:9443/jts/rootservices"/>
    </jd:Friend>
   </rdf:RDF>
   
3. Make these changes to the file:
   1. For the public URL of Jazz Team Server, use <jfs:oauthDomain>.
   2. For the rootservices URL of Jazz Team Server, use <jd:rootServices>.
   3. Obtain the <jfs:oauthConsumerKey> and <jfs:oauthConsumerSecret> values:
      1. Open the Jazz web administration pages at https://server:9443/jts/admin#action=com.ibm.team.repository.admin.configureOAuth.
      2. To obtain the oauthConsumerKey value, in the Authorized Keys section, for the RM consumer, click Edit. Then, copy the consumer key value.
      3. To obtain the oauthConsumerSecret value, you must set a new value:
         1. In the Authorized Keys section, for the RM consumer, click Edit.
         2. 2.Enter a new value for the consumer secret, copy that value, and then click Finish.
4. Save the file, and then restart the RM server so that the changes will go into effect.

If the RM application has a consumer key in its serverconfrmfriendsconfig.rdf file and an RM consumer key entry is on the Jazz Team Server database but the keys do not match, follow these steps. In this case, you restore the consumer key in the friendsconfig.rdf file to match the consumer key and consumer secret in the Jazz Team Server database.

1. Open the Jazz web administration pages at https://server:9443/jts/admin#action=com.ibm.team.repository.admin.configureOAuth.
2. Obtain the oauthConsumerKey value:
   1. In the Authorized Keys section, for the RM consumer, click Edit.
   2. 2.Copy the consumer key value.
3. Obtain the oauthConsumerSecret value by setting a new value:
   1. In the Authorized Keys section, for the RM consumer, click Edit.
   2. Enter a new value for the consumer secret, and then click Finish.
4. Enter the values that you obtained into the serverconfrmfriendsconfig.rdf file, and then restart the server.

If the RM application has a consumer key in its serverconfrmfriendsconfig.rdf file and an RM consumer key entry is on the Jazz Team Server database but the keys do not match, restore the consumer key in the friendsconfig.rdf file to match the consumer key and consumer secret in the Jazz Team Server database, as described in the previous section.

After you complete those steps, if you still cannot access the RM application project areas, reset the consumer key for the RM storage areas in the Jazz Team Server database: To fix the consumer key of the affected storage areas, use a repotools-jts command. The parts of the command are as follows:

-listStorageAreaKeys: Lists the authorization consumer keys for each storage area, including archived storage areas.
[toFile=*]: The path to the file that the list is exported to. The format of the file is a comma-separated list of storage area names and consumer keys.
-setStorageAreaKeys: Sets the authorization consumer keys for the given storage areas.
[list=*]: A comma-separated list of storageAreaName-consumerKey pairs, without spaces. For example: storageArea1,key1,storageArea2,key2
[fromFile=storageAreaKeys.csv]: The path to the file that contains the storage area keys to set. The format of the file is a comma-separated list of storage area names and consumer keys.

To run the command to fix the consumer key, follow these steps:

1. Stop the RM server.
2. From a command prompt, navigate to the /server directory.
3. Enter this command: repotools-jts -listStorageAreaKeys toFile=keys.csv
4. Open the keys.csv file, and then change the old key value to the new one. This value is the oauthConsumerKey value in the serverconfrmfriendsconfig.rdf file.
5. Save and close the file.
6. Enter this command: repotools-jts -setStorageAreaKeys fromFile=keys.csv
7. Start the RM server. The database should be synchronized with the RM application.