To implement Opinsys Authentication to an external service, you must receive a shared secret from Opinsys support at
tuki @ opinsys.fi. To receive it, you must provide us the following information:
Once the shared sercret is in place, the external service may redirect the user's web browser to
https://api.opinsys.fi/v3/sso with a
return_to query string key which determines where the user will be redirected back. The hostname of the
return_to URL must match the FQDN provided to us.
Example redirect URL might be:
When a user is authenticated he/she will be redirected to the URL specified in the
return_to query string key. The URL is augmented with a
jwt query string key which will contain a JSON Web Token. The external service is expected to decode this token, validate it with the given shared secret and make sure that it is not issued too long a ago or in the future. The token will contain following claims:
iatIdentifies the time at which the JWT was issued as Unix timestamp
jtiA unique identifier for the JWT
idUnique identifier for the user
schoolsList of schools the user belongs to
idUnique identifier for the school
nameHuman-readable school name
abbreviationValid POSIX name for the school
school_codeThe Finnish school code. Can be
nullif it hasn't been specified. Not all schools have this set.
rolesOne or more (there should always be at least one) roles the user has in this school. An array of strings, possible values are:
groupsList of groups the user has in the school:
idUnique identifier for the group
nameHuman-readable group name
abbreviationValid POSIX name for the group
typeType of the group. Either
null(if the type is unspecified) or one of these:
nullif the ID has not been specified. Will always be
nullfor non-student users.
In addition to those above, there are some "extra" fields that can be used, but you should NOT rely on their presence (they might not always exist). They are:
id, but this field gives it an explicit name.
deand so on) identifying the language this user primarily speaks. Can be used to localize the environment.
nullfor non-students and students who are not in a Primus-enabled school.
By default external services are not activated for all Opinsys organisations. Each organisation or individual schools must activate the external services on their behalf. They can do this directly from their management interface.
If the external service knows in advance from which organisation the user is coming from it can make the login a bit easier by specifying an additional query string key
organisation to the redirect URL:
Then users don't have to manually type their organisation during login.
When the user is coming from a Opinsys -managed desktop, Kerberos will be used for the authentication. The user will not even see the Opinsys login form in this case. He/she will be directly redirected back to
return_to URL with a
jwt key. The organisation presetting is ignored when Kerberos is active because the organisation will be read from the Kerberos ticket. This is enabled by default for all external services using Opinsys Authentication.
If you need to relay some custom fields through the Authentication service you can just add them to the
return_to URL. Just remember to escape the value.
Redirects user to:
https://example.com/path?custom_field=bar&jwt=<the jwt token>
Feel free to contact us at
dev @ opinsys.fi or open up an issue on Github if you have any trouble implementing this. If you think this documentation could be improved, contact us.