...
...
Version#
...
Date
...
Modified By
...
Description of Modification
Version# | Date | Modified By | Description of Modification |
|---|---|---|---|
| 1.0 | 06/20/2017 | Sovann Huynh | Converted from a design document into a full user manual |
| 1.1 | 1/4/2018 | Tabassum Jafri | Added Exchange Manager GUI |
| 2.0 | 02/01/2018 | Sovann Huynh | Added Certificate Manager and Test Data Loader, deprecated Connection Manager |
| 2.1 | 10/22/2018 | Tabassum Jafri | Added Internal Endpoints properties section. |
| 2.2 | 11/02/2018 | Tabassum Jafri | Updated User Accounts and Cross-Gateway Query Client section. |
| 2.3 | 04/09/2019 | Eric McDonald | Text corrections on Import Wizard. |
...
Account Management - User Accounts
Certificate Management
Certificate Management interface is for to simplify the process of creating new certificate and managing self-signed certificates, CA-issued SSL certificates within KeyStore and TrustStore. It is divided into three tabs - Manage KeyStore, Manage TrustStore and Import Wizard
Manage KeyStore
Selecting the default Manage KeyStore tab under Certificate Management displays the Manage KeyStore page that shows list of available Keystores from CONNECT configuration. For security purposes, users can only view certificates from KeyStore list.
...
| Info | ||
|---|---|---|
| ||
While replacing the self-sign certificates with the CA certificates imported using Import Wizard, user must exercise caution and verify, before replacing, if they have imported the root, intermediate(s) and leaf certificates. |
Import Wizard interface partly automated the process of creating new certificate and importing CA certs into CONNECT configuration. It is divided into five tabs - Start, Create Certificate, Certificate Signing Request,CA Providers, Import SSL Certificate. Import Wizard functions as below:
- Allow user to create new certificate
- Allow user to create Certificate Signing Request (CSR/PKCS10)
- User must manually submit the CSR to their Certificate Authority (CA) to get a trusted certificate for their server
- Allow user to import server Certificate (CSR Reply) and CA certificates (chain of trust)
- Creates a backup of KeyStore and TrustStore under CONNECT configuration //importWizard/temp
- Creates a new KeyStore and TrustStore for replacement under CONNECT configuration //importWizard/new
- After successful Import Wizard process completion, the user must manually:
- Replace CONNECT server configuration KeyStore and TrustStore with the files under //importWizard/new
- Restart the Server
- Verify the AdminGUI functionality works and Manage KeyStore, Manage TrustStore list new certificate
...
| Info | ||
|---|---|---|
| ||
|
Direct Configuration
Several aspects of the Direct configuration from domains to certificate storage locations are defined in the Admin UI. Certificates, trust anchors, and trust bundles themselves can be stored using the Admin GUI tool in the configuration service and accessed through the web service interface. CONNECT has leveraged the Direct RI's config web service for these features.
Configuration is separated into five component:
- Domains - The list of domains managed by the STA agent.
- Certificates - Private and optionally public certificate storage.
- Trust Anchors - Trust anchor certificate storage for coarse grain anchor configuration.
- Trust Bundles - Collections of anchors published by trust communities.
- Settings - Configuration settings for numerous components of a HISP. These are generally higher level configuration settings.
NOTE - Domains, certificates, trust anchors, and trust bundles have specific configuration elements stored in the settings component.
| Info | ||
|---|---|---|
| ||
|
Domains
The Domains page under Direct Configuration menu on the left navigation pane describes the list of domains that will be managed by the HISP/STA and allows for managing and updating domain configurations.
Fig 6: Direct Configuration - Domains screen
The domains list displays all domains associated with the HISP.
Table 6 - Domain List screen display
...
COLUMN
...
DESCRIPTION
...
Name
...
Domain Name
...
Postmaster
...
Postmaster email address for the domain
...
Created
...
Creation date
...
Updated
...
Last updated date
...
OPTION
...
DESCRIPTION
...
Create New Domain
...
Selecting this option opens up Create New Domain page in a pop-up modal dialog window
...
Delete
...
Checking the select check box associated with the domain and selecting this option deletes the selected domain.
...
Create New Domain
Create new domains for the HISP that are managed by the STA
Direct Configuration - Create Domain screen
Edit Domain
View or edit the configurations for a selected domain.
Domain Name
Edit the domain name associated with the domain.
Direct Configuration - Edit Domain -> Domain Name screen
...
Edit the email addresses associated with the domain.
Direct Configuration - Edit Domain -> Addresses screen
...
Anchors stored in the configuration service are added and maintained in the Anchors tab of the configuration service Edit Domain page.
Direct Configuration - Edit Domain -> Anchor screen
| Info | ||
|---|---|---|
| ||
Be sure to click "Add Anchor" after it has finished uploading |
Edit Domain - Stored Anchors
...
COLUMN
...
DESCRIPTION
...
Name of anchor for trusted domain
...
OPTION
...
DESCRIPTION
...
Edit Domain - Add Another Anchor
...
FIELD
...
DESCRIPTION
...
Choose Anchor Certificate
...
Provides the ability to upload a new anchor to the configuration service. See Choose, Upload, Cancel, Add Anchor for detail
...
Incoming
...
Selecting the option allows the trust anchor to be utilized for incoming message processing
...
Outgoing
...
Selecting the option allows the trust anchor to be utilized for incoming message processing
...
Status
...
(Enabled/Disabled).
...
OPTION
...
DESCRIPTION
...
Add Anchor
...
Clicking Add Anchor will add the anchor to the domain and upload the anchor to the configuration service.
...
Trust Bundles
Configured trust bundles can be added to a domain from the Trust Bundles tab of the configuration service Manage Domains page. Each anchor in the bundle is used to create trust between the domain and the system represented by the anchor. Similar to configuring anchors, each bundle can be set to incoming or outgoing to control the direction of trust.
Direct Configuration - Edit Domain -> Trust Bundles screen
Assigned Trust Bundles panel lists the trust bundles that are associated with the selected domain
Edit Domain - Assigned Trust Bundles
...
COLUMN
...
DESCRIPTION
...
Name
...
Trust Bundle Name
...
The fully qualified URL where the trust bundle can be retrieved. For trust bundle URLs referencing HTTPS , the appropriate CA or public certs to access the URL have to be trusted by CONNECT application, i.e. imported to the CONNECT application Trust Store.
...
Incoming
...
(True/False) Indicates whether trust bundle should be utilized for incoming message processing
...
Outgoing
...
(True/False) Indicates whether trust bundle should be utilized for for outgoing message processing
...
OPTION
...
DESCRIPTION
...
FIELD
...
DESCRIPTION
...
Add Trust Bundles
...
Drop down list of available trust bundles that are already configured in the configuration service. Only displays the trust bundles (names) that have not been associated with the selected domain,
that are available to add
...
Incoming
...
If checked, the trust bundle will be utilized for incoming message processing
...
Outgoing
...
If checked, the trust bundle will be utilized for outgoing message processing
...
OPTION
...
DESCRIPTION
...
Add Trust Bundle
...
Clicking Add Trust Bundle will assign trust bundle to the domain .
Agent Settings
| Note |
|---|
CONNECT has leveraged the Direct RI version 3.0.1 for the Direct configuration. The CONNECT team has validated these settings using both WS and KEYSTORE configurations for Anchors, public and private certificates and DNS configurations. LDAP configurations were not tested and will be looked at in the future. |
Direct Configuration - Agent Settings Screen
Agent Settings
...
Anchor Store Agent Settings
Anchors define the certificates that create trust between domains. Each domain must have at least one outgoing or incoming trust anchors. Anchors can be retrieved from different source mediums including the configuration service.
The anchor storage medium is configured in the settings page of the configuration UI. All settings are configured as simple name/value pairs as defined below
Note – Trust bundles are defined using web services ONLY. Trust anchors can be configured using WS and LDAP, Keystore
Anchor Store Agent Settings parameters
...
SETTING NAME
...
VALUE/DESCRIPTION
...
AnchorStoreType
...
The storage type of the anchor store. Valid types:
WS (default): Anchors are stored in the configuration service.(see 6.2.1.1)
LDAP: Anchors are stored in an LDAP server.(see 6.2.1.2)
KEYSTORE: Anchors are stored in a local keystore file.(see 6.2.1.2)
...
AnchorResolverType
...
The type of the anchor resolver. Valid types:
Uniform: All domains use the same anchors for all addresses.
Multidomain: Each domain defines its own discrete set of trust anchors.
...
AnchorKeyStoreFile
...
For keystore store types, the name of the file that contains the certificates. This can be just a file name, a fully qualified path, or a relative path.
...
AnchorKeyStoreFilePass
...
For keystore store types, an optional password used to encrypt the file.
...
AnchorKeyStorePrivKeyPass
...
For keystore store types, an optional password used to encrypt private keys.
...
TrustAnchorLDAPUrl
...
For LDAP store types, the url to the LDAP server. Consists of the protocol, host, and port. Multiple URLs can be define and are comma delimited. Example: ldap://somehost:389
...
TrustAnchorLDAPUser
...
For LDAP store types, the user name credential for connecting to the LDAP store. May be empty if the LDAP server allows anonymous binding.
...
TrustAnchorLDAPPassword
...
For LDAP store types, The password credential for connecting to the LDAP store
...
TrustAnchorLDAPConnTimeout
...
For LDAP store types, an optional timeout in seconds before the connection is failed
...
TrustAnchorLDAPSearchBase
...
For LDAP store types, the distinguished name used as the base of LDAP searches.
...
TrustAnchorLDAPSearchAttr
...
For LDAP store types, the attribute in the LDAP store that is used to match a search query.
...
TrustAnchorLDAPCertAttr
...
For LDAP store types, the attribute in the search query result that holds the certificate file.
...
TrustAnchorLDAPCertFormat
...
For LDAP store types, the format of the certificate in the LDAP store. Valid formats: pkcs12, X.509
...
TrustAnchorLDAPCertPassphrase
...
For LDAP store types and pkcs12 files, the pass phrase used to encrypt the certificate.
Web Service Anchor storage
Anchors stored in the configuration service are added and maintained in the Anchors tab of the configuration service Manage Domains page.
Non Web Service Anchor Storage
Anchors stored in non web service mediums such as LDAP or a keystore require a list of aliases or search criteria to locate the certificates in the anchor store. Each domain requires one of two entries in the settings component: one for a list of outgoing anchors and/or one for a list of incoming anchors. The settings use the following format:
- <domainName>IncomingAnchorAliases
- <domainName>OutgoingAnchorAliases
The value for each setting is a comma delimited list of the aliases or search criteria that identify the anchor in the anchor store.
Example settings for the domain direct.connectopensource.org using a keystore:
...
SETTING NAME
...
VALUE
...
direct.connectopensource.orgIncomingAnchorAliases
...
direct.sitenv.org_ca,microsoft.com
...
direct.connectopensource.orgOutgoingAnchorAliases
...
direct.sitenv.org_ca,microsoft.com
| Note |
|---|
Regardless of the storage mechanism, a domain should always add its own trust anchor to its list or trusted anchors. This is a security precaution to ensure only users with valid certificates signed by the trust anchor can send from the agent's managed domain(s). |
Public Certificate Store Agent Settings
Similar to anchors, public certificates can be retrieved from different source mediums. The public certificate storage medium is configured in the Agent settings page.
Public Certificate Store Agent Settings parameters
...
SETTING NAME
...
VALUE/DESCRIPTION
PublicStoreType
...
PublicStoreFile
...
For keystore store types, the name of the file that contains the certificates. This can be just a file name, a fully qualified path, or a relative path.
...
PublicStoreFilePass
...
For keystore store types, an optional password used to encrypt the file.
...
PublicStorePrivKeyPass
...
For keystore store types, an optional password used to encrypt private keys.
Private Certificate Store Agent Settings
The private certificate storage medium is configured in the Agent settings page
Private Certificate Store Agent Settings parameters
...
SETTING NAME
...
VALUE/DESCRIPTION
...
PrivateStoreType
...
PrivateStoreFile
...
For keystore store types, the name of the file that contains the certificates. This can be just a file name, a fully qualified path, or a relative path.
...
PrivateStoreFilePass
...
For keystore store types, an optional password used to encrypt the file.
...
PrivateStorePrivKeyPass
...
For keystore store types, an optional password used to encrypt private keys.
...
PrivateStoreLDAPUrl
...
For LDAP store types, the url to the LDAP server. Consists of the protocol, host, and port. Multiple URLs can be define and are comma delimited. Example: ldap://somehost:389
...
PrivateStoreLDAPUser
...
For LDAP store types, the user name credential for connecting to the LDAP store. May be empty if the LDAP server allows anonymous binding.
...
PrivateStoreLDAPPassword
...
For LDAP store types, The password credential for connecting to the LDAP store.
...
PrivateStoreLDAPConnTimeout
...
For LDAP store types, an optional timeout in seconds before the connection is failed.
...
PrivateStoreLDAPSearchBase
...
For LDAP store types, the distinguished name used as the base of LDAP searches.
...
PrivateStoreLDAPSearchAttr
...
For LDAP store types, the attribute in the LDAP store that is used to match a search query.
...
PrivateStoreLDAPCertAttr
...
For LDAP store types, the attribute in the search query result that holds the certificate file.
...
PrivateStoreLDAPCertFormat
...
For LDAP store types, the format of the certificate in the LDAP store. Valid formats: pkcs12, X.509
...
PrivateStoreLDAPCertPassphrase
...
For LDAP store types and pkcs12 files, the pass phrase used to encrypt the certificate.
Add New Agent Setting
Selecting Add New Agent Setting option in the Agent Settings page opens up this page for adding key value pairs for agent settings.
Direct Configuration - Add New Agent Setting
Trust Bundles
Trust bundles are a collection of trust anchors that are intended to represent a trust community and generally meet a common set of criteria to be included in the bundle. Trust bundles are packaged into a single file using the PKCS7 standard and distributed via a known URL (the location is discovered out of band). Trust bundles are configured in the Trust Bundles tab of the configuration UI tool.
These bundles as wholistic objects and CONNECT does not support exclusion of anchors within the bundle. This is partly because the definition of a bundle indicates that each anchor within the bundle meets the same minimal requirements. The decision to include a bundle becomes a simple binary decision, you either trust the bundle or you don't.
Bundles are configured separately from domains as opposed to the importing of anchors per domain. Each bundle is identified by a name and it’s URL.
Select Trust Bundles tab to display a list of bundles that are imported into the configuration.
Direct Configuration - Trust Bundles screen
Trust Bundles
...
COLUMN
...
DESCRIPTION
...
Bundle Name
...
The bundle name
...
URL
...
The URL where the bundle is downloaded from
...
Checksum
...
A SHA1 hash of the bundle
...
Created
...
Time that the bundle was added to the system
...
Current As Of
...
The date when the bundle was last updated in the system
...
Last Refresh
...
The date and time when the system last checked for an update. If a newer/different bundle was found, the Current As Of date is also updated.
If not updates were found, then the Current As Of date does not change.
...
Refresh Interval
How often (in hours) updates are automatically checked.
| Note |
|---|
Automatic refresh of trust bundles has not yet been implemented and will be addressed in future releases. However you can always check for updates manually by clicking the Refresh Bundle option on the Trust Bundles screen. |
...
View Anchors
...
If you would like to see the anchor within a bundle, simply click the View Anchors link under the bundle name. This will display a list with the Distinguished Name of each anchor.
...
OPTION
...
DESCRIPTION
...
Add New Trust Bundle
...
Selecting this option pops open Add New Trust Bundle modal window that allows for creating a new trust bundle(See section 6.3.1)
...
Edit Trust Bundle
...
Selecting this option pops open Edit Trust Bundle modal window that allows for editing trust bundle(See section 6.3.2)
...
Delete
Checking the box next to the trust bundles and selecting this option removes a bundle from the system.The user is provided with an alert message for confirmation "Are you sure you want to delete the trust bundle? The trust bundle will be deleted for all domains ". If the user selects Yes, the trust bundle is deleted
| Note |
|---|
If you delete a bundle that has been associated to a domain, the association is automatically removed. |
...
Refresh Bundle
...
During the operation of your HISP, it may be necessary to update bundles in between their configured refresh cycle. To manually refresh/update a bundle, check the box next to the name of the bundles you want to update and select this option.The user is prompted with a "Refreshing trust bundle" status bar while this update operation is in progress.
...
View Anchors
...
Selecting the View Anchors link under the bundle name displays an anchor list with the Distinguished Name of each anchor in a popup dialog as shown below
Add New Trust Bundle
Direct Configuration - Add New Trust Bundle screen
The Add New Trust Bundle dialog will display the following information:
Add New Trust Bundles screen fields
...
FIELD
...
DESCRIPTION
...
Name(R)
...
A unique name of the bundle that describes the trust community of the bundle.
...
Trust Bundle URL(R)
The fully qualified URL where the trust bundle can be retrieved
| Note |
|---|
Per the Implementation Guide for Direct Project Trust Bundle distribution v1.0, signed Trust Bundles must have a .p7m file name extension, unsigned trust bundles are identified by .p7c or .p7b” file name extension |
...
Signing Certificate(O)
...
If the bundle has been signed, this is the certificate that signed the bundle to validate the integrity of the bundle. NOTE: It is completely optional to validate the bundle integrity against a signing certificate. If the bundle has not been signed, the signing certificate is ignored.
...
Refresh Interval(hours)
Indicates the frequency that the system will look for updates to the bundle. If this value is 0, then the system will never automatically look for updates, however you can always check for updates manually by clicking the refresh button.
| Note |
|---|
Automatic refresh of trust bundles has not yet been implemented and will be addressed in future releases. However you can always check for updates manually by clicking the Refresh Bundle option on the Trust Bundles screen. |
...
OPTION
...
DESCRIPTION
...
Add Trust Bundle
...
Selecting the option after adding the fields allows you to add a trust bundle to the Direct configuration, displays the trust bundles list page.
Edit Trust Bundle
Direct Configuration - Edit Selected Trust Bundle screen
The Edit Trust Bundle dialog will display the following information:
Edit Selected Trust Bundle screen fields
...
FIELD
...
DESCRIPTION
...
Trust Bundle Name(R)
...
A unique name of the bundle that describes the trust community of the bundle.
...
Trust Bundle URL(R)
...
The fully qualified URL where the trust bundle can be retrieved
...
Refresh Interval(hours)
...
Indicates the frequency that the system will look for updates to the bundle. If this value is 0, then the system will never automatically look for updates, however you can always check for updates manually by clicking the refresh button. (Automatic refresh of trust bundles will be addressed in future releases)
...
OPTION
...
DESCRIPTION
...
Update
...
Update the trust bundle
...
Certificates
Similar to anchors, public certificates can be retrieved from different source mediums.
The public certificate storage medium is configured in the settings page of the configuration UI.
The private certificate storage medium is configured in the settings page of the configuration UI.
Private and public certificates stored in the configuration service (WS StoreType) are added and maintained in the Certificates tab of the Direct Configuration page
Direct Configuration - Certificates screen
Edit Selected Trust Bundle screen fields
...
COLUMN
...
DESCRIPTION
...
Owner
...
Owner of the certificate. The owner is automatically populated by the service when the certificate is added.
...
Private
...
true/false - indicating if private or public certificate
...
Thumbprint
...
Certificate thumbprint
...
Created
...
Timestamp when this certificate was uploaded to the configuration service
...
Start/End
...
Certificate timestamp for validity
...
OPTION
...
DESCRIPTION
...
Add New Certificate
...
Selecting the option opens up the Add New Certificate page in a popup modal dialog to allow adding a new certificate to the config service.
...
Delete
...
Selecting this option deletes the selected certificate from the service.
Add New Certificate
Direct Configuration - Add New Certificate screen
Add New Certificate screen fields
...
FIELD
...
DESCRIPTION
...
Certificate
...
Location of the DER encoded certificate file that represents the private or public certificate that is uploaded to the configuration service. See Choose, Upload and Cancel for more details.
NOTE: Private certificate files should be pkcs12 encoded files with no encryption on both the file and private key stored in the file.
...
OPTION
...
DESCRIPTION
...
Submit
...
Clicking Submit will add the certificate to the configuration service.
...
MessageSettings
The following settings describe the location where processed messages should be stored. This is intended for debug purposes only and should not be set in a production environment.
MessageTypes:
- Raw: The raw message that entered the SMTP agent.
- Outgoing: If the message is determined to be an outgoing message, the security and trust processed outgoing message.
- Incoming: If the message is determined to be an incoming message, the security and trust processed incoming message.
- Bad: Messages that failed to be processed or caused other errors to be the thrown.
Table 20 - Message Setting values
...
Setting
...
Description
...
RawMessageSaveFolder
...
The folder where raw messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.
...
OutgoingMessageSaveFolder
...
The folder where outgoing messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.
...
IncomingMessageSaveFolder
...
The folder where incoming messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.
...
BadMessageSaveFolder
...
Connection Management
| Info |
|---|
As of CONNECT 5.1, Connection Management is replaced with 113311950 |
...
FIELD | DESCRIPTION | ||
|---|---|---|---|
| General Settings | |||
| Refresh Interval | Duration used for scheduling the next run of Refresh Exchange process. Expressed in minutes. | ||
| Maximum No Of Backups | Number of Backups, that the exchange refresh process is allowed to keep at a given time. | ||
| Default Exchange | A drop down that lists all the available exchanges for user. When selected, it will be used to look up services with a given HCID. If not defined, then the service are looked based on organization HCID only. | ||
| Exchanges | |||
| Name | Name of the Exchange | ||
| Type | Exchange type is a mandatory element and can have three values only, LOCAL, UDDI, FHIR | ||
| URL | Used for downloading the web services endpoints. | ||
| Last Updated | Last Updated displays the timestamp when the exchange was last refreshed | ||
| Refresh Exchange | A button that Enable/Disable an exchange for refresh. | ||
| Organizations | |||
| Exchange | Single select drop-down that's lists all the exchanges configured in the Exchange Manager configuration file. | ||
Organization | Single select drop-down that lists all the remote organizations or business entities, for a selected Exchange, configured in the Exchange Manager configuration file. Selecting any business entity updates the business entity fields and the business service fields below to reflect the parameter values for the organization | ||
Name | Organization Name as defined in the Exchange Manager configuration file for the selected Organization | ||
Description | Organization description as configured in the Exchange Manager configuration file for the selected Organization | ||
Contact | Contact name as configured in the Exchange Manager configuration file for the selected Organization | ||
HCID | Home Community ID as defined in the Exchange Manager configuration file for the selected Organization | ||
| Service Information | |||
| Service Name | Business service Name for the selected Organization | ||
| URL | Endpoint for the web service | ||
| Version | Version of the service provided | ||
| Ping Status | Default is --. Once ping initiated, values are Pass or Fail If ping successful - Pass. If ping is not successful - Fail | ||
| Last Ping | Timestamp for last ping for the web service | ||
OPTION | DESCRIPTION | ||
| Ping Service | Selecting this option after selecting a particular service pings the service. If the ping passed, Ping Status displays Pass If the ping fails, Ping Status displays Fail. A fail could be indicative of some firewall issue, certificate set up issue or some other issue where in the remote service is down
| ||
| Ping All Services | Clicking on Ping All Services, pings all services for a selected Exchange and Organization. | ||
...