Clearlogin JWT Specifications

Follow

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

  1. user navigates to service provider service_login_url
  2. service_login_url forwards to Clearlogin sso_login_url with JWT request.
  3. Clearlogin generates a JWT payload and posts to access_url
  4. access_url verifies the payload and creates the user's session, redirecting where necessary.

Log out flow

  1. User navigates to Service Provider’s standard logout url.
  2. Session should be identified as JWT and redirected to Clearlogin sso_logout_url which will process logouts for all services (Single Logout).
  3. During this process, the user will be silently navigated to your service_logout_url to destroy their session.
  4. 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.

JWT Request

sso_login_url?timestamp=3597523200&return_to=url+encoded+return+url

 

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.



JWT Payload

access_url?jwt=encoded+payload&return_to=url+encoded+return+url

 

The payload we respond with will contain the following fields as per the JWT spec:

{

    "typ": "JWT",

    "alg": "HS256"

}.

{

    "iss": "Clearlogin",

    "aud": application name,

    "iat": now,

    "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.



Single Logout

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.

secret_key

xLI0RdcM4kPzrejPyoWlgbteSQHxT9EOT191E3uChbA4pg8D

The secret key is defined by the service provider. Clearlogin does not have any involvement in its generation.

 

access_url

https://myapp.com/login/jwt

This is where Clearlogin will send the JWT payload.

 

service_login_url

https://myapp.com/login

This is where users will go to log in and be redirected to Clearlogin for sso. Clearlogin requires this for the User Dashboard.

 

service_logout_url

https://myapp.com/logout/jwt

This is where Clearlogin will navigate users to automatically terminate their session during Single Logout.

 

Clearlogin Provided Variables

sso_login_url

https://myapp-com.clearlogin.com/sp/myapp/login

This is where your users should be redirected when accessing the previously mentioned service_login_url

 

sso_logout_url

https://myapp-com.clearlogin.com/logout

This is where your users should be redirected when arriving at your standard logout process and being identified as a JWT session.

 

Have more questions? Submit a request

Comments

Powered by Zendesk