Active directory

 

Petra can use the Active Directory (AD) directory service to establish and maintain database server users and roles.   When using AD, the database server automatically creates Petra users from AD usernames and assigns roles from AD groups.  This method can use  Kerberos authentication (a network authentication protocol that provides mutual authentication between the a computer and server to verify each other's identity) for additional security.  From a user’s perspective, Petra automatically logs in with the user’s AD credentials, which translates to one fewer username/password to manage.  Petra installations with AD enabled in the Petra.ini file can ONLY connect to Petra Database Servers with AD enabled.

Active Directory requires Petra v4.0.6 or higher, PetraEDBServer v1.03 or higher, and a domain using Active Directory.

Configuring the Petra database server with edbsrvr.INI

Enabling AD on the database server requires a few modifications to the server’s edbsrvr.INI file. With a default installation, this file is in the “C:\ProgramData\Elevate Software\...” folder, and can be edited with any basic text editor.  Alternatively, use the Petra Server Admin Tool’s EDB Server Maintenance tool and select “open .INI file.”  

The following entries should be in the [Server] section of the edbsrvr.INI file.

Parameter

Flag

Definition

Active Directory Enabled =

1

Enable (1) or disable (0) Active Directory

Active Directory SPN =

host/computer_name

See, Working with SPN

Active Directory Override Users =

Administrator, Proc_Username

Creates a list of users that can access the Petra Database Server without using AD authentication. At a minimum, this line should include the “Admin User” mentioned below and the “Proc_Username” user (see, Petra.INI )

Admin User =

Administrator

The database server needs administrative rights in order to copy and modify users from the AD groups.  This line  lists a user in the “Administrators” role.  This user must be listed in the “Active Directory Override Users” list mentioned above

Admin Password =

Password

This entry sets the password for the administrator user

IHS recommends creating another administrative account for this edbsrvr.INI file, or at least changing the default password.  The edbsrvr.INI file stores an administrator username and password in plain text, so consider taking extra precautions when assigning read/write permissions to this file.

Mapping AD groups to Petra database server roles

A mapping file connects user AD groups to database server roles.  The database server uses this mapping file to slot AD users into different roles, which can change as their group changes.  This mapping is stored in AD_EDB_GroupMappings.XML in the same location as the edbsrvr.INI file, and can be setup and modified through the Petra Server Admin Tool.  If AD is enabled on the Petra Database, the Server Admin Tool will have a new button on the User Management tab.

The Active directory to EDB Mappings button

Selecting that button opens the Active Directory to EDB Mappings tool.  To add a line, select the green “+” button.  To drop a line select the red “-” button.  To establish a relationship, type in the Petra Database Server roles (EDB Roles) and the associated AD group.  Note that this can be a one-to-many mapping – a role can be fed from multiple groups.

Mapping database server roles to Active Directory groups

When done, click “Save” and you will get a notification explaining which roles will be added or dropped to complete the mappings. Select “Yes” to complete the changes. Once this is done, any user from one of these AD Groups will be able to login to Petra and be automatically created (if doesn’t already exist) and assigned to the mapped Petra Database Server Roles.

Configuring the Petra Installation with Petra.INI

In addition to configuring the Petra Database Server, enabling AD requires a few modifications to the Petra’s configuration file, Petra.INI.  This file isn’t created automatically, so it’s necessary to either create it from scratch or copy the sample Petra.INI located in the PetraSRV\PARMS folder to the Petra installation directory.

Section / Parameter

Flag

Definition

 

[ActiveDirectory]

 

 

Enabled =

1/0

Enable (1) or disable (0) Active Directory

SecurityPackage =

Kerberos

Network authentication protocol that provides mutual authentication between the a computer and server to verify each other's identity. other security packages (NTLM & Negotiate) are available, IHS recommends Kerberos.

Delegate =

YES/NO 

Default = NO. Refer to Microsoft SSPI documentation for an explanation of this option.

MutualAuth =

YES/NO

Default = NO. Refer to Microsoft SSPI documentation for an explanation of this option.

[EDB]

Proc_Username =

EDBProc

This line sets a username that is ONLY used to make initial contact with the Petra Database Server before AD Authentication. This user should NOT be added to any roles which have access to your Petra Project Databases. This user must exist in the “Active Directory Override Users” list mentioned above.

Proc_Password =

EDBProc

This line sets password for the “Proc_user” mentioned above.