Welle Documentation

Configuration

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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.

Applications

Applications allow access to external resources.

Mappings

Mappings link provisioning engine to applications and vice versa.

Access Rights

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

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.

Users

Users refers to identities of an organization.

Default Password Format

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

Note

Read more on Bulk Loading.

Password Policy

All passwords must conform to password policy.

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

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.

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

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.

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.

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.

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.

Action List

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

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

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.

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.

User enters User ID and clicks on Continue button.

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

User enters new password and clicks on Reset Password button.

Password has been successfully reset by user.

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.

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.

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.

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

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

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.

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.

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

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

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

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

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

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.

Reports Customization