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.
Protocol¶
The JWT SSO protocol leverages the following standards:
Endpoints¶
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:
- Authenticating a JWT.
- Signing the user into Vinyl.
Example:
https://example.com/Vinyl/signin-{Provider}
Where {Provider}
is the Vinyl security provider name. See Configuration.
Parameters¶
The authentication service endpoint defines the following parameters:
jwt
– JSON Web Token. Required.return_to
– Relative URI. Optional.
jwt¶
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: https://example.com/Vinyl |
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": "example.com",
"aud": "https://example.com/Vinyl",
"sub": "Arthurd.Dent",
"iat": 1652473593,
"exp": 1652473893,
"groups": [
"Users",
"Employees",
"Sales"
]
}
return_to¶
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.
Example:
/app/Sales/Leads?LeadId=1234
Vinyl will validate the URI to guard against open-redirect attacks.
Methods¶
POST¶
By default, the authentication endpoint will accept a form post:
POST /Vinyl/signin-JWTSSO HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 31
jwt={jwt}&return_to={return_to}
GET¶
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
Host: example.com
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:
- Authenticating the user.
- Generating a JWT.
- Redirecting the user to the Authentication Service.
The Single Sign-On Service endpoint is optional.
Configuration¶
Settings¶
- Name: Security provider name. The name appears in the Authentication Service URL. It may also appear on the login form.
- Type: JWT SSO
Tokens¶
- Audience: Audience. URI. Used to validate the JWT
aud
claim. Example:https://example.com/Vinyl
. - Issuer: Issuer name. String, URI recommended. Used to validate the JWT
iss
claim. Case-sensitive.
Endpoints¶
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. |
Certificates¶
Usage | Type | Description |
---|---|---|
Signature Validation | X.509 Certificate | RSA Public Key Used to validate the JWT signature. |
Properties¶
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. |