Login in Kundo Knowledge and Kundo Forum using SSO
Sometimes it’s important that a forum or a knowledge base is only accessible to a certain group of users. As the customer you will generally already have a system in place that can distinguish who is allowed access and who is not.
For such cases we can enable login integration for you. This type of special login is usually implemented as a consultancy project as per the hourly rate stated in our joint agreement. Always contact us before you implement integration, so we can discuss details and arrangements together.
This article describes a common solution for SSO (see also other options for customised access control). We suggest this solution for customers, as it provides a good user experience, is relatively easy to implement in technical terms and good support is already available at Kundo.
Our most common solution for SSO is based on JWT for sending trusted user data from you to us. Our solution checks authorisation by passing the user on to you, at which point you can authenticate the user and then pass them to us. All this commonly involves just a few redirects that the user does not notice (if already logged in with you) to ensure the user experience for your users is as smooth as possible.
For an introduction to JWT, we recommend JWT.io, which also has sample code in a number of different programming languages.
The user visits your forum or knowledge base.
We detect that they are not logged in and pass them on to your authentication endpoint. We include the address that the user tried to access.
You verify that the user has the appropriate rights in whatever way you choose, and subsequently generate a token (JWT) and transmit it to us. This includes the address that the user was trying to access.
We read the JWT, verify that it is correct, and log the user in.
Since the user is now logged in, we do not need to send any more requests to you until the login expires. Then the process begins again.
What we need to know from you:
The URL of your authentication endpoint. In the URL you can also include the details you need to identify that the login attempt comes from the specific forum or knowledge base, e.g. as a query parameter.
The password that you use to sign JWTs.
We will forward unknown users to this URL, with the origin URL under the query parameter ‘next’.
You then perform authentication, using the following details:
It must be verified that the customer has access to the applicable forum or knowledge basde. The address for the relevant forum or knowledge base is sent as a parameter if you want to have different rights in different channels.
If access is permitted, you should redirect the client to https://[address of your forum]/auth/custom_auth2.
The redirect must include your JWT token under the query parameter ‘jwt’.
The redirect must retain the value we sent under the query parameter ‘next’, using the same parameter name. Remember that the value we send is already URL-encoded, so you do not need to URL-encode again. If the parameter is missing, the customer will end up on the start page for the forum or knowledge base.
In order for us to accept your token:
It must be signed using an algorithm we have agreed in advance. We suggest RS512, RS384, RS256 for asymmetric signature or HS256, HS384, HS512 for signature using a shared key.
The ‘exp’ and ‘iat’ fields must be present as claims. Ideally set ‘exp’ just a short time in the future (as a suggestion, one minute). We will not reuse tokens.
The ‘email’ and ‘name’ fields must be present as claims, and will be used in our system to identify the user. In the case of forums, the name you indicate there is the name that will be displayed when they write posts.
Once we have verified the user’s token, we will remember the login for 24 hours. At the end of this period the process is repeated. For a smooth user experience, you should therefore ensure that you redirect users based on existing logins with you in the first instance, rather than always requiring manual login every time.
If we have agreed on a signature using a shared key, a secret string that we both know is needed. Contact us on firstname.lastname@example.org so we can create one and share it with you in a secure manner. If asymmetric signature is to be used, you need to inform us of your public key (we will then not know your private key).