Waggl JWT Authentication

Introduction

Waggl supports using JWT (JSON Web Tokens) as a Single Sign On (SSO) mechanism. JWT is an industry standard method for representing claims securely between two parties. You can learn more about JWT at jwt.io.

Workflow

1. User clicks a Waggl link.
2. They are redirected to an SSO URL that you provide us. When redirecting we will add a parameter that tells you where to send them after you authenticate.
3. They go to your URL and authenticate (using Active Directory or other internal authentication system).
4. After successful authentication you redirect them to Waggl by taking the URL we have passed to you and adding a JWT Token which is unique to this user.
5. Waggl processes and verifies JWT Token which identifies the email for the user and logs them in.

Processing Requests to your SSO URL

You will provide us a URL that we will redirect your users to for authentication. For example, https://yourcompany.com/waggl/sso/. We will include 2 parameters - return_to_path and return_to_params. When they come to your URL, you will do the following:

1. Authenticate them (if needed)
2. Generate JWT Token (see below)
3. Redirect them to the return_to_path url we provide with the JWT Token

Generating JWT Token

See http://jwt.io/#libraries to find a JWT library in the language of your choice. We will provide you a secret key that is unique to your organization for signing your token. We require the HS512 hash algorithm for signing. Your token should contain the following json data:

{

	data: {
		email: <email address of user>
	}
	iat: <current date/time>,  
	nbf: <date/time when this token should not be usable before.  This should be 3 mins before the current time to allow for any differences is machine clocks.>,  
	exp: <date/time when this token should expire.  After this time, the link will no longer work. We recommend that this is 5 mins after the current time.>,  
	aud: "www.waggl.com"
	
}

Notes: Dates should be the number of seconds since the Epoch (1970-01-01T00:00:00Z UTC). If your company has already been using Waggl, then you will want to make sure that the email address you pass is the same as what participants would already have entered. For example, if John Smith entered email address [email protected] already in the system you don't want to pass [email protected] or their previous activity will not be linked.

Including Tags in JWT Token

You can optionally include tag information about the user. The tags need to be setup in the Waggl system to be used (if you would like to use tags please discuss with your account manager). To use them you add additional attributes to the data object:

data: {
	email: <email address of user>
	tags: {
		<tag category1>: <tag value1>,
		<tag category2>: <tag value2>,
	}
}

For Example:

data: {
	email: [email protected]
	tags: {
		Department: "Sales",
		Region: "West Coast",
	}
}

Generating Redirect

You create the redirect URL in the following way https://app.waggl.com/<return_to_path>?sso_jwt=&<return_to_params>. Note, return_to_params is an optional parameter that will only be included when needed.

For example, with the following values:

• return_to_path: "i%2F9745804b" (URL encoded version of 'i/9745804b')
• return_to_params: "view%3Dvote%26page%3D1" (URL encoded version of 'view=vote&page=1')
• jwt: "xxxxx.yyyyy.zzzzz"

Then the redirect URL would be https://app.waggl.com/i/9745804b?sso_jwt=xxxxx.yyyyy.zzzzz&view=vote&page=1

Or if there is no return_to_params:

• return_to_path: "i%2F9745804b" (URL encoded version of 'i/9745804b')

• jwt: "xxxxx.yyyyy.zzzzz"

Then the redirect URL would be: https://app.waggl.com/i/9745804b?sso_jwt=xxxxx.yyyyy.zzzzz]

Example Code

You can view example code for different languages below:

• Dot Net

• [Ruby on Rails] (https://github.com/waggl/waggl_jwt_sso/blob/master/example_code/ssos_controller.rb)

• [PHP] (https://github.com/waggl/waggl_jwt_sso/blob/master/example_code/php_example.php)