Synap Academy
Synap Home
  • ๐Ÿ‘‹Hello there
  • ๐Ÿ†•What's new
    • Big features
      • ๐Ÿ“ฉCustom messages from attempt tables
      • โณLimit membership duration for user groups
      • โ“Question based marking
      • ๐Ÿ‘ฝCloze questions & new editor
      • ๐Ÿฆ„Customise questions in exams
      • ๐Ÿคธโ€โ™‚๏ธFlexi retakes
      • ๐Ÿ’ฟRecords of learning
      • ๐Ÿ‡Override attempt scores, comments & history
      • ๐ŸงชLab values / Additional exam resources
      • ๐Ÿ”–Bookmarking
      • โœ๏ธSingle Sign On (SSO)
      • ๐ŸŽSub portals
      • ๐Ÿ›‚Multi-factor Authentication (MFA)
      • ๐Ÿ—’๏ธNotepad on attempts
      • ๐Ÿ‘๏ธโ€๐Ÿ—จ๏ธSynoptic
      • ๐ŸŽ–Override Grades
      • ๐Ÿ“ธGet webcam shots for identity verification
      • ๐Ÿ”Exam security: Lock exam attempts
      • โ›“๏ธShare links
      • ๐Ÿ›ฉ๏ธThe attempts table
      • ๐Ÿ“‹Anti cheat: disable copy & paste
      • ๐ŸฆšStudents Insights page
      • ๐Ÿงžโ€โ™‚๏ธGenerating quizzes
      • ๐Ÿฅ‡Exam certificates & resits
      • ๐Ÿ” Mark schemes/rubric marking
      • โœ…Marking & definition of completed attempts events -
      • ๐Ÿ‘ฏโ€โ™€๏ธCloning
  • ๐ŸŽฎInteractive demos
  • ๐Ÿƒโ€โ™‚๏ธGetting started
    • Overview
    • Content management
      • Notes
        • Dynamic notes
      • Surveys
      • Uploading content
        • Embed presentations
    • Billing & usage
  • โ“Quizzes
    • Creating a Quiz
      • Question types
        • Cloze question types
        • Audio recording questions
        • Audio/Video Stems and configurations
      • EMQs
      • Quiz Experience
      • Instructions & sections
      • Scoring on Synap (Points vs Credits)
        • Negative Scoring
        • Score by choice
    • Importing & Exporting Questions
      • Importing
        • Word Doc to CSV Format
        • Questions
        • EMQs
        • Sections
      • HTML formatting
  • ๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘ฆโ€๐Ÿ‘ฆUsers & Groups
    • User types
    • Creating groups
      • Adding & inviting users by email
      • Generating user accounts
      • Importing new and existing users via csv
      • Customising messages to users
      • Sharing user group links
      • Advanced group settings
    • Manage groups
    • User information
    • Permissions
      • Global permissions
      • Specific permissions
      • Educator permissions
      • Markers permissions
  • ๐Ÿ‘จโ€๐Ÿ’ปExams
    • Understanding Exams on Synap
    • Create and Manage Exams
      • ๐Ÿ—๏ธ1. Setup: Exam
        • Dynamic exams
        • Customisation
      • ๐Ÿ”จ2. Build: Exam
        • Sections
        • Grades
      • โš™๏ธ3. Configure
        • Experience
        • Instructions
        • Results
        • Resits
        • Certificates
      • ๐Ÿš€4. Advanced
      • ๐Ÿ–‹๏ธMarking - Double & Blind
        • Adding custom marks & a mark scheme
      • ๐Ÿ“จ5. Share
        • Schedule
        • Publishing
        • Versioning
      • ๐Ÿ‘€6. Manage
    • Mark/Score attempts
    • Anti-Cheat features
      • Disabling Spellcheck for Exams
    • Proctoring
      • Proctoring with Rosalyn
        • Rosalyn Lock-down exam
        • Rosalyn Live Proctoring exam
        • Sitting a Rosalyn Proctored exam
      • Proctoring with Synoptic
        • Create a Synoptic exam
        • Reviewing Synoptic Sessions
        • Sitting a Synoptic Proctored Exam
        • Synoptic Best Practices & Trouble Shooting
      • Proctor Pricing
  • ๐Ÿ„Collections
    • Creating collections
      • Configure collections
    • Manage user group visibility
    • Collection mocks
    • Collections and the Study
    • Collection use cases
  • ๐ŸŽ๏ธCourses
    • Assignments
    • Course builder
    • Assigning a course
      • Viewing assignments & publishing new versions
    • Courses and assignment use cases
  • โš™๏ธPortals
    • Trouble shooting for your students
    • Portal Settings
      • General and branding
      • Registration settings
      • Email settings
      • Locale / Language settings
      • SSO Authentication
        • Auth0
        • JSON Web Tokens (JWT)
        • SAML with Okta (EU)
        • SAML with Okta (US)
      • Study and Self Practice settings
    • User Access
    • Data Management
      • Tag manager
      • Attributes
      • Records of learning
    • Sub portals
      • Creating sub portals
      • Branding sub portals
  • ๐Ÿ“ŠAnalytics
    • Fractal
    • Tags & facets
      • Facet best practice
    • Student Insights
    • Question statistics
  • โฌ…๏ธExports & Reporting
    • Attempts table & exports
    • Reporting platform (Depreciated)
    • Flag exports
  • ๐Ÿ”ŒIntegrations
    • ๐ŸชWebhooks
      • User Updated Webhook
      • Attempt Completed Webhook
      • Attempt override created
      • User Registered Webhook
      • Exam Completed Webhook
      • Attempt Submitted Webhook
      • Exam Submitted Webhook
      • Attempt Certificate Generated
      • Store Purchase Webhook (Legacy)
      • Completed Assignment Webhook
      • Flag Planted Webhook
      • User Added to User Group Webhook
      • User Registered for Exam Webhook
      • Learning Record Webhooks
      • Invite sent
    • Integrations & APIs
    • Single Sign On
    • โšกZapier
      • ๐ŸŸขGet started
      • ๐Ÿ”ซTriggers
      • ๐ŸŽฌActions
      • ๐Ÿ—๏ธExample Workflows
    • Segment
      • Test & Question Analytics
    • Google Analytics
    • Custom Domain (CNAME)
    • Synap Mobile Apps
  • ๐Ÿš€Using Synap
    • Admin Account
    • Synap Students
Powered by GitBook
On this page
  • How it Works
  • Testing & Debugging
  • Developing & Helpful Libraries

Was this helpful?

  1. Portals
  2. Portal Settings
  3. SSO Authentication

JSON Web Tokens (JWT)

Guide to Setting Up SSO via JWT

How it Works

First, a user will be prompted to sign in to your external site. Once authenticated, your application will construct a JWT and redirect the user back to Synap using the token as a query string parameter. Synap then deconstructs the JWT and will either find the user and sign them in, or if they are a new user, it will create an account and then sign them in.

Authentication Endpoint

The Synap JWT authentication endpoint is shown below. Please replace YOUR_JWT_TOKEN with a constructed JWT following the format specified later in this document.

You can also provide return_to and/or error_url parameters, as detailed in the table below, if desired.

EU Infrastructure:
https://api.synap.ac/external-auth/jwt/authenticate/?jwt=YOUR_JWT_TOKEN
US Infrastructure: 
https://use1.prod.api.synap.ac/external-auth/jwt/authenticate
Key
Value
Designation

jwt

An encoded JSON Web Token

REQUIRED

return_to

A URL-encoded URL string that the user should be redirected to after successful authentication. If not specified, the user will be redirected to their default home page on Synap

OPTIONAL

error_url

A URL-encoded URL string that the user should be redirected to if authentication fails. The URL will be appended with an sso_error query param containing a human-readable error message. If not specified, the user will be redirected to the Synap /login page

OPTIONAL

Constructing a JWT

In order to construct a JWT, you will need a Secret Key - in the future, this will be available on your Admin Settings page, but for now please contact your Synap Account Manager to obtain this key.

Once you have obtained your Secret Key you must store it securely. Do not expose it in your client-side code, and we would strongly advise against checking it into your source control.

Please use the following data to construct your header. This specifies the HS256 algorithm.

{
  "alg": "HS256", 
  "typ": "JWT" 
}

Your JWT payload should look like this (replace all values, or remove optional fields as appropriate). Please find detailed descriptions of the fields in the table below

{
  "eaid": YOUR_PORTAL_EAID, // ask your Synap account manager for this
  "exp": 1691610066066, // optional
  "email": "john.doe@synap.ac", 
  "name": "John Doe",
  "subPortal": "abc123" // optional
}
Key
Value
Designation

eaid

This is an internal ID used by Synap to identify your SSO integration. It will be the same for every JWT you construct - please ask your account manager for a copy of it

REQUIRED

exp

A unix timestamp indicating the token's expiry date. This is recommended, but not required. We would advise setting an expiry date of ~14 days but you may wish to set a shorter or longer time depending on your internal security and data protection policies

RECOMMENDED

email

The email address of the user to log in

REQUIRED

name

The full name (e.g. Firstname Lastname) of the user being logged in.

REQUIRED

subPortal

If you make use of Synap Subportals, this field can be used to specify the ID of a subportal to log that user into. If you are not using Subportals then please omit this field entirely

OPTIONAL

Finally, your Verification Signature should be constructed as follows:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  YOUR_SECRET_KEY
)

Replace YOUR_SECRET_KEY with the Secret Key provided by your account manager.

Do NOT base64 encode your secret key when constructing the verification signature

Testing & Debugging

Developing & Helpful Libraries

You may be interested in the following libraries to assist with constructing JWTs:

PreviousAuth0NextSAML with Okta (EU)

Last updated 1 month ago

Was this helpful?

There is a great website for constructing and testing JWTs available at - it can be helpful for quick testing and debugging.

- An 'Authentication as a Service' platform that you can use to set up and manage your authentication process. It provides JWT as a login option, as well as native Auth0 login and SAML.

- Has an extensive list of JWT signing and verification libraries in a range of popular programming languages and platforms.

โš™๏ธ
https://jwt.io/
Auth0
This page