Enable Applications Passwords for Non-Web Clients on JAS Configured with Third Party SAML/OIDC Providers

Authors: ShubjitNaik
Build basis: Engineering Lifecycle Management Solution 7.0.2 and Higher

Configuring Engineering Lifecycle Management (ELM) to authenticate via corporate SAML IDP or OIDC Provider is a common request from our clients as it allows for Multi-factor authentication. Until version 7.0.1 this authentication flow was possible via Jazz Authorization Server (JAS) and it worked only for Web Clients and the Non-web clients authenticated directly via JAS.

Starting ELM and JAS version 7.0.2, a new type of authentication flow is being provided for Non-web (native) clients connecting to ELM applications that are configured with Jazz Authorization Server delegated to a third party Identity provider via SAML or OIDC.

Details about the feature is available on Liberty application password feature and our Development Wiki Article.

The focus on this article is to provide simple instructions on enabling App Passwords on Jazz Authorization Server configured to delegate authentication to third party identity Providers via SAML or OIDC, without changing the configuration on the ELM Applications.

High Level Instructions

Pre-Req: Jazz Authorization Server is configured to delegate authentication to a third party Identity Provider Via SAML or OIDC

• Register a new Client for Application password configuration
• Configure Jazz Authorization Server to enable Application passwords
• Allow Application password and Password grant type for ELM Applications registered in JAS
• Generate Application password as a User

Register a new Client for Application Password configuration

To enable Application password in JAS, the configurations needs a ClientId and a Secret. We can reset the Client Secret of one of the ELM application, example JTS and use those credentials in the JAS config. But to minimize changes to the ELM application configurations, we will create a new ClientId and Secret which will solely be used for the Application password configurations.

Here is a sample app.json file to create a new Client in JAS.

{
  "registration_client_uri" : "https://<JASURI>/oidc/endpoint/jazzop/registration/AppPasswordClientId",
  "client_id" : "AppPasswordClientId",
  "client_secret" : "AppPasswordClientPassword",
  "publicClient" : false,
  "application_type" : "web",
  "appPasswordAllowed" : true,
  "appTokenAllowed" : false,
  "allow_regexp_redirects" : false,
  "token_endpoint_auth_method" : "client_secret_basic",
  "scope" : "openid profile email general",
  "client_name" : "Enable App Password",
  "preauthorized_scope" : "openid profile email general",
  "trusted_uri_prefixes" : [ "https://<JASURI>/" ],
  "grant_types" : [ "password", "authorization_code", "client_credentials", "implicit", "urn:ietf:params:oauth:grant-type:jwt-bearer", "refresh_token" ],
  "redirect_uris" : [ "https://<JASURI>/jazzop" ],
  "introspect_tokens" : true,
  "proofKeyForCodeExchange" : false,
  "response_types" : [ "code", "token","id_token token" ]
}

In the above example replace/update the following variables:

• JASURI - Your Jazz Authorization Server URI
• client_name - Name to uniquely identify your client
• client_id and client_secret - Unique ClientId and Secret (Update the ClientId on the registration_client_uri as well)

Import the app.json file to JAS

#  cd /<JAS_Home>\cli
#  ./ldclient -a https://<JASURI>/oidc/endpoint/jazzop -u UserName:Password -c app.json 

Configure JAS to enable App Passwords

There are a few sections to edit in [JAS_HOME]/wlp/usr/servers/jazzop/appConfig.xml file.

• Specify the new ClientId and Secret in the oauthProvider element
• The attributes to update are internalClientId and internalClientSecret along with setting the attribute passwordGrantRequiresAppPassword to true. Here is an example:

  <openidConnectProvider id="jazzop" oauthProviderRef="JazzOP" sessionManaged="true"/>
   <oauthProvider id="JazzOP"
          httpsRequired="true"
          autoAuthorize="true"
          customLoginURL="/jazzop/form/login"
          accessTokenLifetime="7201"
          authorizationGrantLifetime="604801"
          passwordGrantRequiresAppPassword="true"
          internalClientId="AppPasswordClientId"
          internalClientSecret="AppPasswordClientPassword"
          trackOAuthClients="true">
          <databaseStore dataSourceRef="OAUTH2DBDS" />
   </oauthProvider>
  

• Optional: Add the appPasswordLifetime attribute to the oauthProvider element to change how long the Application password will remain active. The default value is 90 days (90d). See oauthProvider definition in Liberty documentation.

• Update the OIDC or SAML filters for the personal token management UI to require delegated authentication:

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

• Define Administrators for token management UI, under tokenManager element shown below

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

Enable Application password and Password grant type for ELM Applications registered in JAS

First verify the attributes for already registered ELM applications by accessing the URL

https://jas.example.com/oidc/endpoint/jazzop/registration 

Following are the attributes to look out for

 "appPasswordAllowed" : false,
 "grant_types" : [ "authorization_code", "client_credentials", "implicit", "urn:ietf:params:oauth:grant-type:jwt-bearer", "refresh_token" ], 

The value for appPasswordAllowed should be true and "password" should be present in the grant_types.

Here are the steps to update the attribute values:

• Export the Application registrations from JAS

  ./lsclient -a https://jas.example.com/oidc/endpoint/jazzop -u UserName:Password  > jas_export.json 

• Edit the jas_export.json file and for each application:
  • Update appPasswordAllowed to true
  • Add password to the list of grant types
• Here is an extract of the updated values

   { ....
      "appPasswordAllowed" : true,
      "grant_types" : [ "password", "authorization_code", "client_credentials", "implicit", "urn:ietf:params:oauth:grant-type:jwt-bearer", "refresh_token" ],
     ....
   } 

• Import the updated json file to change the desired values

  ./ldclient -a https://jas.example.com/oidc/endpoint/jazzop -u UserName:Password  jas_export.json 

Generate Application Passwords as a User

Once JAS is configured for Application passwords, users will be able to generate app passwords for their userId via the following URL. This will follow the SAML/OIDC authenticaion flow https://jas.example.com/oidc/endpoint/jazzop/personalTokenManagement

• Click on Add New
  
  
  
  

• Select app-password and click Generate and copy the generated password
  
  
  • *Note:* The use of "App Tokens" is not supported with the Jazz Authorization Server.
    
    
    

• By default the password is valid for 90 days. You can configure the validity by adding appPasswordLifetime attribute
  
  
  

Note : An Application password is locked to the first Application it is used against. For example, an Application password generated and used with Workflow Management Clients cannot be reused with Test Management clients.

Use Application Password with a non-web client

Use the generated Application Password from previous step with any Native client. Here is an example of for SCM Tools

# ./scm login -r https://ewm.example.co/ccm -u clmadmin -P L8ePXlZsUN848mXCO25t757E524U7z5pLC1H4vbbZe

Redirect usersTokenManagement authentication to SAML IdP or Third Party OIDC Provider

The usersTokenManagement url on JAS allows Administrators to search for specific users and review/delete their Application Passwords.

https://jas.example.com/oidc/endpoint/jazzop/usersTokenManagement 

By default the authentication is based on the backing userRegistry configured with JAS. To redirect the page to SAML IdP for authentication edit the filters as follows:

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

The authentication fails with 403 forbidden. The reason is, the access is restricted to specific users who have been defined under tokenManager as shown below.

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

While the user is authenticated via SAML IdP or Third Party OIDC Provider, mapping the user to a group on the backing userRegistry on JAS does not happen with the default configurations and hence the access is denied.
To overcome this error add mapToUserRegistry="user" within the samlWebSso20 configuration or mapToUserRegistry="true" within the oidcLogin configuration. Sample SAML configuration shown below

<samlWebSso20 
       id="defaultSP"
       spCookieName="jazzop_sso_cookie_idp"
       forceAuthn="false" 
       authFilterRef="samlAuthFilter" 
       keyStoreRef="defaultKeyStore"
       mapToUserRegistry="user" >
</samlWebSso20> 

Note: These steps apply for /ClientManagement and/or /registration URLs as well

Encrypting internalClientSecret in appConfig.xml file

In the current version of IBM WebSphere Liberty until version 23.0.0.2, encrypted values for internalClientSecret is not accepted and there is an error accessing the personalTokenManagement UI page. This is planned to be implemented in one of the upcoming releases. Please visit the Fix list for IBM WebSphere Liberty to review new releases when this is implemented.

Related topics: Liberty application password feature, Development Wiki - App Password