Skip to Content

Security provider - JWT SSO

The JWT SSO security provider is an implementation of a custom single sign-on (SSO) protocol. The protocol allows a trusted service to sign a user into Vinyl. This is achieved by generating a JSON Web Token (JWT) and passing the token to an authentication endpoint by way of a client browser redirect.


The JWT SSO protocol leverages the following standards:


The JWT SSO protocol defines two service endpoints.

  • Authentication Service - Hosted by Vinyl.
  • Single Sign-On Service - Hosted by the trusted, third-party service.

Authentication service

The authentication service is responsible for:

  1. Authenticating a JWT.
  2. Signing the user into Vinyl.


Where {Provider} is the Vinyl security provider name. See Configuration.


The authentication service endpoint defines the following parameters:

  • jwt – JSON Web Token. Required.
  • return_to – Relative URI. Optional.

The jwt parameter contains the JSON Web Token. JWTs are URL safe, so no additional encoding is required.

JWTs must meet the following requirements:

  • The JWT must be signed using the RS256 algorithm (RSA, SHA-256).
  • The JWT must not be encrypted.
  • The JWT must include the following registered claims.
Claim Name Type Purpose
iss Issuer StringOrURI Vinyl will match the issuer to the security provider's configured issuer, performing a case-sensitive comparison.
sub Subject StringOrURI Vinyl will match the subject to a Vinyl user account.
aud Audience URI Vinyl will match the audience to the security provider's configured audience. Example:
exp Expiration Time NumericDate Vinyl will validate that expiration date is less than the current date, taking into account clock skew.
nbf Not Before NumericDate Vinyl will validate that current date and time is greater than the Not Before value, taking into account clock skew.
iat Issued At NumericDate Vinyl will use the Issued At value to determine the age of the JWT. Vinyl will limit the window in which a token is accepted to, e.g., 5 minutes.
jti JWT ID NumericDate Vinyl will use the JWT ID to prevent replay attacks.

The JWT registered claims are described in Section 4.1 of the JSON Web Token standard.

The JWT may contain additional claims. As with all Vinyl security providers, the claims can be:

  • Used to provision user accounts and supply security group membership
  • Mapped to user account properties such as the user name, email address or phone number.
  • Accessed by business rules using the mvSQL claim() runtime function.

Example of a JWT payload:

  "jti": "918b6e73-400d-479c-baa1-8e12f5fd78f4",
  "iss": "",
  "aud": "",
  "sub": "Arthurd.Dent",
  "iat": 1652473593,
  "exp": 1652473893,
  "groups": [

The return_to parameter consists of a URI. The URI is relative to the Vinyl application root directory. It must be prefixed with a leading slash.



Vinyl will validate the URI to guard against open-redirect attacks.



By default, the authentication endpoint will accept a form post:

POST /Vinyl/signin-JWTSSO HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 31


As an alternative, the authentication endpoint may also be configured to accept GET requests:

GET /Vinyl/signin-JWTSSO?jwt={jwt}&return_to={return_to} HTTP/1.1

When using the GET method, the JWT security token is passed in the URL query string.

Consider the following before using GET:

  • GET poses additional risk as query strings are often written to web server log files. This can be mitigated by ensuring security tokens have a short lifespan and cannot be replayed.
  • URLs are subject to length restrictions, typically in the vicinity of 2,000 characters. This can be mitigated by limiting the number of claims.
  • The return_to parameter may contain double-URL-encoded values. Such requests can be blocked by firewalls.

Single sign-on service

The Single Sign-On Service is the endpoint that Vinyl will redirect users to when a challenge is issued. The Single Sign-On Service is responsible for:

  1. Authenticating the user.
  2. Generating a JWT.
  3. Redirecting the user to the Authentication Service.

The Single Sign-On Service endpoint is optional.



  • Name: Security provider name. The name appears in the Authentication Service URL. It may also appear on the login form.
  • Type: JWT SSO


  • Audience: Audience. URI. Used to validate the JWT aud claim. Example:
  • Issuer: Issuer name. String, URI recommended. Used to validate the JWT iss claim. Case-sensitive.


Type Description
Single Sign-On Service Location that users will be redirected to when a challenge is issued to the JWT SSO security provider. Optional, absolute URI.


Usage Type Description
Signature Validation X.509 Certificate RSA Public Key Used to validate the JWT signature.


The OAuth security provider supports the following additional parameters:

Parameter Default Description
AllowHttpGet False Indicates that the authentication endpoint should allow HTTP GET requests.
ClockSkew 5 Number of minutes. Positive integer. Used when validating the JWT iat, nbf and exp claims.
MaxLifetime 5 Number of minutes. Positive integer. Used to validate the iat claim
SigningAlgorithm RS256 JWT signing algorithm RS256 is the only algorithm currently supported.