Configure User Registration

Step 1 - Configure the Email Server

The user registration system requires an SMTP server in order to send emails during the registration process (for example to validate a user's email address) as well as for the "forgot password" feature.

The SMTP server must allow forwarding to any domain that is to be supported for registration. If authentication is used, the account must also have permission to forward to the required domains.

To configure this, add the following section to the SuperADMIN local.conf configuration file. If you installed to the default directory, this file is located in C:\ProgramData\STR\SuperADMIN\server\config\local.conf.

CODE

str.superadmin {
  email {
        smtpHost: "localhost"
        smtpPort: 25
        startTls: false
        auth {
            enabled: false
            username: "changeme"
            password: "changeme"
        }
        debug: false
    }
}

You will need to modify this to match the appropriate values for your SMTP server:

Replace localhost with the hostname of your SMTP server.
Change the port number if necessary.
If your SMTP server requires authentication, set the appropriate username and password and change enabled to true.

When you have finished making changes, restart the SuperADMIN/SuperSERVER service.

Proxy Server Configuration (Optional)

SuperADMIN can be configured to send the emails via a forwarding web proxy if necessary. To use a web proxy, you can add the following optional configuration keys to the local.conf configuration file:

Key	Description	JavaMail Equivalent
str.superadmin.email.proxy.host	The hostname or IP address of the web proxy. The hostname must be set in order to use a proxy (it can also be set using the JavaMail property under `str.superadmin.email.javaMail`).	mail.smtp.proxy.host
str.superadmin.email.proxy.port	The port to use to connect to the proxy. Defaults to 80 if not specified.	mail.smtp.proxy.port
str.superadmin.email.proxy.username	The username to use to login to the proxy.	smtp.proxy.user
str.superadmin.email.proxy.password	The password to use to login to the proxy.	mail.smtp.proxy.password
str.superadmin.email.javaMail	This key can be used to pass any JavaMail property to JavaMail. To do so, this key must contain a flat list of keys that have string values. Enclose both the keys and values in quotes. The keys will be passed as-is to JavaMail.

For example:

Basic Proxy Configuration

CODE

str.superadmin {
  email {
        smtpHost: "localhost"
        smtpPort: 25
        startTls: false
        auth {
            enabled: false
            username: "changeme"
            password: "changeme"
        }
        debug: false
        proxy {
            host: "physical-build4"
            port: 8888
        }
    }
}

JavaMail Example

CODE

str.superadmin {
  email {

        ...

        proxy {
            host: "physical-build4"
            port: 8888
        }

        javaMail {
            "mail.smtp.localport": "5000"
            "mail.smtp.noop.strict": "true"
        }

    } 
}

Step 2 - Configure Groups for Registered Users

The user registration system can automatically add new registered users to one or more user groups. This allows you to set some default permissions for newly registered users (including the datasets they can access) and allow users to login immediately after registering. To configure this:

Create a group in SuperADMIN for registered users. For example:
CODE
```
account creategroup RegisteredUsers
```
Set the catalogue permissions for this group to an appropriate level for new users. You should ensure that they have access to at least one dataset otherwise they will not be able to log in to SuperWEB2.
Configure the user registration system to add new users to this group using the following command in SuperADMIN:
CODE
```
cfg global superadmin.selfreg.addToGroups set ["RegisteredUsers"]
```
Replace RegisteredUsers with the name of the group you created in the previous step.

You can have registered users added to multiple groups if you wish. Simply list all of the groups separated by commas. For example: cfg global superadmin.selfreg.addToGroups set ["RegisteredUsers", "AnotherGroup", "ThirdGroup"]

Make sure you configure the group to have read access to at least one dataset. If newly registered users are not added to a group with access to at least one dataset then they will not be able to log in to SuperWEB2 until their permissions are manually changed.

Step 3 - Required Configuration Adjustments

Set the From Address

By default, emails will be sent from the address changeme@changeme.spacetimeresearch.com. You should change this to a real email address for your organisation. To do so, run the following command in SuperADMIN:

CODE

cfg global superadmin.selfreg.email.fromAddress set <new_email_address>

Replace <new_email_address with the email address you want to use, enclosed in double quotes. For example:

CODE

cfg global superadmin.selfreg.email.fromAddress set "registrations@mycompany.com"

Set the URL Whitelist and (Optional) Default Host for Links

Provided your Tomcat and reverse proxy (e.g., NGINX) deployment have been configured correctly, SuperWEB2 will automatically determine the URL to use for links in registration emails that users click to verify their email address, based on the URL used to access SuperWEB2. However, you must add all possible hostnames for your deployment (and IP addresses if applicable) to a whitelist before SuperWEB2 will use those links in the emails. To add a hostname or IP address to the whitelist, use the following commands in SuperADMIN:

CODE

cfg global superadmin.selfreg.webClient.host.whitelist add <hostname_or_ip>

For example:

CODE

cfg global superadmin.selfreg.webClient.host.whitelist add "mydomain.com"
cfg global superadmin.selfreg.webClient.host.whitelist add "192.168.0.0"

To allow for subdomains, entries can begin with *.

As an optional step, if you want to ensure that all links always use the same URL regardless of the URL that is actually used by the user initiating the registration process, you can specify a default host, using the following command:

CODE

cfg global superadmin.selfreg.webClient.host.default set "mysuperwebdomain.com"

If set, the default host is automatically included in the whitelist and does not need to be added to the set of whitelisted hosts/IP addresses.

(Optional) Set the Base URL for Links

This step was required in earlier versions of SuperWEB2 to set the base URL for the links in the registration emails that users click to verify their email address, but from 9.10 onwards it has been replaced with automatic detection and the whitelist process described above.

However, if necessary, you can manually set the base URL using the following command in SuperADMIN:

CODE

cfg global superadmin.selfreg.webClient.root set <url>/webapi/jsf/user

Change the base URL to match your deployment. For example:

CODE

cfg global superadmin.selfreg.webClient.root set "https://mydomain/webapi/jsf/user"

If you choose to configure a value for the configuration key superadmin.selfreg.webClient.root then this will override the value that would otherwise be automatically set by SuperWEB2, although please note that in order for this to work, the root domain you set must be included in the host whitelist specified in the superadmin.selfreg.webClient.host.whitelist configuration key. In the above example, that would mean adding mydomain to the whitelist.

Set the User Registration API URL

The user registration process needs to communicate with SuperADMIN to complete the account creation process. To do this it sends messages to a SuperADMIN REST endpoint, so it needs to know where SuperADMIN is running.

You must run the following command in SuperADMIN to set the root URL for the SuperADMIN REST endpoint:

CODE

cfg global superadmin.selfreg.publicAPI.root set <url>:<port>

Replace <url> with an address that resolves to the machine running SuperADMIN. The standard port number is 9001.

For example:

CODE

cfg global superadmin.selfreg.publicAPI.root set "https://mysuperadminserver:9001"

If you make a change to this setting, you will need to restart SuperWEB2 for it to be applied.

The REST endpoint needs to be publicly accessible, so you must ensure that port 9001 on this machine is accessible. This is a new firewall requirement introduced with the user registration system. See Port Usage for more details.

Step 4 - Optional Configuration Adjustments

The following are some optional adjustments you may wish to make. Refer to the detailed instructions for more details:

Change the email templates	Default email templates are provided, but you will probably want to modify these to add your own branding and messaging.	Customise Email Templates
Update the support email link in error message	A number of error messages relating to user registrations include a support email link. By default this is set to use a dummy email address (support@example.com). You should change all instances to an appropriate support email for your organisation.	Add your Support Contact Email to Error Messages
Configure rate limiting and token duration	You may wish to configure rate limiting (to limit the number of emails that can be sent to any given email address within a specified time) and the length of time that a verification email link will be valid for.	Rate Limiting and Token Duration

Step 5 - Enable User Registration

The user registration system is not enabled by default. To activate it, you need to change a setting in the configuration.properties file:

Open <tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties in a text editor.

Set global.enableUserRegistration to true:

CODE

# Boolean.  Default false.
global.enableUserRegistration=true

Save your changes and restart Tomcat or the SuperWEB2 service.