[vc_row type=”full_width_content” full_screen_row_position=”middle” bg_image=”9″ bg_position=”center center” bg_repeat=”no-repeat” scene_position=”center” text_color=”light” text_align=”left” top_padding=”8%” bottom_padding=”5%” color_overlay=”#262f3f” overlay_strength=”0.95″][vc_column centered_text=”true” column_padding=”padding-3-percent” column_padding_position=”left-right” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/1″ tablet_text_alignment=”default” phone_text_alignment=”default”][vc_row_inner text_align=”left”][vc_column_inner enable_animation=”true” animation=”fade-in-from-bottom” column_padding=”padding-1-percent” column_padding_position=”bottom” background_color_opacity=”1″ width=”1/1″ delay=”200″][vc_column_text]
getting started
[/vc_column_text][/vc_column_inner][/vc_row_inner][vc_row_inner bottom_padding=”30″ text_align=”left”][vc_column_inner enable_animation=”true” animation=”fade-in-from-bottom” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ width=”1/1″ delay=”300″][vc_column_text]
Learn More about SwipeClock’s Integration Options
[/vc_column_text][/vc_column_inner][/vc_row_inner][vc_row_inner bottom_padding=”30″ text_align=”left”][vc_column_inner enable_animation=”true” animation=”fade-in-from-bottom” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ width=”1/1″ delay=”300″][/vc_column_inner][/vc_row_inner][/vc_column][/vc_row][vc_row type=”full_width_background” full_screen_row_position=”middle” scene_position=”center” text_color=”dark” text_align=”left” top_padding=”100″ bottom_padding=”2.5%” overlay_strength=”0.3″][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/1″ tablet_text_alignment=”default” phone_text_alignment=”default”][tabbed_section style=”minimal” alignment=”left” cta_button_style=”extra-color-1″ cta_button_text=”API Status” cta_button_link=”#”]
[/tabbed_section][/vc_column][/vc_row][vc_row type=”full_width_background” full_screen_row_position=”middle” bg_color=”#ffffff” scene_position=”center” text_color=”dark” text_align=”left” top_padding=”7%” bottom_padding=”4%” overlay_strength=”0.3″][vc_column centered_text=”true” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/1″ tablet_text_alignment=”default” phone_text_alignment=”default”][divider line_type=”Full Width Line” line_thickness=”2″ divider_color=”default” animate=”yes”][/vc_column][/vc_row][vc_row type=”full_width_background” full_screen_row_position=”middle” bg_color=”#ffffff” scene_position=”center” text_color=”dark” text_align=”left” top_padding=”4%” bottom_padding=”4%” overlay_strength=”0.3″][vc_column centered_text=”true” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”2/3″ tablet_text_alignment=”default” phone_text_alignment=”default”][vc_column_text]Summary
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
This document provides an overview of how to complete a single sign on (SSO) into SwipeClock. SwipeClock’s SSO model follows an OAuth 2.0 JWT Bearer Token Flow. JWT stands for JSON Web Token which is JSON-based security token encoding that enables identity and security information to be shared across domains. For more information on JWT visit https://jwt.io
The standard workflow of the OAuth 2.0 JWT Bearer Token Flow is as follows:
1. The JWT created is posted to SwipeClock’s OAuth token endpoint.
2. SwipeClock’s OAuth token end point validates the content and signature of the JWT token.
3. Assuming the posted JWT is valid and from an approved integration partner, an access token is issued.
4. The issued access token includes an expiration date and is valid for subsequent calls to other SwipeClock API endpoints (including SSO endpoints).
When completing an SSO into SwipeClock, you can display SwipeClock’s components in an Embedded HTML iframe/object
[/vc_column_text][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][/vc_row][vc_row type=”full_width_background” full_screen_row_position=”middle” bg_color=”#ffffff” scene_position=”center” text_color=”dark” text_align=”left” top_padding=”4%” bottom_padding=”4%” overlay_strength=”0.3″][vc_column centered_text=”true” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”2/3″ tablet_text_alignment=”default” phone_text_alignment=”default”][vc_column_text]
Pre-Requisites
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Before accessing any of the exposed SwipeClock APIs, you must first obtain an API secret. This secret is your “password” to programmatically access SwipeClock’s API endpoints.In order to understand the types of API secrets available, it’s important to review the hierarchy built into SwipeClock’s systems. The image below depicts some important entities and actors in SwipeClock.
1. Partner/Accountant – A partner/accountant administers any number of sites below them. A typical example of a partner is a payroll provider who has setup SwipeClock for a number of employers they manage.
2. Client/Site – A client/site is an end employer setup for SwipeClock’s services. Each site will have a number of employees managed along with users identified as client/site administrators and supervisors. In our image we have three sites: Steve’s Lawn Care, Joe’s Pizza Shop and Dr. Martin’s Office.
3. Employee – an employee using SwipeClock’s services.
4. Client/Site Administrator – a client/site can have certain user accounts granted administrative privileges to manage aspects of the client/side configuration.
5. Supervisor – a client/site can have user accounts with supervisor/management privileges to manage aspects of specific employees within the client/site.
[/vc_column_text][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][/vc_row][vc_row type=”full_width_background” full_screen_row_position=”middle” bg_color=”#ffffff” scene_position=”center” text_color=”dark” text_align=”left” top_padding=”4%” bottom_padding=”4%” overlay_strength=”0.3″][vc_column centered_text=”true” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”2/3″ tablet_text_alignment=”default” phone_text_alignment=”default”][vc_column_text]
Single Sign On
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
The single sign on workflow allows you to render SwipeClock with your platform as an embedded HTML iframe/object or into a new browser window/tab. No matter which method you choose, the initial set of steps are the same.
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Step 1: Authenticate Against SwipeClock’s OAuth Token Endpoint
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
URL: https://clock.payrollservers.us/AuthenticationService/oauth2/userToken.
You must first create your JWT (tip: visit https://jwt.io/#libraries-io for a number of free libraries/SDKs available for use to create your JWT).
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Creating a JWT Header
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
The first part of your JWT will be the header. This identifies the algorithm and token type you’re using. Included in the JWT header are:
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
| Name | Type | Description |
|---|---|---|
| alg | String | Identifies the hasing algorithm being used. Use “HS256”. |
| type | String | Identifies the type of token which is JWT. Use “JWT”. |
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Below is an example of a header of a JWT.
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
{
alg: "HS256",
typ: "JWT"
}
[/vc_column_text][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][/vc_row][vc_row type=”full_width_background” full_screen_row_position=”middle” bg_color=”#ffffff” scene_position=”center” text_color=”dark” text_align=”left” top_padding=”4%” bottom_padding=”4%” overlay_strength=”0.3″][vc_column centered_text=”true” column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”2/3″ tablet_text_alignment=”default” phone_text_alignment=”default”][vc_column_text]
Creating a JWT Body/Payload
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
URL: https://clock.payrollservers.us/AuthenticationService/oauth2/userToken.
You must first create your JWT (tip: visit https://jwt.io/#libraries-io for a number of free libraries/SDKs available for use to create your JWT).
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Creating a JWT Header
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
The first part of your JWT will be the header. This identifies the algorithm and token type you’re using. Included in the JWT header are:
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
| Name | Type | Description |
|---|---|---|
| iss | String | SwipeClock partner ID |
| product | String | twpemp = for employee SSO twplogin – for client/site administrator or supervisor SSO |
| sub | String | partner = if you have a partner API secret client = if you have a site API secret |
| exp | String | A date in Unix epoch time. Visit https://www.epochconverter.com/ for more information. |
| siteinfo | Object | An object of name value pairs:
|
| user | Object | An object of name value pairs:
|
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Below is an example of the JSON body/payload for your JWT for partner 1, site 69481 and employee with the employee code 1234 if you’re using a client level API secret.
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
{
iss: 69481,
product: "twpemp",
sub: "client",
exp: 1517004886,
siteInfo: {
type: "id",
id: "69481"
},
user: {
type: "empcode",
id: "1234"
}
}
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Below is an example of the JSON body/payload for your JWT for partner 1, site 69481 and employee with employee code 1234 if you’re using a partner level API secret.
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
{
iss: 1,
product: "twpemp",
sub: "partner",
exp: 1517004886,
siteInfo: {
type: "id",
id: "69481"
},
user: {
type: "empcode",
id: "1234"
}
}
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
Below is an example of the JSON body/payload for your JWT for partner 1, site 69481 and supervisor with the login ssosupervisorlogin if you’re using a client level API secret.
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
{
iss: 69481,
product: "twplogin",
sub: "client",
exp: 1517004886,
siteInfo: {
type: "id",
id: "69481"
},
user: {
type: "login",
id: "ssosupervisor"
}
}
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
The differences between using the partner API secret and client API secret is within the following elements of the JSON body/payload:
[/vc_column_text][divider line_type=”No Line” custom_height=”40″][vc_column_text]
| Entity Name | Value when using a partner API secret | Value when using a client API secret |
|---|---|---|
| iss | Partner/Accountant ID | Client/Site ID |
| sub | “partner” | “partner” |
[/vc_column_text][/vc_column][vc_column column_padding=”no-extra-padding” column_padding_position=”all” background_color_opacity=”1″ background_hover_color_opacity=”1″ width=”1/6″ tablet_text_alignment=”default” phone_text_alignment=”default”][/vc_column][/vc_row]