This document serves to outline how Clearlogin handles JWT service providers and to provide a guideline for how to implement our expectations for the JWT flow into third party service providers.
Log in flow
- user navigates to service provider service_login_url
- service_login_url forwards to Clearlogin sso_login_url with JWT request.
- Clearlogin generates a JWT payload and posts to access_url
- access_url verifies the payload and creates the user's session, redirecting where necessary.
Log out flow
- User navigates to Service Provider’s standard logout url.
- Session should be identified as JWT and redirected to Clearlogin sso_logout_url which will process logouts for all services (Single Logout).
- During this process, the user will be silently navigated to your service_logout_url to destroy their session.
- if a return to url is specified, the user will be forwarded to that url, otherwise they will be shown the Clearlogin logged out page.
When making a JWT login request to Clearlogin's sso_login_url we require the current time as a parameter. This should be passed in the url query string as timestamp. It should be the integer unix timestamp. We have a leeway of 5 minutes on this timestamp to respond with a payload. We also support forwarding of a url the SP can use to redirect logged in users to. This should be passed in the url query string as return_to.
The payload we respond with will contain the following fields as per the JWT spec:
"aud": application name,
"exp": now + 5 minutes,
"jti": auto generated unique identifier
We use HMAC SHA-256 (HS256) to sign and encode our payloads.
We will also add any number of additional unique identifying fields as per your requirements.
These will be configurable as key value pairs, relating to your AD/OpenLDAP fields and Clearlogin user database fields. We will provide some default mappings in the claim.
"user_name": ldap cn or sAMAccountName,
"email": ldap mail
You can configure these on an app specific basis under App Connections in the Clearlogin Admin.
Clearlogin offers single logout for users to log out of all of their SAML service providers with one click. We extend this concept to JWT based services by navigating the users to a provided logout url.
Service Provider Provided Variables
These variables are set in your App Connections screen in the Clearlogin Admin.
The secret key is defined by the service provider. Clearlogin does not have any involvement in its generation.
This is where Clearlogin will send the JWT payload.
This is where users will go to log in and be redirected to Clearlogin for sso. Clearlogin requires this for the User Dashboard.
This is where Clearlogin will navigate users to automatically terminate their session during Single Logout.
Clearlogin Provided Variables
This is where your users should be redirected when accessing the previously mentioned service_login_url
This is where your users should be redirected when arriving at your standard logout process and being identified as a JWT session.