Configuration Application Tool - version 3.7
- Stine Granviken
This document is written in English only
Configuration Application is a standalone application to provide GUI for configuration XML file. Configuration Application located in the same directory with installed LRA Client. Name of executable is ConfigurationApplication.exe.
Default setup folder has from v3.4 changed to Buypass Access Manager, so it has changed from:
Windows x32 – Program Files\Buypass\Lra Client
Windows x64 – Program Files (x86)\Buypass\Lra Client
To:
Windows x32 – Program Files\Buypass\Buypass Access Manager
Windows x64 – Program Files (x86)\Buypass\ Buypass Access Manager
Also link to ConfigurationApplication.exe is placed in Start menu (Windows 7).
Start page
Either you Open existing configuration files - LOCAL and MASTER, or you want to create a new configuration using New.
- LOCAL file must always be available on the BAM client PC. The LOCAL configuration includes mappings and connections to drivers for readers, scanners, signpads, pinpads and local values connected to this and this BAM client only.
- MASTER file can be available on the BAM client PC, but can also be common for all or more clients and therefore localized on a common file server. The MASTER configuration includes mappings and connections to CA, AD, Buypass, Issuing process and values connected to the organization independent on number of BAM clients.
Look of start page BAM Configuration Application Tool v3.7
Navigation
You can use TAB key to navigate between tabs, fields and buttons. To get to the menu use ALT key. Use arrow keys to navigate between options in menus and tabs. Most of controls have tooltips with additional description. Move mouse pointer over the needed parameter to read field description.
Id | Description | Comments |
|---|---|---|
#1 | Application menu | Available functions:
|
#2 | Configuration tabs | Show the Start page tab and a tab for each open configuration file |
#3 | Configuration file path | Absolute URI of configuration file in actual tab, that is the tab you now are working with |
#4 | Tab control | Tab list of device and parameter subgroups |
#5 | Paremeters | Show all parameters connected to actual tab control, that is the subtab you now are working in |
#6 | Tool tip | Mouseover in parameter input field shows a help tooltip with additional info connected to actual parameter |
#7 | REVERT-button | Reverts all changes on all tabs with last saved parameters from present file |
#8 | SAVE-button | Save all changes in present file |
#9 | SAVE AS-button | Save file with last changes in new file |
TEST-button
The TEST-button in the different TABs of the LOCAL and MASTER configuration will test actual devices and backend interfaces with parameters and values registered in each TAB.
It does not matter if the values are saved or not when testing, but you need to remember to save before exiting the application if you want to keep the new values given. New values are shown in red.
Details of what actually are tested are described specially for each tab or function - see describtion for each tab further down on this page.
In version 3.7 we have added a "test-section"on each TAB showing the actual parameters or objects tested with labels and results. We have used the same principle as the startup of the BAM client.
See below connected to header Local_Test All tab or Master_Test All tab.
Trace- and log files
All moves and functions run in BAM client will be stored in a separate log file which is stored at {ApplicationFolder}\Logs\trace.<date hour>.txt
All changes done in the Configuration Application Tool client will be stored in a separate log file which is stored at {ApplicationFolder}\Logs\configuration.trace.<date hour>.txt
A new file is greated every time the BAM client or Configuration client is started - date and timestamp is part of filename to differ the files.
From BAM v3.7 it is possible to send trace files directly to Buypass Customer Service from the Start page TAB in the Configuration Application Tool client.
Using the SEND-button you will send the last 5 trace files for the BAM or Configuration client as attachments to emails.
From BAM v3.7.6_7875 these 5 trace-files will be packed in a ZIP-file and the ZIP-file protected with a password.
The password is automatically and randomly set and shown to the Administrator in the screen as shown below.
The password must be sent to the receiver of the mail, but remember to send in separate channel - for instance on sms.
BAM client trace files
Configuration Application Tool client trace files
Local Configuration
Local configuration file contains parameters that may be specific to each LRA client station. This file is stored locally.
Local_Common
Id | Description | Comments |
|---|---|---|
#1 | Master configuration | Path to master configuration file. Contains two functions:
|
#2 | Language | Language used in GUI for labels and guidelines. |
#3 | Location | Place or address of organization will be written in all PDF documents generated. |
| #4 | TEST-button | Testing if path and MASTER file is found. |
Local_Smartcard
Id | Description | Comments |
|---|---|---|
#1 | FETCH-button | Refreshes list of available readers which can be chosen for Operator- and user card readers |
#2 | Operator card reader | Map one of the card readers from list to be the Operator card reader - that is where Operator must insert his/her smartcard when operating the BAM client |
| #3 | User card reader | Map one of the card readers from list to be the User card reader - that is where User/Employee must insert his/her smartcard. |
#4 | TEST-button | Checks names and access to readers. In addition to Operator- and User cardreader the connection to the PinPad set up in installation will be tested - either the ACR88/89 or the Secure PinPad. |
Choosing ACR88/89 a Service will be installed in order to support smartcard communication. This is not needed for Secure PinPad.
Local_Scanner
Id | Description | Comments |
|---|---|---|
#1 | SELECT-button | Shows dialog to select scanner which is available on this machine |
#2 | Scanner name | Shows name of scanner when chosen |
#3 | TEST-button | Checks name and access to scanner and gets an image |
* Windows Image Acquisition (WIA) service must be started on client PC.
Local_SignPad
Id | Description | Comments |
|---|---|---|
#1 | TEST-button | Ensures SignPad is accessible. Driver for SignPad must be loaded separately as part of the BAM installation. No configuration needed. |
Local_Logs
Changes from BAM v3.7.6.7875 - see details in releasenote section 3 and 4 - written in both Norwegian (on top of page) and English (bottom of page).
Id | Description | Comments |
|---|---|---|
#1 | Severity | Desired severity for default log (trace.log file in the app directory)
|
| #2 | Reset severity level | Default value = 2 On startup of BAM client the severity level is checked. ERROR is default. If a higher log level (read: Verbose) then the log level will be reset to Error if more than number of days registered since last change. The log level is not change automatically to Error. The message will come until the Administrator have change level and saved the file here in Configuration Application Tool.
|
| #3 | Delete trace files | Default value = 2 On startup of BAM client all log files older than number of days registered will be deleted.
Vi har fått tilbakemelding om at noen brukersteder har fått feilmelding ved oppstart etter installsjon. Om så skjer så kan årsaken være at konfigurasjonen ikke har får satt dato og at det er datosjekken som feiler i oppstarten.
|
Local_Test All
In version 3.7 we have added a "test-section"on each TAB showing the actual parameters or objects tested with labels and results. We have used the same principle as the startup of the BAM client.
Id | Description | Comments |
|---|---|---|
#1 | TEST-button | Tests all local devices and parameters defined in the different LOCAL-tabs with current settings and shows aggregated results. |
Master Configuration
Master configuration file contains parameters that are common to all LRA stations within one organization. This file is usually stored in a shared area.
Master_Common
Id | Description | Comments |
|---|---|---|
#1 | BAM mode | Different configurations of BAM-client:
Mixed mode is default value. Unnecessary tabs or fields within tabs will be disabled based on which mode is set. |
#2 | Company name | Name of organization. Will be written in all PDF documents generated. If organization has more LRA-clients situated in different locations - name can show department. |
Master_Key length
Id | Description | Comments |
|---|---|---|
#1 | Local certificates key length | Defines the certificate size generated on the smartcard. Valid values:
Value chosen must be in compliance with key length in template. |
Master_Active directory - Common
Id | Description | Comments |
|---|---|---|
#1 | Domain | Defines the name of the domain controller. Example: testdc:389. FETCH-button gets available ADs and you will be able to choose the correct one. |
#2 | SearchBase | Defines the search path for searching for Users in selected AD. Different OU's (directories) in AD can be defined and included. See more details below under the heading Search Base. |
#3 | Use nested groups | If Users are connected to usergroups in AD, which in turn are linked to the certification groups rather than linking one and User to one or more certificate groups this check box must be ticked off. |
| #4 | User search mapping | Options - see more details below under User search mapping.
|
| #5 | ADD AD-button | Create new AD configuration. Will be created and available on the left tabs list. |
| #6 | COPY AD-button | Copy current AD configuration into new tab, which then can be modified. |
| #7 | DELETE AD-button | Delete currently selected AD configuration. |
#8 | TEST-button | Ensures AD is accessible. Checks configured domain name, searchbases, employee mappings and groups. |
Search Base
Active Directory allows administrators to create a hierarchy within a domain that meets the needs of their organization. The object class of choice for building these hierarchies is the class organizationalUnit, a general-purpose container that can be used to group most other object classes together for administrative purposes. An organizational unit in Active Directory is analogous to a directory in the file system; it is a container that can hold other objects.
To define path to SearchBase OU-s you need to construct the entire distinguished name by following references to the root. You can use (*) in case of recursive search needed. Several SearchBases supported separated by semicolon.
For example: we have this Active Directory structure:
- If you need to search only in testOU_1 and not include subunits: SearchBase: ou=testOU_1, ou=TestUsers, ou=Infopulse;
- If you need to search in TestUsers and all subunits, you need to use sign of recursive search – “(*)”. SearchBase: ou=TestUsers, ou=Infopulse(*);
- If you need to search in OU-s testOU_1_1 and all subunits, and also search in testOU_2 without subunits: SearchBase: ou=testOU_1_1, ou=testOU_1, ou=TestUsers, ou=Infopulse(*); ou=testOU_2, ou=TestUsers, ou=Infopulse;
Note: Order of organization units must be specified from bottom to top.
User Search mapping with lookup in AD when Usercard present
- UpnPrefix - maps prefix UPN from Subject Alternative Name in certificate to samAccountName field in AD (samAccountName =value). This has been the only possible implementation until v3.4 and is default value
- UpnFull - maps full UPN from Subject Alternative Name in certificate to UPN field in AD (userPrincipalName =value)
- SubjectCN - maps value from Subject.CN field from certificate to samAccountName field in AD (samAccountName =value) Requires that value in Subject.CN = samAccountName
- DistinguishedName - maps value from Subject field from certificate to DistinguishedName field in AD (distinguishedName =value) DistinguishedName from certificate is used as user’s “absolute path” in AD at the time of certificate issuance
- Certificate - If chosen search (one of the above) does not return User the LRA will automatically do another search mapping whole certificate itself to userCertificate field in AD (userCertificate=\30\82\...)
Search connected to remote functions is not changed. Buypass Access uses UserName stored in the card as part of remote filename and this will be used as search criteria and mapped to AD as samAccountName.
Search connected to reports is also changed in v3.4. From this version and onward it is using the configuration in order to be consistent. Searches in reports can use one of the four first options (a-d). If option e) whole certificate, is set up in configuration the search will automatically switch to use option a) upn prefix = samAccountName, as in current implementation. CA report entry includes certificate metadata (SubjectName, NotBefore, NotAfter, UPN, DistinguishedName, etc.), but not certificate itself. It is possible to search with certificate in reports as well, but then the time of searching will significantly increase. LDAP filter for search using list of certificates will be huge and search in AD much slower even for moderate number of CA report entries.
Master_Active directory - Employee mappings
Id | Description | Comments |
|---|---|---|
#1 | FETCH DEF-button | Gets "smal" list of available mapping fields from AD. "Smal" list are the most used fields only:
|
| #2 | FETCH EXT-button | Gets "large" list of all available mapping fields from AD. "Large" list is an extended list with ALL fields defined in AD, and will take some time to fetch. |
#3 | First name | First name should consist of first and middle name |
#4 | Last name | Last name should consist of last name only |
#5 | Official email of User in the organization | |
| #6 | SSN mapping / SSN Mode | SSN is a 11 digits number which consist of date of birth (6 digits on format ddmmyy) and social security number (5 digits). Available SSN modes:
From v3.7 SSN-mapping is stored in the LraConfig.Master.XML file in a new way. The SSN-mode and the mapping, if required, will be remembered when updating the BAM-client,
If BAM client is configured to be in Buypass Mode (QC only) then IssuerKey is defined in the Master_Buypass tab - see description in this section below. |
#7 | Issuer Key mapping / IssuerKey ** | IssuerKey is referring to a key representing a User/employee. The issuerKey must be unique within an organization. IssuerKey will be registered at Buypass together with user information and will be used as lookup on search and mapping between organisations and Buypass. The value of an issuerKey-field must not be changed without notifying Buypass. |
| #8 | TEST-button | Ensures AD is accessible. Checks configured domain name, searchbases, employee mappings and groups. |
** For any AD mapping fields you can use any AD attribute listed in AD Attributes List. For selected AD attribute «LDAP-Display-Name» should be used.
On search the client is reading the configuration and searches AD based on this. If the fields in AD does not correspond to configuration the Operator may have strange information in GUI OR User will perhapes not be found.
Excample: If AD has SSN registered in 1 field, but in the configuration this is mapped to 2 fields, then SSN will show the content from field 1 twice. 21036912345 in AD-field will be 2103691234521036912345 in GUI.
Master_Active directory - Group mappings
Id | Description | Comments |
|---|---|---|
#1 | FETCH-button | Gets list of available groups from AD. Due to the fact that some organizations have ADs which have very many groups it is from v3.7 possible to limited the search for fetching groups. |
#2 | Local certificate group | Users belonging to Local certificate group will have local certificate issued (LC). |
#3 | Operator group | Users belonging to Operator group will have enrollment agent certificate issued (EA). |
#4 | Administrator group | Users belonging to Administrator group will have enrollment agent certificate issued (EA). |
#5 | Qualified certificate group | Users belonging to Qualified certificate group will have a par of qualified certificates issued (QC). |
Master_Certificate Authority - CA
Id | Description | Comments |
|---|---|---|
#1 | Server name | Defines the common name of the CA configuration. SELECT-button allows to obtain CA name automatically. Example: ca.testlab.local\Testlab CA |
#2 | FETCH-button | Gets certificate templates from chosen CA |
#3 | Logon template | Name of template - if you get OID the template is unknown |
#4 | Temporary template | Name of template - if you get OID the template is unknown |
#5 | Enrollment agent template | Name of template - if you get OID the template is unknown |
#6 | TEST-button | Ensures CA is accessible and template fields are not empty |
In version 3.6.0 we implemented a new check so there are no longer possible to fetch CA templates without a corresponding OID.
Master_Reports
Id | Description | Comments |
|---|---|---|
| #1 | SELECT-button | Gives you the possibility to browse and set up a file area for the reports. You can also write path directly. |
#2 | Path | File area for storage of reports. |
#3 | TEST-button | When pushing the TEST-button we generate a file, store it on file area and delete it in order to check availability. |
From BAM v3.7.6_7875 the reports will open in the selected editor (eg Excel) with UTF8 encoding. Norwegian special characters æøå / ÆØÅ and other special characters will visualize correct.
Master_Document Registry
Id | Description | Comments |
|---|---|---|
| #1 | SELECT-button | Gives you the possibility to browse and set up a file area for the PDF-documents. You can also write path directly. |
#2 | Path | File area for storage of PDF-documents, which are generated for every function started in BAM client to have tracks on issuance and administration of smartcards in organization.. |
#3 | TEST-button | When pushing the TEST-button we generate a file, store it on file area and delete it in order to check availability. |
Master_Remote functions
Id | Description | Comments |
|---|---|---|
#1 | Remote functions enabling checkbox | If organization is using remote functions having Users at remote locations this checkbox must be ticked off. When box is ticked it will give access to more configurable parameters.
|
#2 | Auto check request count | If number of remote certificate request should be counted and shown in Main menu this checkbox must be ticked off. |
#3 | Path to requests | Filearea for storage of remote certificate requests. Possible to browse using the SELECT-button. |
#4 | Path to responses | Filearea for storage of certificates generated which act as responses of remote requests. Possible to browse using the SELECT-button. |
#5 | Pooling interval | Defines the polling interval for responses in milliseconds. Default value is 2000. |
#6 | Max number of attempts | Defines the maximum retry times the BAM client tries to acces the remote file area. Default value is 30. |
#7 | TEST-button | When pushing the TEST-button we generate a file, store it on file area and delete it in order to check availability. |
Buypass Access (NetID) must have corresponding path for request and responses for Temporary cards (Enroll) end Renewal of certificates (Renew).
- Request file names: {prefix}{userId}.{extension}
- Rnv_{userId}.req
- Tmp_{userId}.req
- Response files: {prefix}{userId}.{extension}
- Rnv_{userId}.crt
- Tmp_{userId}.crt
Master_Buypass
From BAM v3.7.6_7875 we have implemented a new interface between BAM client and Buypass backend. For versions before v3.7.6 we use WebLTS which is a SOAP-based interface. From v3.7.6 we use a new REST-based interface. This is a part of Buypass' development and deployment architecture, and the new interface is the basis for future issuance of Buypass ID@Work - central stored PKI for mobile devices to be available for BAS customers during the fall 2018 / spring 2019.
In Local and Mixed Mode
Endpoint address: https://api.buypass.no/access-manager-api
In Buypass Mode
Endpoint address: https://api.buypass.no/access-manager-api
Id | Description | Comments |
#1 | Merchant ID | Merchant ID connected to organization. Will be provided by Buypass |
#2 | Timeout | Max time of waiting response from Buypass - the WebLTS interface |
#3 | Endpoint address | Address for BAM versions from 3.8.2: https://api.buypass.no/access-manager-api |
#4 | Merchant certificate serial number | Serial number of merchant certificate installed in MicroSoft certificate store. By using button SELECT you can obtain certificate serial key automatically. Certificate should be installed as described in BAM Client readme |
#5 | Buypass Mode Preregistration Use SSN as IssuerKey | The Buypass Mode Preregistration parameter will show only when the parameter BAM Mode in MASTER_Common is set to value Buypass. The organization can choose which value should be the IssuersKey, that is the key used by Buypass to identify the employees uniquely. The IssuersKey is used for searching and is the link between the organisation and Buypass. In Buypass Mode the Issuerskey will only be searchable from Buypass systems, but in Mixed Mode the IssuersKey will be the link between local AD and Buypass.
In Mixed Mode, when the parameter BAM Mode in MASTER_Common is set to value Mixed, the issuersKey is configured in the Master_AD_Employee mapping tab. See description in this section above. |
#6 | TEST-button | Here a request is signed using the Merchant certificate, the request is sent to Buypass and Buypass will give a response telling if the signing was verified OK or give an error message. |
Master_Issue process
Id | Description | Comments |
|---|---|---|
#1 | Agreement sign required | If User should accept agreement on first time issuance of local certificates this ceckbox must be ticked off. NOTE: For first time issuance of qualified certificates the User must always accept the agreement. |
#2 | User scan and document scan required | If User should sign and get his ID document scanned on first time issuance of local certificates this ceckbox must be ticked off. NOTE: For first time issuance of qualified certificates the User must allways sign and get his ID document scanned. |
| #3 | Allow more Local certificates | Enables possibility to issue additional local certificates in ID card scenario. |
| #4 | Allow Operator identification | Enables possibility for the Operator to say that User is known and there are no need of extra identification. In smaller organizations where "everyone knows everyone" this will make the issuance process easier, .... but the Operator still have the responsibility to identify the user. |
#4 | Document scan required on replace | If User should get his ID document scanned on issuance of replacement of both local and qualified certificates this ceckbox must be ticked off. |
| #5 | QC: Renewal limit, weeks | Already issued qualified certificates (QC) in card will not be renewed if QCs are issued for less than 12 weeks ago (default) in cases where you are trying to issue new LC or renew existing LC in User card. This is mostly used when Allow More Local Certificate is enabled. |
#6 | Third party identification enabled | If organization allow 3.party identification in cases where User has forgotten his own ID document this checkbox must be ticked off. 3.party identification means another colleague in organization is using his smartcard to verify the Users identity. |
#7 | Timeout | Third party card waiting timeout. |
Master_Test All
Id | Description | Comments |
|---|---|---|
#1 | TEST-button | Tests all backends/devices and parameters defined in the different MASTER-tabs with current settings and shows aggregated results. |