UNICORE Web Portal: Administrator Manual

JavaScript must be enabled in your browser to display the table of contents.

1. Overview

The UNICORE Portal is a web client for the UNICORE Grid middleware.
The Portal presents a user friendly interface for all the UNICORE basic
services as well as basic functionality of the UNICORE workflow system.

2.2. Download

2.3. Installation and configuration

Unzip the archive into a convenient folder, which will result in the following directory structure

bin: start/stop/status scripts

lib: application libraries

conf: configuration files

webcontent: libraries for Java webstart application(s) used by the portal
as well as VAADIN folder with UI theme files, icons, CSS style sheets

logs: default log directory

doc: readme, changelog and others

2.4. Signing Java webstart archives and applet(s)

The application includes parts that are run via Java webstart or
the Java applet mechanism.
These need to be signed using the portal credential. Signing
requires the "jarsigner" application from the Java Development
Kit (JDK).

A script unicore-portal-sign.sh is provided in the bin folder which signs
the jar files. Please review this script and provide the proper
values for your portal credential.

This process has to be done only once before running the portal
for the first time.

2.5. Preferences file

The main configuration file is <portal home>/conf/portal.properties
This file contains central settings such as host and port of the
server. You must review it before starting the portal.

2.6. Logging

The portal log files are located in <portal home>/logs folder. By default the level of logging is set to INFO
but you can edit that in the <portal home>/conf/logging.properties file.

3. Portal configuration - credentials

3.1. Configuration file

By default, the portal checks for the existence of a file <portal home>/conf/portal.properties and reads
settings from there.

The configuration file can contain default settings for many options,
which are given in the form <option name>=<value> where <option name> is the attribute.
The property values may contain variables in the form ${VAR_X},
which are automatically replaced with the environmental variable values with the same name.

In the default configuration, DEMO-CA certificates are accepted, and
the portal uses a certificate issued by the DEMO-CA. This will allow
to test the portal against a UNICORE server demo installation.
Furthermore, a "demo user" login is provided, however the credentials
used by this account can be configured. If you wish to modify
anything, please refer to the comments in the property file.

For example, to set your keystore, truststore and registry, the file would
contain the following settings

To protect your passwords, you should make the file non-readable by others,
for example on Unix using a command such as chmod 600 preferences

3.2. Credential and truststore options

In general you need a keystore containing your identity in order
to use UNICORE, as well as a truststore file (or directory) containing trusted
certificates. There are also other options available for authentication discussed below.

A full list of options related to credential and truststore management is available in
the following tables.

Table 1. Credential properties

Property name

Type

Default value / mandatory

Description

portal.credential.path

filesystem path

mandatory to be set

Credential location. In case of jks, pkcs12 and pem store it is the only location required. In case when credential is provided in two files, it is the certificate file path.

portal.credential.format

[jks, pkcs12, der, pem]

-

Format of the credential. It is guessed when not given. Note that pem might be either a PEM keystore with certificates and keys (in PEM format) or a pair of PEM files (one with certificate and second with private key).

portal.credential.password

string

-

Password required to load the credential.

portal.credential.keyPath

string

-

Location of the private key if stored separately from the main credential (applicable for pem and der types only),

portal.credential.keyPassword

string

-

Private key password, which might be needed only for jks or pkcs12, if key is encrypted with different password then the main credential password.

portal.credential.keyAlias

string

-

Keystore alias of the key entry to be used. Can be ignored if the keystore contains only one key entry. Only applicable for jks and pkcs12.

Table 2. Truststore properties

Property name

Type

Default value / mandatory

Description

portal.truststore.allowProxy

[ALLOW, DENY]

ALLOW

Controls whether proxy certificates are supported.

portal.truststore.type

[keystore, openssl, directory]

mandatory to be set

The truststore type.

portal.truststore.updateInterval

integer number

600

How often the truststore should be reloaded, in seconds. Set to negative value to disable refreshing at runtime. (runtime updateable)

--- Directory type settings ---

portal.truststore.directoryConnectionTimeout

integer number

15

Connection timeout for fetching the remote CA certificates in seconds.

portal.truststore.directoryDiskCachePath

filesystem path

-

Directory where CA certificates should be cached, after downloading them from a remote source. Can be left undefined if no disk cache should be used. Note that directory should be secured, i.e. normal users should not be allowed to write to it.

portal.truststore.directoryEncoding

[PEM, DER]

PEM

For directory truststore controls whether certificates are encoded in PEM or DER.

In case of openssl truststore, controls which (and in which order) namespace checking rules should be applied. The REQUIRE settings will cause that all configured namespace definitions files must be present for each trusted CA certificate (otherwise checking will fail). The AND settings will cause to check both existing namespace files. Otherwise the first found is checked (in the order defined by the property).

portal.truststore.opensslPath

filesystem path

/etc/grid-security/certificates

Directory to be used for opeenssl truststore.

--- Revocation settings ---

portal.truststore.crlConnectionTimeout

integer number

15

Connection timeout for fetching the remote CRLs in seconds (not used for Openssl truststores).

portal.truststore.crlDiskCachePath

filesystem path

-

Directory where CRLs should be cached, after downloading them from remote source. Can be left undefined if no disk cache should be used. Note that directory should be secured, i.e. normal users should not be allowed to write to it. Not used for Openssl truststores.

portal.truststore.crlLocations.*

list of properties with a common prefix

-

List of CRLs locations. Can contain URLs, local files and wildcard expressions. Not used for Openssl truststores. (runtime updateable)

portal.truststore.crlMode

[REQUIRE, IF_VALID, IGNORE]

IF_VALID

General CRL handling mode. The IF_VALID setting turns on CRL checking only in case the CRL is present.

portal.truststore.crlUpdateInterval

integer number

600

How often CRLs should be updated, in seconds. Set to negative value to disable refreshing at runtime. (runtime updateable)

portal.truststore.ocspCacheTtl

integer number

3600

For how long the OCSP responses should be locally cached in seconds (this is a maximum value, responses won’t be cached after expiration)

portal.truststore.ocspDiskCache

filesystem path

-

If this property is defined then OCSP responses will be cached on disk in the defined folder.

portal.truststore.ocspLocalResponders.<NUMBER>

list of properties with a common prefix

-

Optional list of local OCSP responders

portal.truststore.ocspMode

[REQUIRE, IF_AVAILABLE, IGNORE]

IF_AVAILABLE

General OCSP ckecking mode. REQUIRE should not be used unless it is guaranteed that for all certificates an OCSP responder is defined.

portal.truststore.ocspTimeout

integer number

10000

Timeout for OCSP connections in miliseconds.

portal.truststore.revocationOrder

[CRL_OCSP, OCSP_CRL]

OCSP_CRL

Controls overal revocation sources order

portal.truststore.revocationUseAll

[true, false]

false

Controls whether all defined revocation sources should be always checked, even if the first one already confirmed that a checked certificate is not revoked.

Controls how many times the client should try to call a failing web service. Note that only the transient failure reasons cause the retry. Note that value of 0 enables unlimited number of retries, while value of 1 means that only one call is tried.

Controls whether server’s hostname should be checked for matching its certificate subject. This verification prevents man-in-the-middle attacks. If enabled WARN will only print warning in log, FAIL will close the connection.

portal.client.sslAuthnEnabled

[true, false]

true

Controls whether SSL authentication of the client should be performed.

portal.client.sslEnabled

[true, false]

true

Controls whether the SSL/TLS connection mode is enabled.

portal.client.wsCallRetryDelay

integer number

10000

Amount of milliseconds to wait before retry of a failed web service call.

--- HTTP client settings ---

portal.client.http.allow-chunking

[true, false]

true

If set to false, then the client will not use HTTP 1.1 data chunking.

portal.client.http.connection-close

[true, false]

false

If set to true then the client will send connection close header, so the server will close the socket.

portal.client.http.connection.timeout

integer number

20000

Timeout for the connection establishing (ms)

portal.client.http.maxPerRoute

integer number

6

How many connections per host can be made. Note: this is a limit for a single client object instance.

portal.client.http.maxRedirects

integer number

3

Maximum number of allowed HTTP redirects.

portal.client.http.maxTotal

integer number

20

How many connections in total can be made. Note: this is a limit for a single client object instance.

portal.client.http.socket.timeout

integer number

0

Socket timeout (ms)

--- HTTP proxy settings ---

portal.client.http.nonProxyHosts

string

-

Space (single) separated list of hosts, for which the HTTP proxy should not be used.

portal.client.http.proxy.password

string

-

Relevant only when using HTTP proxy: defines password for authentication to the proxy.

portal.client.http.proxy.user

string

-

Relevant only when using HTTP proxy: defines username for authentication to the proxy.

portal.client.http.proxyHost

string

-

If set then the HTTP proxy will be used, with this hostname.

portal.client.http.proxyPort

integer number

-

HTTP proxy port. If not defined then system property is consulted, and as a final fallback 80 is used.

portal.client.http.proxyType

string

HTTP

HTTP proxy type: HTTP or SOCKS.

Table 4. HTTP options for the Portal

Property name

Description

portal.client.http.proxyHost

HTTP(s) proxy to use

portal.client.http.proxyPort

Port of the HTTP(s) proxy to use

portal.client.http.nonProxyHosts

Space separated list of host name fragments for which NOT to go via the proxy. If the target URL contains such a fragment, it is accessed directly

portal.client.http.connection.timeout

Timeout to use when establishing a HTTP connection

portal.client.http.socket.timeout

Timeout to use when reading/writing from/to HTTP connection

For example, to set the timeout when establishing a connection to 5 seconds, you would use

portal.client.http.connection.timeout=5000

4. Portal configuration - authentication

The web portal offers various possibilities for authentication and registration of users. Currently implemented are:

a demo account for testing

authentication with a user certificate that has been imported in the browser

authentication via kerberos

username/password

authentication via Unity

4.1. Portal authentication and registration options

Table 5. Enabled authentication and registration types

Property name

Type

Default value / mandatory

Description

portal.authn.enabledFacilities

string

mandatory to be set

List of the enabled authentication facilities names.
For example: DEMO, TLS, AUTH-USER, KRB5 or AUTH-SAML but it can be any other string (please see the note below).

portal.registration.enabledFacilities

string

mandatory to be set

List of the enabled registration facilities names.
For example: REG-USER, REG-TLS, REG-SAML but it can be any other string (please see the note below).

For example to enable the possibility for the user to login with username/password, as well as with their certificate,
imported in the browser, and a demo login for testing, the following line has to be configured

portal.authn.enabledFacilities=AUTH-USER TLS DEMO

To enable registration with username/password as well as
register certificates, imported in the browser, you need to enable the following

portal.registration.enabledFacilities=REG-USER REG-TLS

Table 6. Common properties for all authentications

Property name

Type

Default value / mandatory

Description

portal.authn.facility.<type>.description[.*]

string can have subkeys

mandatory to be set

Description of the authenticator, to be presented in the login screen.

portal.authn.facility.<type>.description.[.*]

string can have subkeys

-

Under this prefix could be specified language specific descriptions of the authenticator.

portal.authn.facility.<type>.name[.*]

string can have subkeys

mandatory to be set

Human readable name of the authenticator, to be presented in the login screen. Should be unique among all authenticators.

portal.authn.facility.<type>.name.[.*]

string can have subkeys

-

Under this prefix could be specified language specific names of the authenticator.

The table represents a few properties that are common for all types of authentication
where <type> is the string corresponding to one of the values in the enabled statement’s right hand side.
Please note that

Note

In the statement portal.*.enabledFacilities=<enabled_type> (where * is any of "authn" and "registration")
the value of <enabled_type> can be any string.
However it is important that the value of <enabled_type> from the property portal.*.enabledFacilities = <enabled_type>
is equal to the <enabled_type> in portal.authn.facility.<enabled_type>.*=…

4.2. Using Unity

If your Grid installation is using the Unity identity management service (see http://www.unity-idm.eu),
you can setup the configuration file with the help of the following properties.

Table 10. SAML properties

Property name

Type

Default value / mandatory

Description

portal.authn.facility.AUTH-SAML.autoRegister

[true, false]

false

If true then remotely authenticated users will be automatically registered locally. Note that in such case it is important to ensure that the IdP provides required attributes.

portal.authn.facility.AUTH-SAML.description[.*]

string can have subkeys

mandatory to be set

Description of the authenticator, to be presented in the login screen.

portal.authn.facility.AUTH-SAML.description.[.*]

string can have subkeys

-

Description of the authenticator, to be presented in the login screen.

portal.authn.facility.AUTH-SAML.emailAttribute

string

email

Name of the SAML attribute with the user’s e-mail.

portal.authn.facility.AUTH-SAML.idpLogoutUrl

string

-

If defined then the value will be used as a URL of a SAML HTTP logout endpoint of the IDP. For Unity the URL is https://HOST:PORT/UNICORE-WEB-ENDPOINT/SLO-WEB. If the value is left undefinedthen single logout functionality won’t be used. Note that for integrating SLO with Unity, the Unity unicore endpoint configuration must include in the UNICORE portal SP definition also portal’s certificate and both postLogoutResponseEndpoint and postLogoutResponseEndpoint (both set to the base portal URL). Minimum version of Unity is 1.8.0.

portal.authn.facility.AUTH-SAML.idpName

string

mandatory to be set

Short, human readable name of the Identity Provider.

portal.authn.facility.AUTH-SAML.idpTruststore.[.*]

string can have subkeys

-

Under this prefix truststore should be configured using standard UNICORE truststore settings. The truststore must contain ONLY certificates of trusted Identity Providers and NO other certificates, in particular NO CA certificates. Typically the truststore will contain only one certificate of the IdP in question, but can also conatin other IdPs certificates.

portal.authn.facility.AUTH-SAML.idpUrl

string

mandatory to be set

Full URL of the SAML Identity Provider to be used.

portal.authn.facility.AUTH-SAML.localSamlId

string

-

Full identifier of this SAML Service Provider, in SAML Entity format (typically a URI). It is used to identify this service to the Identity Provider. Identity Provider checks if this identifier is matching its configuration. When using UNICORE aware IdP this property will be automatically set to portal’s certificate DN. In other cases it must be set.

portal.authn.facility.AUTH-SAML.name[.*]

string can have subkeys

mandatory to be set

Human readable name of the authenticator, to be presented in the login screen. Should be unique among all authenticators.

portal.authn.facility.AUTH-SAML.name.[.*]

string can have subkeys

-

Human readable name of the authenticator, to be presented in the login screen. Should be unique among all authenticators.

where PORTAL-CERT is a name of a portal’s certificate as defined in pki.properties and the PORTAL-URL is simply the base URL of the portal (e.g. https://host:port/portal)

4.4. Account registration

Typically users need to be registered in the portal server in order to be able to login properly.
The table represents a few properties that are common for all types of registration
where <type> is the string corresponding to one of the enabled types of registration.

Table 11. Basic registration properties

Property name

Type

Default value / mandatory

Description

portal.registration.facility.<type>.description

string

empty string

Description of the registrator, to be presented in the registration screen.

portal.registration.facility.<type>.description.[.*]

string can have subkeys

-

Description of the registrator, to be presented in the login screen.

portal.registration.facility.<type>.name

string

mandatory to be set

Human readable name of the registrator, to be presented in the login screen. Should be unique among all registrators.

portal.registration.facility.<type>.name.[.*]

string can have subkeys

-

Human readable name of the registrator, to be presented in the login screen. Should be unique among all registrator.

Even when the authentication happens via Unity, the portal still needs the user to be registered.
The necessity of manual registration by the user can be avoided if portal.authn.facility.AUTH-SAML.autoRegister is set to true.
Other properties concerning the registration of Unity users include

Table 12. SAML properties for registration

Property name

Type

Default value / mandatory

Description

portal.registration.facility.REG-SAML.description[.*]

string can have subkeys

mandatory to be set

Description of the authenticator, to be presented in the login screen.

portal.registration.facility.REG-SAML.description.[.*]

string can have subkeys

-

Description of the authenticator, to be presented in the login screen.

portal.registration.facility.REG-SAML.emailAttribute

string

email

Name of the SAML attribute with the user’s e-mail.

portal.registration.facility.REG-SAML.idpName

string

mandatory to be set

Short, human readable name of the Identity Provider.

portal.registration.facility.REG-SAML.idpTruststore.[.*]

string can have subkeys

-

Under this prefix truststore should be configured using standard UNICORE truststore settings. The truststore must contain ONLY certificates of trusted Identity Providers and NO other certificates, in particular NO CA certificates. Typically the truststore will contain only one certificate of the IdP in question, but can also conatin other IdPs certificates.

portal.registration.facility.REG-SAML.idpUrl

string

mandatory to be set

Full URL of the SAML Identity Provider to be used.

portal.registration.facility.REG-SAML.localSamlId

string

-

Full identifier of this SAML Service Provider, in SAML Entity format (typically a URI). It is used to identify this service to the Identity Provider. Identity Provider checks if this identifier is matching its configuration. When using UNICORE aware IdP this property will be automatically set to portal’s certificate DN. In other cases it must be set.

portal.registration.facility.REG-SAML.name[.*]

string can have subkeys

mandatory to be set

Human readable name of the authenticator, to be presented in the login screen. Should be unique among all authenticators.

portal.registration.facility.REG-SAML.name.[.*]

string can have subkeys

-

Human readable name of the authenticator, to be presented in the login screen. Should be unique among all authenticators.

portal.registration.facility.REG-SAML.nameAttribute

string

cn

Name of the SAML attribute with the user’s name.

portal.registration.facility.REG-SAML.organizationAttribute

string

o

Name of the SAML attribute with the user’s organization.

portal.registration.facility.REG-SAML.photoAttribute

string

jpegPhoto

Name of the SAML attribute with the user’s photo.

portal.registration.facility.REG-SAML.requireAttributesFromIdp

[true, false]

false

If set to true the IdP must provide at least the email and name attributes in the returned assertion. What is more the user can not edit them. If false then editing is possible and lack of attributes from IdP is not considered a problem.

Example of setting the properties of the username/passwrod registration

portal.registration.facility.REG-USER.type=username
portal.registration.facility.REG-USER.name=Username registration
portal.registration.facility.REG-USER.description=Register a new local account, for logging with username and password
portal.registration.facility.REG-USER.minPasswordLength=6
portal.registration.facility.REG-USER.requireSecurePassword=false

5. Portal configuration - server options, preferences and UI

5.1. Server options

Table 14. Portal server properties

Property name

Type

Default value / mandatory

Description

portal.server.address.<NUMBER>

list of properties with a common prefix

mandatory to be set

URLs to bind to. Both http and https can be used.

portal.server.resourceBase

string

.

Web application resources base path.

portal.server.webconfigPath

string

conf/web.xml

Web application config file (web.xml) path.

5.2. User preferences

The following table represents how to setup a connection to the database where the user preferences are to be stored.

Table 15. User preferences properties

Property name

Type

Default value / mandatory

Description

--- Database ---

portal.userprofiles.dialect

[h2, mysql]

h2

Database SQL dialect. Must match the selected driver, however sometimes more then one driver can be available for a dialect.

portal.userprofiles.driver

Class extending java.sql.Driver

org.h2.Driver

Database driver class name. This property is optional - if not set, then a default driver for the chosen database type is used.

5.3. Core and UI configuration options

Table 16. Portal configuration properties

Property name

Type

Default value / mandatory

Description

portal.core.discoveryMaxAllowedLoad

floating point number

3

Load is defined as an average, cumulative number of refreshes that are supposed to be performed per second. This property defines up to what load the discovery is using the regular refresh intervals. When the normal load threshold is exceeded, the slow down mechanism is activated. The slow down mechanism increases the intervals so that the discovery stays in the given threshold. The proper value depends on your machine power, especially number of CPUs. If the service generates too large load on a machine this setting should be reduced. If machine is powerfull but discovery seems to be slow, then this setting can be increased.

portal.core.discoveryMediumServiceRefresh

integer number

30000

The regular interval in ms between semi dynamic resource (TSS or SMS under SMSF) status refreshes

portal.core.discoveryRegistryRefresh

integer number

30000

The regular interval in ms between registry status refreshes

portal.core.discoveryServiceDeathCheckRefresh

integer number

60000

The regular interval in ms between status refreshes of resources for which we can expect only its removal (e.g. finished jobs)

portal.core.discoveryTopServiceRefresh

integer number

30000

The regular interval in ms between top service (TSF, global SMS, …) status refreshes

An important configuration item refers to the location where user
workspaces are stored. By default, they are stored on the
portal machine, but they can also be stored remotely on a UNICORE
storage.

Example of setting up the user workspace

If the workspace is located on the local file system, the prefix file:/// needs to be used.
portal.core.workspace.root = file:///tmp/portal-workspaces
If the workspace is located remotely on a UNICORE storage, the prefix u6:// needs to be used.
portal.grid.workspace.root = u6://<host>:<port>/<site>/services/StorageManagement?res=default_storage#portalWorkspaces

Tha table has been autogenerated. Please exchange of configuring different languages for the UI