Using JWT Authentication

Use JWT (JSON Web Token) to securely pass user data into MediaOS. This allows you to pre-fill user information, set audiences and forum groups, and provide a seamless user experience across your web properties.

Why Use JWT? #

JWT integration allows external platforms (like a CMS, paywall, or custom login system) to pass authenticated user data into MediaOS. This eliminates redundant form fields, enables instant access to protected resources, and improves the user’s onboarding experience.

MediaOS accepts JWT payloads for secure, one-time user provisioning. This is ideal for single sign-on (SSO), paywall access, newsletter registration, or forum permissions.

Note: Never share your JWT secret publicly. Keep it secure, as it grants authorization to inject users into your MediaOS instance.

Where to Find Your JWT Secret #

Your JWT secret is unique to each website.

To find it:

1. Navigate to Websites in MediaOS.
2. Click Manage on the specific website where you’re setting up JWT.
3. Locate the JWT Secret in the settings panel.

Tip: If you don’t see a JWT secret or the field is empty, contact your MediaOS administrator or support team to enable it for your environment.

Example Integration #

Here’s a basic PHP example of how to generate a JWT token and inject it into the page using MediaOS’s SSO mechanism:

<?php
$payload = [
	'email' => 'email@email.com',
	'first_name' => 'John',
	'last_name' => 'Doe',
	'company' => 'Company',
	'expires' => strtotime('+1 minute'),
	'passwordMD5' => md5('PASSWORD'), // optional
	'forumGroupIds' => [1,2,3],
	'audienceIds' => [1,2,3],
	'avatar' => 'https://domain.com/avatar.jpg',
	'newsletterIds' => [2, 4]
];
?>
<script type="text/javascript">
	window.mediaosSSO = '<?=JWT::encode($payload, 'YOUR JWT SECRET', 'HS256')?>';
</script>
<script type="module" src="https://mos-scripts.com/a/main.js"></script>

Note: Replace 'YOUR JWT SECRET' with the actual JWT secret from your website’s Manage settings in MediaOS.

Payload Field Reference #

Below are the common fields you can pass in the JWT payload:

• email (required) – The user’s email address.
• first_name – User’s first name.
• last_name – User’s last name.
• company – User’s organization.
• expires (required) – UNIX timestamp when this token should expire. Recommended: set to a short duration like strtotime('+1 minute').
• passwordMD5 – MD5-hashed password for setting a password upon import (optional).
• forumGroupIds – Array of forum group IDs the user should join.
• audienceIds – Array of audience IDs the user should be added to.
• avatar – URL to a profile image for the user.
• newsletterIds – Array of newsletter IDs the user should be subscribed to.

Warning: The passwordMD5 field is optional and should only be used if you’re setting or syncing user passwords. Never pass plain-text passwords.

Embedding the Script #

To complete the integration:
Output the JWT token into window.mediaosSSO before loading the MediaOS script.
Then include the following script tag:

<script type="module" src="https://mos-scripts.com/a/main.js"></script>

Tip: This script must be loaded after window.mediaosSSO is defined. For best results, include both immediately before the closing tag of your page.

Troubleshooting #

• JWT tokens are time-sensitive. Make sure the expires value is no more than a few minutes in the future and your server clock is accurate.
• Use a JWT debugging tool like jwt.io to inspect your token and ensure it’s structured properly. Be careful not to paste real tokens with your live secret into public tools.
• If no user is injected after page load, check the browser console for errors and verify the token structure and payload fields.

Suggested Use Cases #

• Automatically subscribe users to newsletters after external form completion.
• Seamlessly log in users from your paywall or external CMS.
• Grant users forum access or custom onboarding when joining a partner program.