Post Change Actions to external webservice

Creating a post password change action, that posts to a web service

Some of the various product modules allows the admin to configure Actions to be performed after the module successfully performed a function, for example: After User Change Password, User Registration, User Change Forgotten Password and so on.

This is a neat feature that allows you to communicate with an external web service to extend the functionality of PWM - For example,

• You may want to update legacy systems with credentials and account settings (such as when the user's password will expire).
• You may want to notify the CRM system when a new user registered in the system.

To implement this, you can use the web service action to submit either:

• an http Get with query string parameters, i.e: GET /whatever/page.aspx?param1=value&param2=value
• an http Post with form data i.e.
  POST /whatever/page.aspx
Content-Type: application/x-www-form-urlencoded
param1=value&param2=value

Notice that in order to postback a form, you must set the Content-Type:application/x-www-form-urlencoded HTTP Header, and the body form data is in the format: param1=value&param2=value

To populate the values, you can use The Macro format variables:

Macros

Macro	Description
@LDAP:name@	Lookup the LDAP value of the user's LDAP attribute name.
@LDAP:name:length@	Lookup the LDAP value of the user's LDAP attribute name. If the value is longer than length, then truncate the value to the specified length.
@LDAP:name:length:padding@	Lookup the LDAP value of the user's LDAP attribute name. If the value is longer than length, then truncate the value to the specified length. If the value is shorter than length, then pad the value with the value of length.
@LDAP:DN@	Replace with LDAP value of user's LDAP Distinguished Name
@User:PwExpireTime@	Time user's password will expire in default ISO format.
@User:PwExpireTime:pattern@	Time user's password will expire where pattern is a SimpleDateFormat pattern
@User:DaysUntilPwExpire@	Number of days until the user's password will expire
@User:ID@	User's UserID (if authenticated)
@User:Email@	User's Email Address
@User:Password@	User's current password (if authenticated). Use caution, this will allow password to appear in logs and whichever function the macro is used in.
@InstanceID@	Instance ID of the application
@CurrentTime@	Current time in default format.
@CurrentTime:pattern@	Current time where pattern is a SimpleDateFormat pattern
@CurrentTime:pattern:tz@	Current time where pattern is a SimpleDateFormat pattern, and the timezone is a tz specified as a valid TimeZone ID.
@Site:URL@	URL of the site http://www.example.com/password
@Site:Host@	Hostname of the site www.example.com
@RandomChar@	A single random character of visible upper & lower ASCII characters and digits.
@RandomChar:length@	Random characters, where length is the number of random characters to generate.
@RandomChar:length:characters@	Random characters, where length is the number of random characters to generate and characters is the list of characters to be used as random characters.
@Encode:type:[[value]]@	Encode a value using the specified type of encoding, where type is the type of encoding and where value is the value to encode. The value may include other macros. Types permitted are urlPath, urlParameter and base64.

• Note: Parameters that need to include a literal @ or : character must escape these characters with a preceding / such as /@ or /:

Here is an example of such implementation:

• Action: Post Password change action
• Name: UpdateToLegacyUserDB
• Type: webservice
• HTTP Method: Post
• HTTP Headers: Content-Type:application/x-www-form-urlencoded
• URL: http://services.example.com/pwreset
• BODY: username=@User:ID@&password=@User:Password@&expire=@User:PwExpireTime:yyyy-MM-dd HH:mm:ss.SSS@&requestfrom=@&Site:Host@&auth=12345678901234567890

The "pwreset" application on the above example services url, does the processing of the above data, and will set the password and password expiry in the legacy application accordingly.

Notice how we used the SimpleDateFormat pattern to carefully pass the User's password expiry time in the format our app expects to receive it.

Notice you can test a Macro in the context of the logged on admin user, if you edit the configuration and press the magic-wand icon on the action bar on the top.

Notice I had an issue changing the HTTP Method to Post on the UI. Luckily there is a workaround: create the get action, then go to the server and change it manually in webapps/pwm/WEB-INF/PwmConfiguration.xml from get to post, and then go into configuration editor ui again. the form will show the body part, and HTTP method will remain on post.