An inbound authentication protocol to implement JWT based SSO for your application with WSO2 Identity Server.
Before we dive into the topic, I hope you know the terms, JWT and SSO.
You may aware of the protocols used to implement SSO on your application such as SAML and OpenID Connect (OIDC). Those are well-known protocols used to implement SSO and almost all the identity providers support it. You may refer configuring SSO in WSO2 Identity Server though.
In the same context, the JWT SSO is a kind of protocol used to implement SSO on your application.
In a concise manner,
We can say, the JWT SSO is an authentication protocol used to authenticate the user based on the JWT token. In other words, the application relies on the JWT token and uses the JWT token as the source of authentication in the SSO flow. As an example, the Thinkific LMS and Zendesk Support Ticket System provide the SSO feature through the JWT SSO protocol.
The high-level architecture of the authentication flow can be depicted using the below diagram.
In general, those applications require an authentication request to be made as follows.
https://applicationdomain.com/jwt?jwt={payload}Once the application receives the JWT token, it verifies the JWT token, get the user claims from the JWT token and it will let the user sign in to the application without prompting the sign-in page of the application as it believes the user is already authenticated using the Identity Provider, in this scenario the WSO2 Identity Server.
Let’s dive into the topic!
Let’s take a scenario, where your organization is having multiple applications and to avoid signing into the application separately, you’re implementing SSO with an Identity Provider, which lets the users sign into the identity provider once and the identity provider will let the user sign in to all the required applications without prompting the sign-in page again and again (Basically the advantage of SSO).
How the JWT token comes into play in existing SSO architecture?
Let’s assume you want to implement SSO for an application, which requires the JWT token as the source of authentication. A most common example would be the Thinkific LMS as it supports implementing SSO only using the JWT SSO protocol.
Since it is not using a common SSO protocol like OIDC or SAML, we’ll have to put an extra effort to implement SSO among all the other applications in the existing architecture. However, with WSO2 Identity Server, you can easily integrate SSO into Thinkific LMS just by adding a service provider.
How JWT SSO works in WSO2 Identity Server?
Let’s depict the flow using the below diagram by taking LMS as the application you want to implement SSO.
The Login Flow
- jwtRP - The name of the relying party configured in the IDP.
- return_to - URL to redirect the user after the successful authentication.
- error_url - URL to redirect the user in case of an error occurred in LMS when processing the authentication response received from the IDP.
As usual, once the user clicks on the Login button of LMS, the user will be redirected to WSO2 Identity Server (the IDP) for authentication. When we send a request to the IDP (/identity/jwtsso), apart from the jwtRP query parameter, we can pass return_to and error_url as additional query parameters. Let’s explain how those parameters are handled in the latter part of this article.
The WSO2 IS accepts the authentication request and validates the Relying Party (Whether the provided Relying Party exists on the IDP), Return URL, and Error URL (Validates against the regex pattern configured on the IDP). If the validation is failed or anything occurred in the middle, the IDP shows an error page. But as the error occurred in the IDP, it will not make a redirection call to the error URL specified in the authentication request instead, an error page in the WSO2 IS will be shown.
Once the validation is successful, the IDP will redirect the user to the login page if an already authenticated session does not exist on the IDP. After the user is authenticated or if an already authenticated session exists on the IDP, it will generate the JWT token based on the claims configured. The LMS defines the following claims as mandatory.
{
"first_name": "Alex",
"last_name": "John",
"email": "john@mail.com"
}Apart from the claims configured in the Service Provider configuration, the IDP will always include sub (Subject), iat (Issued At Time), exp (Expiration Time), and jti (JWT ID) claims in the JWT token as below.
{
"sub": "john",
"first_name": "Alex",
"last_name": "John",
"exp": 1590221973,
"iat": 1590221853,
"jti": "49d4868d-29ba-4ffe-bce0-c2aa8c0865e1",
"email": "john@mail.com"
}The generated JWT token will then be signed using the API key of your application (in this scenario, the API key provided by the LMS) and the signed JWT token will be sent as a query parameter.
Once the LMS receives the JWT token, it will verify the JWT token based on the signature to confirm whether the JWT token was originally sent by the IDP. After validating the JWT token, it will extract the email claim, identify the user, and let the user sign in to the LMS directly without prompting the login page. If the particular user does not have an account on the LMS, it will let the user sign in to LMS after provisioning the user in the background.
If the return_to parameter is provided on the authentication request made from LMS, once the JWT token is verified, the LMS will redirect the user to the specified Return to URL. In the same context, if the error_url is provided and if any failures occurred during the JWT token verification process (Validating the JWT Signature, and verifying whether if all the mandatory claims are included in the JWT token), it will redirect the user to the specified error URL.
Specifically, return_to and error_url parameters are not handled by the IDP except validating those parameters. It implies, the LMS is the one redirect the user to the Return to URL or Error URL after it receives the JWT token as the authentication response from the IDP. If the return_to or error_url are not provided, the LMS will redirect the user to the default pages. On the WSO2 IS, we’ll have to add a regex to validate those parameters considering the security concerns involved in it.
The Logout Flow
Once the user clicks on the Logout button, the logout request through /identity/jwtsso/logout will terminate the user session on the IDP and the user will be redirected to the Logout URL configured in the SP configuration.
In conclusion,
The JWT SSO inbound authenticator is a newly built extension in WSO2 Identity Server which provides the capability of integrating SSO for the applications, which require a JWT token as the source of authentication. In this scenario, the user will be authenticated by the WSO2 Identity Server (The Identity Provider) and it will send the authenticated user details using a JWT token as a query parameter. However, as the JWT token is sent as a query parameter, we should not include any sensitive user attributes on the JWT token. Further, considering the security concerns involved with this process such as the replay attack, WSO2 Identity Server includes additional attributes in the JWT token such as JWT ID (jti) and the Expiration Time (exp), which helps to implement following security measures on the application side.
- The token should be accepted by the application for authentication within the specified time period considering the exp claim.
- The token should only be used once to authenticate the user by invalidating the token using the jti claim.
Predominantly, to confirm whether the JWT token was originally sent by the IDP, the JWT token is signed using the API key of the application and the application must validate the JWT token against the JWT signature. The default algorithm used to sign the JWT token (JWS Algorithm) is HS256 and additionally, it supports HS384 and HS512.
