Configuring authentication with application password support

1. Shut down the Engineering Lifecycle Management servers, but leave the JAS running.
2. In the server/conf/jts/teamserver.properties file, find the value of the com.ibm.team.repository.servlet.sso_clientId property and copy it (to the clipboard).
3. Change the value of the com.ibm.team.repository.servlet.sso_clientSecret property to a new secret value. The value should NOT be surrounded by square brackets. For example, if you use MyJtsS3cret as the new secret, the property entry is displayed as:com.ibm.team.repository.servlet.sso_clientSecret=MyJtsS3cret.
4. Go to the /oidc/endpoint/jazzop/clientManagement page in JAS.
5. Click on Edit for the Jazz® Team Server entry.
6. In the Client secret field, change the asterisk to your new secret value, click Update, then click Done.
7. Edit JazzAuthServer/wlp/usr/servers/jazzop/appConfig.xml to specify the new JTS client ID and secret in the <oauthProvider> element. Add them as attributes named internalClientId and internalClientSecret. For example, if the JTS client ID was "0df15df2eaf14f968596d0d7a7c2df0c", and you changed the secret to "MyJtsS3cret", the <oauthProvider> element is displayed as:

   <oauthProvider id="JazzOP"
      httpsRequired="true"
      autoAuthorize="true"
      customLoginURL="/jazzop/form/login" 
      accessTokenLifetime="7201" 
      authorizationGrantLifetime="604801"
      internalClientId="0df15df2eaf14f968596d0d7a7c2df0c"
      internalClientSecret="MyJtsS3cret"
      passwordGrantRequiresAppPassword="true">
      <databaseStore dataSourceRef="OAuthFvtDataSource" /> 
   </oauthProvider>

8. You can also add the appPasswordLifetime attribute to the <oauthProvider> element to change the time that an application password remains valid. The default value is "90d" (90 days). See OAuth Provider Definition (oauthProvider) in the IBM WebSphere Liberty knowledge center for more details.
   Note: You have the option of encoding the internalClientSecret value so that it is not readily visible. To do that, set a command shell to the JazzAuthServer/wlp/bin folder and execute the command using your new secret value instead of the example "MyJtsS3cret":

   securityUtility encode MyJtsS3cret
   {xor}EiYVKywMbDwtOis=

   Copy the output string (for example, "{xor}EiYVKywMbDwtOis=") and set it as the value of the internalClientSecret attribute.
9. To allow an administrator to be able to revoke application passwords for users, find the <oauth-roles> element in the appConfig.xml file and add an additional child element. For example:

   <tokenManager>
      <group name="JazzAdmins" />
   </tokenManager>

   There are several ways to specify which users or groups are granted the "token manager" role (see the tokenManager). It works the same way as the existing <clientManager> element, which is set to grant the role to the JazzAdmins group as well. If that element is customized, it is recommended to configure the <tokenManager> element the same way. The final <oauthRoles> element is displayed as the following ():

   <oauth-roles>
      <authenticated>
         <special-subject type="ALL_AUTHENTICATED_USERS" />
      </authenticated>
      <clientManager>
         <group name="JazzAdmins" />       
      </clientManager>      
      <tokenManager>
         <group name="JazzAdmins" />       
      </tokenManager>         
   </oauth-roles>

   It is assumed that the default configuration of JazzAdmins being administrators is used.
10. Change the <authFilter> element to require delegated authentication for the Personal Token Management UI and for clients that support application passwords. The <authFilter> element for each type of supported delegated authentication contains the child elements <requestUrl> and <userAgent>. In <requestUrl>, change the urlPattern attribute value from /authorize to /authorize|/personalTokenManagement. In the <userAgent> element, change the agent attribute value from Mozilla|Opera to Mozilla|Opera|app-password-enabled. The two elements should look like this when finished:

    <requestUrl id="samlRequestUrl" urlPattern="/authorize|/personalTokenManagement" matchType="contains" />
       <userAgent id="samlUserAgent" agent="Mozilla|Opera|app-password-enabled" matchType="contains"/>

    Note: You can also set delegated authentication for the administrator's token management UI by changing the urlPattern value to /authorize|/personalTokenManagement|/usersTokenManagement.
11. After making all the changes, restart the JAS server. Verify that going to <JAS-root-URL>/oidc/endpoint/jazzop/personalTokenManagement redirects to your external identity provider for authentication. Verify that going to <JAS-root-URL>/oidc/endpoint/jazzop/usersTokenManagement redirects to your external identity provider for authentication, if configured to do so. From this point on, any clients that are application-password enabled (that is, the EWM Eclipse IDE, repotools commands, SCM CLI, build engines, all other clients that are built on the Foundation Repository client libraries, and any other clients that have implemented support as well) will require an application password to connect to a server - they will not work with user passwords.

Converting a pre-7.0.2 installation to support application passwords involves all the steps that are required for a new installation, plus a couple of additional steps.

1. Set a command shell to the JazzAuthServer/cli directory.
2. Dump the client registration data to a file by executing the lsclient -u username:password> client-reg.json command, where "username:password" is replaced by your administrator username and password, which is separated by a colon.
3. Edit the client-reg.json file. Change false to true in each line that has the "appPasswordAllowed" : false, text.
4. In every line that starts with grant_types, add password to the list of values. That is, change "grant_types" : [ "authorization_code", "client_credentials", "implicit", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer" ], to "grant_types" : [ "authorization_code", "client_credentials", "implicit", "password", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer" ],.
   It does not matter where in the list it is added; the output is alphabetically ordered.
5. Load the modified client registration data back into the JAS by executing the ldclient -u username:password client-reg.json command.