Configuration

This section will go through the various configurations required to get started with a basic functional Welle.

../_images/configuration-ov-0.png

The above illustrates the various components (Provisioning, Governance and External Integrations) in Welle. The underlying provisioning engine is WrenIDM.

Provisioning

The Provisioning component in Welle is an abstract layer on top of the underlying WrenIDM provisioning engine. It provides a convenient way for IAM administrator to perform configurations.

../_images/configuration-pv-0.png

Hint

For fresh installation of Welle, it is recommended to start configuration in the following sequence - Applications, Mappings, Access Rights, Roles.

Overview

Applications

Applications allow access to external resources. External resources are also known as target systems.

../_images/configuration-pv-1.png

An Identity Management server (also known as Provisioning Engine) can be configured to connect to multiple external resources. These are called Applications.

Mappings

Mappings link provisioning engine to applications and vice versa.

../_images/configuration-pv-2.png

After an application is configured, we can define Mappings between the Identity Management server and the application.

2 Mappings can be defined. When the Identity Management server is mapped to the application, the source is the Identity Management server and the target is the application. When the application is mapped to the Identity Management server, the source is the application and the target is the Identity Management server.

When a mapping is created, we can define which attributes from the source are mapped to corresponding attributes from the target.

Note

The purpose of attribute mappings is to ensure attributes are kept in-sync between source and target at all time. It is used during Account Creation and Account Update.

Access Rights

Access Rights define attributes that are mapped from provisioning engine to applications.

../_images/configuration-pv-3.png

Important

Access Rights only allows Mappings where the source is the Identity Management server.

A collection of attributes can be selected from the full list of attributes defined the target application. This collection is called Access Rights.

Roles

Roles refers to business roles that are a collection of access rights.

../_images/configuration-pv-4.png

Tip

Business roles help manage and structure the assignment of technical roles (access rights) in the target systems.

Use Case

An organization manages its employees’ accesses via Microsoft Active Directory. Recently, the organization wants to allow employees to work from home. Thus VPN access is required for each staff. There is also a need to assign VPN administrators.

../_images/configuration-pv-5.png

The IAM administrator creates an Application - Active Directory. As the access control in the VPN Server is delegated to Active Directory, there is no need to create an application in the Identity Management server for it.

../_images/configuration-pv-6.png

The IAM administrator then creates 2 Mappings. One from the Identity Management server to the Active Directory, and the other in the other direction. She maps the attributes in the Identity Management server to the attributes in the Active Directory. e.g. userName maps to sAMAccountName, sn maps to sn etc.

Since the VPN Server delegates access control to the Active Directory, the IAM administrator decides to make sure of the Active Directory attribute memberOf to distinguish between VPN User and VPN Administrator.

../_images/configuration-pv-7.png

2 Access Rights are created - VPN USER and VPN ADMIN.

../_images/configuration-pv-8.png ../_images/configuration-pv-9.png

Finally 2 Roles are created for users to request for access via the portal - VPN USER and VPN ADMIN.

../_images/configuration-pv-10.png

For VPN USER role, it is a direct mapping to VPN USER access right.

../_images/configuration-pv-11.png

For VPN ADMIN role, it is a composite of VPN USER and VPN ADMIN access rights. This will provide convenient for VPN administrators when they request for access. Once VPN ADMIN role is requested, a VPN administrator will be able to manage the VPN server and access VPN remotely.

Departments

Department refers to departments within an organization.

../_images/configuration-pv-a6.png

Applications

Applications allow access to external resources.

../_images/configuration-pv-a0.png

Mappings

Mappings link provisioning engine to applications and vice versa.

../_images/configuration-pv-a1.png

Access Rights

Access Rights define attributes that are mapped from provisioning engine to applications.

../_images/configuration-pv-a3.png

Roles

Roles refers to business roles that are a collection of access rights. Baseline Access is defined here.

Note

Baseline Access can be defined for all staff within a department to be granted the same roles from an application. Baseline Access will be provisioned automatically during user on-boarding.

../_images/configuration-pv-a4.png

Users

Users refers to identities of an organization.

../_images/configuration-pv-a5.png

Default Password Format

Default password format is applied to passwords for new users imported by Bulk Loading tool.

Note

Read more on Bulk Loading.

../_images/configuration-pv-a7.png

Password Policy

All passwords must conform to password policy.

../_images/configuration-pv-a8.png

Governance

The core component of Welle is Governance. It takes care of the seamless communication between the Welle portal and WrenIDM as the underlying provisioning engine. The Welle portal provides easy-to-use Access Request, Access Review and Admin Module modules to users, managers, application owners and IAM administrator.

Database

../_images/configuration-go-0.png

Welle connects to 3 databases - IDM Database, Attestation Database and Attestation Archive Database.

Hint

For better performance, it is recommended that each database be separated in different physical instances. It is especially important for the Attestation Archive Database to be segregated from the Attestation Database.

../_images/configuration-go-a0.png

Each database should be configured as follows:

Driver:JDBC Driver. Default: org.mariadb.jdbc.Driver.
URL:JDBC Connection URL in the format of jdbc:mariadb://<HOST>:<PORT>/<DATABASE_NAME>
Username:Database User Name
Password:Database User Password
Pool Size:Database Pool Size. Recommended: 5

IDM

../_images/configuration-go-1.png

Welle connects to WrenIDM mostly via REST API calls. For retrieving users and roles which are heavier in payloads, direct database connection is established.

Hint

For better performance, Welle caches users and roles retrieved from WrenIDM. Ad-hoc flushing of caches is supported.

../_images/configuration-go-a1.png
Service URL:URL to WrenIDM (provisioning engine)
Username:WrenIDM administrative user name
Password:WrenIDM administrative user password
Department Cache:
 Show the last time department cache was refreshed.
Role Cache:Show the last time role cache was refreshed.
User Cache Update Frequency:
 Frequency, in minutes, to refresh user cache
User Cache:Show the last time user cache was refreshed.
Roles:Custom user attributes used when input is required from user during Access Request.
Users:Custom user attributes used in custom data models.

Note

Read more on usage of Custom User Attributes and Custom Data Models.

Audit Logs:Purge audit logs in WrenIDM.

Attestation

Attestation is also known as Access Review.

../_images/configuration-go-a2.png
Service URL:URL to Welle. Used in Request Approval via Email.
Max Reassignment Allowed:
 The maximum number of times a task can be reassigned. Recommended: 1.
Max Campaign Duration (In weeks):
 The maximum number of weeks for campaign due date. This is a global variable applied to all campaigns. During campaign creation, IAM administrator can further reduce this value. Recommended: 4.
Archive Older Campaigns:
 Archive campaigns from Attestation Database to Attestation Archive Database. Applicable to campaign(s) in Closed state.

Hint

For better performance, campaigns older than 6 months should be archived.

Mail Server

Welle sends email notifications on a regular basis to managers, application owners and IAM administrators.

../_images/configuration-go-a3.png

The mail server should be configured as follows:

From Address:The from address is what recipients will see when they receive email notifications
Email Prefix:This will be prefix on the email subject
Secured SMTP:Default SMTP Port will be 25. If Secured SMTP is selected, SMTP Port will be changed to 465. However, manual change is still allowed.
Host Name:Mail server host name or IP address
SMTP Port:Mail server port number
Authentication Required:
 If authenticated is required, it means Username and Password are required to send out emails

Email Templates

Email templates can be customized here.

../_images/configuration-go-a4.png

Action List

Welle notifies log-in user of any task that the user needs to action on.

../_images/configuration-go-3.png

An email notification can be triggered with the following configuration.

Task Notification via Email:
 To enable/disable task notification via email.
Frequency:Frequency, in days, to trigger the email notification.
Task Notification Email Template:
 Email template for Task Notification.
User Without Manager Notification Email Template:
 Email template for notifying administrators of users found with no manager.

Access Request

Note

Read Request Approval for more information.

Request Approval via Email:
 Enable this to allow request approval via email. Default OFF.
Request Approval Email Template:
 Email template for Request Approval.
Request Completion Email Template:
 Email template for Request Completion.

Access Review

During a campaign, emails are sent to IAM administrators and managers in each stage. Reminder emails are also sent to managers who have not action on a campaign.

Campaign Creation Email Template:
 Email template for Campaign Creation.
Campaign Started Email Template:
 Email template for Campaign Started.
Campaign Ended Email Template:
 Email template for Campaign Ended.
Reassignment Email Template:
 Email template for Reassignment.
Reminder Email Template:
 Email template for Reminder.

Security

../_images/configuration-go-a5.png
Max Session Timeout (Seconds):
 Maximum session timeout for Welle portal.
Max Idle Timeout (Seconds):
 Maximum idle timeout for Welle portal.
Password Meter:Turning on this option will enforce stronger password when users change their passwords in My Profle.
Verbose Logging:
 Turning on this option specifically for troubleshooting purpose only. Recommended: OFF.

Note

Welle implements a data-driven password meter. Its effects on password security and usability were evaluated in the following publication: Ur et al. “Design and Evaluation of a Data-Driven Password Meter.” In the Proceedings of CHI, 2017.

To learn more, read Password Meter.

../_images/configuration-go-2.png

External Integrations

The External Integrations component in Welle takes care of integration with user self-service portal and social logins. Currently, only WeChat Login is supported.

User Self-Service

User Self-Service (USS) is a self-service portal for users who require forget password and password reset services.

../_images/configuration-ei-uss-0.png

User enters User ID and clicks on Continue button.

../_images/configuration-ei-uss-1.png

If the User ID is valid, user will receive OTP via SMS. User enters OTP and clicks on Submit button.

../_images/configuration-ei-uss-2.png

User enters new password and clicks on Reset Password button.

../_images/configuration-ei-uss-3.png

Password has been successfully reset by user.

../_images/configuration-ei-0.png

Important

At least one of the choices (Email or OTP) must be enabled.

Forget Password URL:
 URL to Forget Password page on USS server
API Key:Required for USS to make a REST call to Welle to retrieve the following information.
Enable Email:Enable email notification
Email Template:The email which will be sent to user who requests for forget password or password reset service
Enable OTP:Enable OTP notification via Email or SMS
OTP Length:Length of OTP string
OTP Validity:Time when OTP expires in seconds
OTP Delivery Method:
 Email or SMS via Twilio
OTP SMS Template:
 The SMS which will be sent to user who requests for OTP code

Note

For SMS via Twilio to be made available as one of the OTP delivery methods, Twilio external integration must be enabled.

Twilio

Twilio Programmable SMS sends and receives text messages globally with the API that over a million developers depend on.

Welle integrates with Twilio to send SMS notifications.

../_images/configuration-tw-1.png
Sender Phone Number:
 Sender phone number that will be appeared when user receives SMS
Account SID:Find Account SID at twilio.com/console
Auth Token:Find Auth Token at twilio.com/console

Proxy Server

A proxy server acts as a gateway between Welle and the Internet.

Welle, being an Identity Governance product, is usually deployed in Intranet (Secured) zone. In such scenario, for component like Twilio to work, a forward proxy server is required.

../_images/configuration-ps-0.png

Note

Currently, only HTTP Proxy is supported.

Protocol:Choose either HTTP or HTTPS
Host IP Address:
 IP address of the Proxy Server
Host Port:Port number of the Proxy Server

Tip

For deployment that integrates with WeChat Login (discussed in next section), Host IP Address and Host Port should point to Welle Proxy Server.

Note

This module has also been tested successfully with Tinyproxy.

WeChat Login

The WeChat Login extension allows users to log into Welle using their WeChat accounts.

Important

Before integrating WeChat Login, please register a developer account on the WeChat Open Platform, own an approved website application, and obtain the corresponding AppID and AppSecret. You can start the access process after your application for WeChat Login is approved.

To learn more, read Website App WeChat Login Development Guide.

../_images/configuration-ei-2.png

After a user clicks on Log In with WeChat button, a WeChat Login box will display a QR code.

../_images/configuration-ei-3.png

By scanning it using the WeChat app installed on the user’s smartphone, the user will auto log into Welle.

../_images/configuration-ei-1.png

The following is basic information required to connect to WeChat Login server:

App ID:The unique identifier of the application, which is obtained after the application submitted for review on WeChat Open Platform is approved
App Secret:The application secret, which is obtained after the application submitted for review on WeChat Open Platform is approved
Grant Type:Only authorization_code is supported now
Access Token URL:
 Gets access_token,refresh_token, and authorized scope via code
User Info URL:Gets the user’s personal information
QR Connect URL:Link to display WeChat QR code

Redirect URLs

After successful authentication via WeChat Login, WeChat Login server uses the redirect URLs to redirect user’s browser to designated pages in Welle. Currently, WeChat QR code is displayed in Welle Login Page and User Profile Page via an iFrame rendered from Welle Proxy Server.

Note

A typical link to display WeChat QR code looks like https://open.weixin.qq.com/connect/qrconnect? appid=[App ID] &response_type=code &scope=snsapi_login &redirect_uri=[REDIRECT_URL]

Important

Redirect URL must be encoded

The following redirect URLs are currently in use:

Login Page:Private URL for WeChat Login server to redirect back to Welle Login page via Welle Proxy Server
User Profile Page:
 Private URL for WeChat Login server to redirect back to User Profile Page via Welle Proxy Server

Welle Proxy Server

A proxy server acts as a gateway between Welle and the Internet.

Welle, being an Identity Governance product, is usually deployed in Intranet (Secured) zone. Welle Proxy Server bridges Welle, which resides in Intranet, and WeChat Login Server, which resides in Internet.

Important

Welle Proxy Server is a custom-built component to integrate Welle with WeChat Login Server. It is required for Welle to work with WeChat Login Server.

../_images/configuration-ei-4.png

Welle Proxy Server helps to render WeChat QR code so that it can be displayed on Welle Login Page via an iFrame (Inline Frame).

During Out-Of-Band Authentication process, WeChat Login Server is only able to redirect to Welle Proxy Server as it is the only Internet-facing component. Welle Proxy Server will extract the WeChat ID and make a callback to Welle to perform login activity for the user.

Note

Currently, only HTTP Proxy is supported.

Public FQDN:Publicly accessible domain name of the Proxy Server. WeChat Login Server will redirect to this URL in the Internet zone.
Private FQDN:Private domain name of the Proxy Server. Welle connects to this URL, which will proxy any outgoing traffic to WeChat Login Server.

Mobile Login

The Mobile Login extension allows users to log into IC Governor using IC Governor Mobile Application.

Important

Before integrating Mobile Login, please download IC Governor Mobile Application. Both iOS and Android versions are available.

../_images/configuration-ml-0.png

Before a user can Log In with Mobile with mobile phone, the user has to first register the device.

../_images/configuration-ml-1.png

After a user clicks on Log In with Mobile button, a IC Governor Moblie login box will display a QR code.

../_images/configuration-ml-2.png

By scanning it using the IC Governor Mobile app installed on the user’s smartphone, the user will auto log into Welle.

../_images/configuration-ml-3.png
Encryption Key:Used to encrypt and decrypt user information that are communicated between Mobile Application and Welle
Timeout:The maximum time to wait for user to scan QR code during Authentication. Default: 60 seconds.
Theme:Theme to be used by Mobile Application. This will be pushed during Device Registration phase. No change of theme allowed after registration.

Welle Proxy Server

A proxy server acts as a gateway between IC Governor and the Internet.

IC Governor, being an Identity Governance product, is usually deployed in Intranet (Secured) zone. Welle Proxy Server bridges Welle, which resides in Intranet, and IC Governor Mobile Application, which resides in Internet, over mobile network.

Important

Welle Proxy Server is a custom-built component to integrate IC Governor with IC Governor Mobile Application. It is only required if IC Governor is not accessible from the Internet.

Important

Welle Proxy Server is required if WeChat Login is enabled.

Device Registration

../_images/configuration-ei-5.png

Welle renders Mobile QR code during Device Registration. The IC Governor Mobile Application will send Device ID (with other information) through the Welle Proxy Server. A callback to Welle will be made so that the Device ID can be linked with the user.

Authentication

../_images/configuration-ei-6.png

During Out-Of-Band Authentication process, IC Governor Mobile Application is only able to connect to Welle Proxy Server as it is the only Internet-facing component. Welle Proxy Server will make a callback, with Device ID, to Welle to perform login activity for the user.

Note

Currently, only HTTP Proxy is supported.

Public FQDN:Publicly accessible domain name of the Proxy Server. Mobile Application will redirect to this URL in the Internet zone.
API Key:Required for Welle Proxy to communicate with Welle via REST calls.