The API supports the creation of sessions using a single sign-on service instead of providing a username and password. This is done by linking a single sign-on token for a specific single sign-on service to a user. While this token is linked, sessions can be started by providing a valid single sign-on response from this service, which is validated by the API.
This page describes the global working of single sign-on support in the API. For details on how to use a specific type of single sign-on service, refer to the details page for that service type. The following single sign-on service types are currently supported by the API:
To be able to use a single sign-on service, it needs to be made available in the API. This cannot currently be done using the API itself. Please contact StreamOne Support to add a single sign-on service to the API, and to guide in the implementation of single sign-on in your environment.
Managing single sign-on tokens¶
User tokens can be managed by users or applications with a role containing the user-sso-token token. This is usually assigned to the application which manages the portal on which single sign-on can be used. Normally, users cannot manager their own single sign-on tokens.
Before a user can log in using single sign-on, they need to have a single sign-on token linked to them via the user/linkssotoken action. This action takes a user, a single sign-on service, and a response. The response will be validated, and if valid the token embedded in this response will be linked to the user.
A user can only have one single sign-on token linked to it per service. Attempting to link a new token while there is already a token linked to the user for the same service results in an error. To change the token for a user, first clear the already assigned token from the user.
The single sign-on token of a user for a certain service can be cleared using the user/clearssotoken action. This action takes a user and a single sign-on service, and will removed the single sign-on token linked to the given user for the given service.
Creating a session¶
When a user has a single sign-on token linked to them, an application can create a session for that user by posting the single sign-on response of that user to the session/createwithsso action.
The application needs to obtain a single sign-on response from the user for the single sign-on service used. The details of how to do this depend on the type of the service used. When a response is obtained, this can be sent together with the service to the session/createwithsso action. This action will validate the response, extract the token, and check whether that token is linked to a known user. If a user is found, a session will be created for this user.
When the token is not linked to a known user, the status STATUS_SSO_TOKEN_UNKNOWN is returned. This can be used to create users via the API on demand when a single sign-on user first logs in. The application can create a user via the user/create action, and immediately link the received single sign-on token to it using the user/linkssotoken action. When this is done, the login can be attempted again to create a session for the newly created user. Be sure to assign the desired roles to the newly created user, and to create an account for them if desired.