Configure Users

unresolvable-reference.html#GUID-F8FE0E6F-0824-40B2-BF6E-B1D56B594CB1

Managing Users

After you install GoldenGate Stream Analytics, it is important to authenticate and manage users who use the application.

User details are stored in a database. When you create a GGSA schema at the time of installation, the following database tables are populated with one record in each table:

osa_users — table containing the users
osa_user_roles — table containing the user names and their associated roles

When you execute a query to pull in all the data from the osa_users table, you can see the following:

select * from osa_users;

+----+----------+--------------------------------------+ 
| id | username | pwd                                  | 
+----+----------+--------------------------------------+ 
|  1 | osaadmin | MD5:201f00b5ca5d65a1c118e5e32431514c | 
+----+----------+--------------------------------------+

where osaadmin is the pre-configured user along with the encrypted password.

When you execute a query to pull in all the data from the osa_user_roles table, you can see the following:

select * from osa_user_roles;

+---------+---------+
| user_id | role_id |
+---------+---------+
|       1 |       1 |
+---------+---------+

where role_id of value 1 indicates that the user is an administrator.

Adding Users

Though you can continue using Oracle GoldenGate Stream Analytics through the pre-configured user, it is a best practice to create your own users and delete the default pre-configured user.

When you add a user, it is highly recommended, though not mandatory, to obfuscate or encrypt the password. You can use the utility provided with the application server (Jetty) to encrypt the password.

Add Users Through User Interface

You can add/create users through the Oracle GoldenGate Stream Analytics application user interface.

To add a new user:

Go to System Settings.
Under the User Management tab, click Add user.
Enter details in the Username, Password, and Confirm Password fields.
click Create.
You can see the new user along with the predefined user in the list of available users.

Repeat these steps for as many users as you need, based on your requirement. If you try a user with the same name as that of an existing user, an error A user profile with the user name <username> already exists. Please specify another user name. pops up.

Add Users Through Code

To add a new user:

Open a terminal and navigate to OSA-19.1.0.0.*.*.
This is top-level folder in the folder where you have extracted your zip installer.

Note:
Replace *.* with the current version of GGSA.

Execute the following command:

java -cp ./lib/jetty-util-9.4.17.v20190418.jar org.eclipse.jetty.util.security.Password NewUser <password>

where NewUser is the name of the user and <password> is the password that you want to obfuscate or encrypt.

You will see a similar screen on your terminal:

2018-02-22 17:26:31.259:INFO::main: Logging initialized @100ms to org.eclipse.jetty.util.log.StdErrLog <password> 
OBF:1pbi1vn61unn1z7e1vu91ytc1o4u1o5s1yta1vv11z7o1uob1vnw1pcg 
MD5:58d613129c5e71de57ee3f44c5ce16bc 
CRYPT:NegJERR2H/a1M

For more information about running the password utility, see Configuring Secure Password.

Connect to the database using the database user credentials that you have configured in /osa-base/etc/jetty-osa-datasource.xml.

Insert a record into the osa_users table using any one of the following commands:

insert into osa_users (id,username,pwd) values (2,'NewUser','OBF:1pbi1vn61unn1z7e1vu91ytc1o4u1o5s1yta1vv11z7o1uob1vnw1pcg');

insert into osa_users (id,username,pwd) values (2,'NewUser','MD5:58d613129c5e71de57ee3f44c5ce16bc');

insert into osa_users (id,username,pwd) values (2,'NewUser','CRYPT:NegJERR2H/a1M');

Insert a record into the osa_user_roles table using the following command:
```
insert into osa_user_roles (user_id, role_id) values (2,1);
```
Important:
Currently, Oracle GoldenGate Stream Analytics supports only one user role, i.e, the administrator role. So the role_id value must always be 1.

You can now login to Oracle GoldenGate Stream Analytics as NewUser using <password>. Repeat these steps to create as many users as you require.

Changing Password

Change Password Through User Interface

To change a user password:

Go to System Settings.
Click the User Management tab.
Click Change Password next to the required user within the list of available users and then provide a value for the new password and click Save.

Passwords are stored in MD5 hash form.

Change Password Using Code

To change a user password:

Obfuscate or encrypt the new password for the user using the utility provided with the application server (Jetty).
Update the relevant record in the osa_users table. For example:
```
update osa_users set pwd='CRYPT:NesIZC3VkNGN2' where username='NewUser';
```
This command updates the password for the NewUser.

Remember to use your updated password the next time you login with NewUser.

Removing Users

You may want to remove users when you no longer need them.

Before you proceed to delete any user, make a note of the following:

If a user who owns draft pipelines is deleted, then the pipelines are either migrated to the current user or deleted, based on the selection you make at the time of deletion.
If you attempt to delete yourself, all your draft pipelines are deleted after you confirm. The current user session is invalidated and you will be signed out of the application immediately.

Delete Users Through User Interface

To delete a user:

Go to System Settings.
Click the User Management tab.
Click Delete next to the required user within the list of available users and then click OK within the confirmation dialog.

Delete Users Through Code

To delete a user:

Execute the following command from SQLPLUS or SQLDeveloper tools to remove a user:
```
delete from osa_users where id=2;
```
This command deletes the user with the id value as 2, i.e, the second user in the database.
Execute the following command to delete the user role corresponding to the user in the above step:
```
delete from osa_user_roles where user_id=2;
```

Configuring LDAP for User Authentication and Management

Oracle GoldenGate Stream Analytics makes use of the LDAP support for Jetty. The Lightweight Directory Access Protocol (LDAP) is an open source application accepted across various industries. This application protocol is used for obtaining and maintaining distributed directory information services over a network using an Internet Protocol (IP). With this feature, you can use the directory information services for user authentication and management. To use Microsoft directory services, set up a Microsoft Active Directory.

The user authentication and management can be through either internal LDAP or external LDAP.

For internal LDAP use the following command to create an LDAP service with default administrative access:

docker run --name LDAP-service --hostname LDAP-service -p 389:389 --detach osixia/openLDAP:1.2.1

Setting Up LDAP

To use LDAP for user authentication:

Update etc/override-web.xml to specify ldap role (EMPLOYEE for oracle ldap) and realm as osa-realm-ldap.
In case you need to switch back to data source from LDAP, you can update etc/override-web.xml to specify role (admin) and realm as osa-realm-ds. By changing realm in etc/override-web.xml, you switch between LDAP and data source. You can keep ldap-login.conf configured to retain LDAP configuration and can toggle between LDAP and data source by just changing override-web.xml file.

Update /osa-base/etc/LDAP-login.conf as per LDAP user/group settings. For example:

For User role:

osa-demo-LDAP {
		org.eclipse.jetty.jaas.spi.LDAPLoginModule required
			debug="true"
			contextFactory="com.sun.jndi.LDAP.LDAPCtxFactory"
			hostname=<hostname> <!-- hostname of LDAP -->
			port="389"
			authenticationMethod="simple"
			forceBindingLogin="true"
			userBaseDn="l=emea,dc=oracle,dc=com"
			userRdnAttribute="uid"
			userIdAttribute="mail"
			userPasswordAttribute="userPassword"
			userObjectClass="person"
			roleBaseDn="l=emea,dc=oracle,dc=com"
			roleNameAttribute="opn_access_level"
			roleMemberAttribute="targetdn"
			roleObjectClass="person";
		};

For Employee role:

osa-demo-LDAP {
		org.eclipse.jetty.jaas.spi.LDAPLoginModule required
			debug="true"
			contextFactory="com.sun.jndi.LDAP.LDAPCtxFactory"
			hostname=<hostname> <!-- hostname of LDAP -->
			port="389"
			authenticationMethod="simple"
			forceBindingLogin="true"
			userBaseDn="l=amer,dc=oracle,dc=com"
			userRdnAttribute="uid"
			userIdAttribute="mail"
			userPasswordAttribute="userPassword"
			userObjectClass="person"
			roleBaseDn="l=amer,dc=oracle,dc=com"
			roleNameAttribute="employeetype"
			roleMemberAttribute="targetdn"
			roleObjectClass="organizationalPerson";
		};

Remember to change userBaseDn and RoleBaseDn as per your locality name.

If in America:

userBaseDn="l=amer,dc=oracle,dc=com"
	roleBaseDn="l=amer,dc=oracle,dc=com"

If in Asia Pacific:

userBaseDn="l=apac,dc=oracle,dc=com"
	roleBaseDn="l=apac,dc=oracle,dc=com"

If in Europe:

userBaseDn="l=emea,dc=oracle,dc=com"
	roleBaseDn="l=emea,dc=oracle,dc=com"

(Re) start the application.

Setting Up Microsoft Active Directory

To setup Microsoft Active Directory 2016:

Ensure that role name is updated in the web.xml file located at /osa-base/etc/override-web.xml:
```
<auth-constraint>
		<role-name>developer</role-name>
	</auth-constraint>
```

Update /osa-base/etc/ldap-login.conf as per LDAP user/group settings. For example:

osa_demo_ldap {
		org.eclipse.jetty.jaas.spi.LdapLoginModule required
			debug="true"
			contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
			hostname=<hostname> <!-- this is the active directory server hostname -->
			port="389" <!-- this is the active directory server port -->
			bindDn="CN=Administrator,CN=Users,DC=corp,DC=oradev,DC=com"
			bindPassword=<password> <!-- If the active directory server allows anonymous login, no need to provide bindDn and bindPassword. Else, set the active directory server admin DN and password -->
			authenticationMethod="simple" <!-- if the active directory server allows anonymous login then set to 'none' otherwise set it to 'simple'-->
			forceBindingLogin="true"
			userBaseDn="l=amer,dc=oracle,dc=com" <!-- user attributes as per user setup in active directory server -->
			userRdnAttribute="uid" <!-- user attributes as per user setup in active directory server -->
			userIdAttribute="mail" <!-- user attributes as per user setup in active directory server -->
			userPasswordAttribute="userPassword" <!-- user attributes as per user setup in active directory server -->
			userObjectClass="person" <!-- user attributes as per user setup in active directory server -->
			roleBaseDn="l=amer,dc=oracle,dc=com" <!-- role (group) attributes as per user setup in active directory server -->
			roleNameAttribute="opn_access_level" <!-- role (group) attributes as per user setup in active directory server -->
			roleMemberAttribute="targetdn" <!-- role (group) attributes as per user setup in active directory server -->
			roleObjectClass="person"; <!-- role (group) attributes as per user setup in active directory server -->
		};

Configuring User Preferences

To set or update user preferences:

Click the user name at the top right corner of the screen.
Select Preferences from the drop-down list.
Click General, to set the following general preferences:
- Start Page: Select a start page from the drop-down list.
Click Notifications, to set the following notification preferences:
- Show Information Notifications: Select this option if you want the information notifications to appear in the pipeline. This option is selected by default.
- Information Notification duration (in seconds): Set the number of seconds for which the notifications appear. The default value is 5.
Click Catalog, to set the following Catalog page settings:
- Default Sorting Column: Select the column by which you want the columns to be sorted. This value will be used as the default for all columns until you change the value again.
- Default Page Size: Select the value to be used as the default page size. Based on the value selected, the number of records that appear on a page vary. This value will be used as the default for all pages until you change the value again.
Click Pipeline, to set the following pipeline preferences:
- Select Yes, to display the User Assistance text for the pipelines in the Pipeline Editor.
- Click Live Output Stream, to set the default table size, for the data in the Live Output Stream table, of a pipeline.
- Click Timestamp, to set the following timestamp function and format preferences:
  - Timestamp Function: Select a value from the drop-down list.
  - Timestamp Format: Select a format to display the timestamp type fields.
Click Map, to select a tile layer from the drop-down list.
Click Save.