-
Notifications
You must be signed in to change notification settings - Fork 0
Registration Configuration
This module contains the OSIAM registration functionality.
The functionality consists of three parts which will be:
- user registration
- change password mechanism
- change email mechanism
- If you use the OSIAM Server Version 0.17.1 or before please jump to the old configuration
- otherwise follow the next chapters:
This module needs a pre-installed mail server on the current System. The configuration is up to the operator, apart from the important parts for this module. These are the SMTP-port and the hostname. More information on the configuration in the following chapters.
We recommend to choose the latest OSIAM release version.
- Release Repository: http://maven-repo.evolvis.org/releases/org/osiam/
- GitHub Release Tags: https://github.com/osiam/server/releases
Download the OSIAM .war file for the registration-module
$ wget http://maven-repo.evolvis.org/releases/org/osiam/osiam-registration-module/<VERSION>/osiam-registration-module-<VERSION>.war
and the OSIAM sources
$ wget http://maven-repo.evolvis.org/releases/org/osiam/osiam-registration-module/<VERSION>/osiam-registration-module-<VERSION>-sources.jar
and unpack the sources
$ unzip osiam-registration-module-<VERSION>-sources.jar
For the registration you need to add some extension fields into the database otherwise it will not work.
The extension is configured with it's own namespace and will not conflict user defined extensions.
Start the database commandline:
$ sudo -u postgres psql
Now insert it as user osiam by calling
$ psql -f ./sql/registration_extension.sql -U osiam
while being in the directory where you unpacked the sources.
For the registration module OSIAM needs some configuration values. Create the file
/etc/osiam/osiam-registration.properties
with content based on this example
osiam.mail.from
The sender address from where the emails will be send to the user.
osiam.mail.*.linkprefix *register *changeemail *lostpassword
The controller URL on client side where the link will point to. This must be on client side and should not point directly to the osiam registration module due to security issues. The URL must end with either a '?' or a '&' character. This depends on whether you already have some parameters or not. If you don't have url parameter add the '?' character otherwise add the '&' character.
Here some examples:
osiam.html.*.url *register *changeemail *lostpassword
The controller URL on client side where the call arrives, submitted by the HTML from. This must be a URL on client side and should not point directly to the osiam registration module due to security issues.
TODO: all config values should explained
To deploy the registration module into Tomcat server the downloaded .war files need to be renamed and moved into Tomcat's webapp directory:
$ sudo mv osiam-auth-server-<VERSION>.war /var/lib/tomcat7/webapps/osiam-auth-server.war
For further information on Tomcat's configuration and how to add the /etc/osiam folder to the classpath, read this section:
For the integration in your app you need to define a client side mechanism for calling the registration module's HTTP API and to receive the user requests. The user agent will not directly speak with the registration module.
You need also to enhance the request with the authorization header and a valid access token before sending to the registration modules HTTP endpoint.
The base URI for the module is: http://HOST:PORT/osiam-registration-module
As a new feature we decided to integrate the thymeleaf template engine for creating email templates. Thymeleaf has a great integration with the actual version 4.0 of the Spring Framework which we use.
For the three mechanisms mentioned below, we created default templates in english and german as HTML files. The default template language is english. You can have a look to the templates in the resources folder.
The template file retrieving will be explained by the example of the registration email. We check the classpath for template files resolved by the following order:
- registration-*.html: Your registration email template with a specified language. You have to set the language code in the locale of the SCIM User Object and choose a standard language code (e.g. 'en') which is listed here: Supported Locales e.g. registration-en.html
- registration.html: Your registration email template which will be taken, if the locale of the user is not set or the file with the language code not found. Could be your default language template, so you have to care only about one language file.
- registration-default-*.html: You can also create default templates with a specific language, but its not necessary.
- registration-default-de.html: The default template provided by OSIAM in german
- registration-default.html: The default template provided by OSIAM in english
If you like to change also the other three email templates, you have to create files with the same concept mentioned above, but with the specific file name:
- changeemail.html
- changeemailinfo.html
- lostpassword.html
You have to copy all your template files in your folder classpath: '''registration-module/template/mail''' which you can add like the osiam-registration.properties file and you have to configure your container like mentioned above.
There are four different email templates each with two languages e.g. for the registration process we created the file registration-default.html which is the default template and will be chosen, if the user has no locale set or the locale is not available. If you want to create your own templates you have to create HTML files with the name registration.html and for other languages registration-de.html. You can chose the standard language by set it in the template without
Thymeleaf provides a wide range of functionality, which is explained in the documentation. So we just explain a few things, so you can handle your own templates.
Thymeleaf is a engine that render your java objects which referenced in your templates into readable text and also provide a wide range of logical functionality. You will write standard HTML, but with some extensions of the thymeleaf engine. With thymeleaf you add th:* attributes to HTML elements and have access to the java object attributes by the ${object.attribute}-expression. This will just be rendered, if this expression is in an th:*-tag (short introduction to the tags).
In the userinfos template file you can have a look how to access attributes of an object:
<span id="greeting" th:remove="tag" th:text="${user.name} ? (${user.name.formatted}?: 'Sir or Madam') : 'Sir or Madam'"></span>
You have access to all attributes of the user which have a getter and also with an infinity depth of object graph (e.g. user.name.givenname). In the above example, the complex name object attribute of the SCIM user
The registration will be done via a double opt in mechanism.
In the first step the user will register at osiam via the client application. Then a email will be send to the address provided in the first step. The content of that email will include a registration link with an activation token. The second step for the user will be to confirm his email address by going to that url. The client application will then send the activation request to osiam and the user will be activated if the activation token validation will be correct and the user is able to login.
There are three HTTP endpoints:
| /register | GET | no access token needed | Will provide a HTML form with the required fields for registration including validation. The request will be submitted to the URL configured in the 'osiam.html.register.url' parameter. |
| /register/create | POST | access token in the Authorization header as HTTP Bearer authorization | Will create the user with activation token and will send you the HTTP status code as response. The user will be disabled until email confirmation and he is not able to login yet. Also a email will be send to the user with the link pointing to the 'osiam.mail.register.linkprefix' config parameter |
| /register/activate | POST | access token in the Authorization header as HTTP Bearer authorization. Parameters: 'userId' and 'activationToken' from the email's confirmation link. | The activation token will be validated and the user will be enabled for login if the validation was successful. You get the HTTP status code as response. |
The change password mechanism has also multiple steps.
First of all the user has to indicate on client side that he lost his password. Then the client will send a request to the registration module. Osiam will now generate a one time password and will send the user an email with a link in the content, including the one time password. This url will also be hosted on client side an will point to the 'osiam.web.passwordlostmail.linkprefix' config parameter. The user need to go to the url from the email's content and has to enter his new password. Then the request must be submitted to the registration module where the one time password verification will be triggered and if this was successful the new password will be saved and the user is able to login with the new password.
There are three HTTP endpoint:
| /password/lostForm | GET | no access token needed | Will provide a HTML form with the required fields for change password including validation. The request will be submitted to the URL configured in the 'osiam.web.password.url' parameter. |
| /password/lost | POST | access token in the Authorization header as HTTP Bearer authorization Parameters: 'userId' for whom the password should be changed. | This will generate a one time password an sending the user an email with a confirmation link pointing to the 'osiam.web.passwordlostmail.linkprefix' config parameter including his one time password. The response will be the HTTP status code. |
| /password/change | POST | access token in the Authorization header as HTTP Bearer authorization Parameters: 'userId', 'oneTimePassword' and 'newPassword' | This will validate the one time password and save the new password if the validation will be successful. The response will be the HTTP status code and the previously updated user if successful. |
The change e-mail mechanism has also multiple steps.
First of all the user has to indicate on client side that he want to change his e-mail address. Then the client will send a request including the new e-mail to the registration module. Osiam will now generate a confirmation token and will send the user an email with a link in the content, including the confirmation token. This url will also be hosted on client side an will point to the 'osiam.web.emailchange.linkprefix' config parameter. The user need confirm his e-mail address by going to the url from the email's content. Then the request must be submitted to the registration module where the confirmation token verification will be triggered and if this was successful the new e-mail address will be stored. Finally an information e-mail will be send to the user's old e-mail address.
There are three HTTP endpoint:
| Uri | HTTP-Method | Access | Template | Description |
|---|---|---|---|---|
| GET | no access token needed | - | Will provide a HTML form with the required fields for change e-mail including validation. The request will be submitted to the URL configured in the 'osiam.web.email.url' parameter. | |
| /email/change | POST | access token in the Authorization header as HTTP Bearer authorization Parameters: 'newEmailValue' the new user's e-mail address. | This will generate a confirmation token an sending the user an email with a confirmation link pointing to the 'osiam.web.emailchange.linkprefix' config parameter including the confirmation token. The response will be the HTTP status code. | |
| /email/confirm | POST | access token in the Authorization header as HTTP Bearer authorization Parameters: 'userId', 'confirmToken' | This will validate the confirmToken and save the new e-mail if the validation will be successful. The response will be the HTTP status code and the previously updated user if successful. |