Deep link usage

IBM Notifier (Mac@IBM Notifications) provide also a light and state less method to trigger Banner, Pop-up and Onboarding UIs: Deep links.

The default url schema associated with the app is ibmnotifier and the path to trigger UIs is shownotification.

This deep link accept all the available arguments used in the invocation through command line (except for the special arguments) but remember to remove the - from the front. (ex. -title -> title)

How to handle deep link security?

Deep links are secured via JSON Web Tokens (JWT). This token must be added to the deep link in order to let the agent to validate it and then parse the link arguments.

This JWT token are signed with a private key guarded by the admin. In order for the agent to evaluate the token signature, it needs to use the related shared public key.

Every token can specify a different expiration date and set different other claims. To learn more about the technology of JWT and its use, please refer to the jwt.io site.

How to enable deep link security and share the public key with the agent?

To enable deep link security the admin should deploy and ad-hoc configuration profile on the user device.
This profile will define the following ManagedPreferences for IBM Notifier (com.ibm.cio.notifier):

• deeplinkSecurity = YES
• deeplinkSecurityKey = YOUR_JWT_PUBLIC_KEY

The resultant config profile should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadContent</key>
			<dict>
				<key>com.ibm.cio.be.mac-notification-agent</key>
				<dict>
					<key>Forced</key>
					<array>
						<dict>
							<key>mcx_preference_settings</key>
							<dict>
								<key>deeplinkSecurity</key>
								<true/>
								<key>deeplinkSecurityKey</key>
								<string>-----BEGIN PUBLIC KEY-----
HEREYOURPUBLICKEY
-----END PUBLIC KEY-----</string>
							</dict>
						</dict>
					</array>
				</dict>
			</dict>
			<key>PayloadDisplayName</key>
			<string>Custom Settings</string>
			<key>PayloadIdentifier</key>
			<string>37681FFA-B01E-4575-8B6F-4AAFE406BC21</string>
			<key>PayloadOrganization</key>
			<string>JAMF Software</string>
			<key>PayloadType</key>
			<string>com.apple.ManagedClient.preferences</string>
			<key>PayloadUUID</key>
			<string>37681FFA-B01E-4575-8B6F-4AAFE406BC21</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string></string>
	<key>PayloadDisplayName</key>
	<string>IBM Notifier DeepLink Security</string>
	<key>PayloadIdentifier</key>
	<string>1BE1618D-5D7A-4F23-9693-B985DFF39FA9</string>
	<key>PayloadScope</key>
	<string>System</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>1BE1618D-5D7A-4F23-9693-B985DFF39FA9</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

You can find it also here.

How to generate a JWT Token?

To simplify generating JWTs here we provide a small helper tool in Python which you can use to generate fully compliant, production ready JSON Web Tokens. The README file contains detailed description about using it. If you want to just quickly start using secured deep links in IBM Notifier, first make sure you have Python 3 installed on your device and then enter following commands to your terminal once inside of jwt-generator folder in the project:

pip3 install -r requirements.txt - it will install required dependencies for JWT Generator

./keygen.sh - it will generate new RS256 key pair (when prompted for a passphrase press enter to skip it)

Now copy the printed public key (including -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines) and use it to share public key as described in enabling deep link security section.

From now on you can start generating secured, digitally signed JWTs For IBM Notifier by running:

./jwtgenerator.py jwtRS256.key

Each token will be valid for 10 minutes after generation (see README file if you'd like to use different expiration time)

Example

This is an example on how to trigger a simple Pop-up with a deep link:
open "ibmnotifier:shownotification?token=THISISATOKEN&type=popup&title=This%20is%20a%20title&subtitle=This%20is%20a%20subtitle"