Build your own SSO view
We provide our SSO view implementation out of the box as part of KWS. It is designed to provide a single sign-on experience for all the applications on your platform. By centralising user sign-in, registration, and account management, you can provide a secure and consistent experience for kids across your platform, based on the industry standard OAuth 2.0 authorisation protocol.
In rare cases it may be desirable to build and host your own fully customisable version of the SSO view. This section describes how to do that.
UI guidelines
Follow these UI guidelines to ensure that the screens you build remain compliant while achieving the best UX for your users:
SSO view configuration
The default SSO view that KWS provides is designed to let users activate their accounts with any KWS-integrated application in your platform. To get the most out of KWS, we strongly recommend that you build your own SSO view in the same way.
Our SSO view uses the following query parameters:
- clientId: Public identifier of the app for which the user is being authenticated. This can be used with the Get App Config endpoint to get the configuration data for the app, including branding details and an app ID which is required for user activation. You can find the clientId on the Control Panel’s Integration tab.
- redirectUri: This is the URL that successfully authenticated users are redirected to after they activate their app account. For security, it must match a URL that you add to the app via the Control Panel’s Integration tab.
For more information about the Integration tab, see KWS API.
When the SSO view is initialised, it should use the clientId passed in the query params to retrieve the configuration of the view from the API. This configuration includes information for applying branding to the view and for verifying the redirect URI.
curl -X GET \
https://{API_URL}/v1/apps/config?oauthClientId=<appClientId> \
-H 'Content-Type: application/json' \
-H 'Accept-Language: en' \
-H 'Accept: application/json, text/plain, */*'See the Get App Config endpoint for all options.
Register the user
To register a user, you need a form that allows them to enter a username and password. Depending on the configuration of your app, they typically also need to enter a date of birth and a parent’s email address. The form data should be submitted to the Create User endpoint.
curl -X POST \
https://{API_URL}/v2/users \
-H 'Content-Type: application/json' \
-d '{
"username": "MyUsername",
"password": "password",
"parentEmail": "myparent@superawesome.com"
}'When the user has been registered successfully, the SSO view must log the user in and activate them in the app before an authorisation code can be retrieved and sent back to the app. For instructions to do this, see User login below.
User login
To log a user in, first the OAuth Password Grant must be used to gain an access token with SSO scope. This can be done by calling the /oauth/token endpoint:
curl -X POST \
https://{API_URL}/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept-Language: en' \
-H 'Authorization: Basic c3VwZXJhd2Vzb21lY2x1YjpzdXBlcmF3ZXNvbWVjbHVi' \
-H 'Accept: application/json, text/plain, */*' \
-d 'grant_type=password&username=<username>&password=<password>'When the user is successfully authenticated, the response returns an access token in the form of a JSON Web Token (JWT) which has the scopes ‘sso’ and ‘user’.
This token should not be exposed outside of the SSO app. However, you can store it and use it to retrieve an auth code, which can be returned to the application and used to get a token with the right scope.
It is recommended that you store this token in some way, for example in Localstorage, so it can be used later by the user if they return to the app and wish to log in again, or if they wish to manage their account.
For this endpoint you must use basic authentication via the Authorization
header, as in the above example.
Now that you have the token, you can call the authorise endpoint:
curl -X POST \
https://{API_URL}/oauth/authorise \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept-Language: en' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <token>' \
-d 'response_type=code&client_id=<appClientId>&redirect_uri=<appRedirectUri>' On getting a successful response, redirect the user to the same ‘redirect URI’ passed to this request.
If you get a ‘403’ error response from this request, it means the user is not yet activated in the application. To activate the user, follow the instructions in Activate the user below, and then attempt the login request again.
Activate the user
Whether the user has just created an account or is logging in to an existing account, they must be activated in the app before they can be authenticated and provided with a token scoped to the app.
To activate the user in the app, make a request to the Activation endpoint:
curl -X POST \
https://{API_URL}/v1/users/<userId>/apps \
-H 'Content-Type: application/json' \
-H 'Accept-Language: en' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <token>' \
-d '{"username":"<username>","appName":"<appClientId>","permissions":[]}'Forgot password/reset password
The KWS SSO view enables users to reset their password. To provide this functionality in your own app, you need to implement two separate pages:
- A page to collect the user’s username and trigger the ‘forgot password’ email.
- A page to reset the user’s password.
For both of the endpoints described in this section, the appName parameter (which takes the ID of your application as its value) is optional. If provided, it is used to apply your app-specific branding to the emails that KWS sends.
Forgot password
First, call the forgot-password endpoint, providing the target username and optionally the client ID of your application. This triggers an email to be sent to the child (or the parent, if the child has no email address associated with their account), containing a link with a password reset token.
You need to ask your Implementation Manager to configure the ‘reset password’ URL in order for these generated emails to link to your custom SSO view.
curl -X POST \
https://{API_URL}/v1/users/forgot-password \
-H 'Content-Type: application/json' \
-H 'Accept-Language: en' \
-H 'Accept: application/json, text/plain, */*' \
-d '{"username":"<username>","appName":"<optional appName>"}'For security reasons, this endpoint always returns 204 No Content, whether or not the specified user exists in KWS.
Reset password
When the user clicks on the ‘reset password’ link in the email and lands on your reset password page, your application must:
- extract the
password_reset_tokenquery parameter from the URL. - use this to call the reset-password endpoint, along with the user’s new password and optionally the client ID of your application.
This endpoint triggers an email to be sent to the child (or parent, if the child has no email address associated with their account), confirming the password change.
curl -X POST \
https://{API_URL}/v1/users/reset-password \
-H 'Content-Type: application/json' \
-H 'Accept-Language: en' \
-H 'Accept: application/json, text/plain, */*' \
-d '{"token":"<token>","newPassword":"<newPassword>","appName":"<optional appName>"}'Delete user account
To comply with GDPR, your SSO view must allow a user to delete their account.
To delete the user’s account on their behalf, call the delete-account endpoint, specifying the user’s ID in the URL and their password in the request body.
When calling this endpoint, you must provide an access token which has the sso scope, such as that obtained via the login endpoint. See User login above for more details.
curl -X POST \
https://{API_URL}/v1/users/{USER_ID}/delete-account \
-H 'Content-Type: application/json' \
-H 'Accept-Language: en' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <token>' \
-d '{"password":"<password>"}'