Initial configurations

PARME provides a convenient way to define them inside a .env (with a leading dot) file located in the root folder of parme-api component.

The .env file is read and parsed on every request and its env vars are added to the $_ENV & $_SERVER variables. Any existing env vars are never overwritten by the values defined in .env, so you can combine both.

SQL database creation

The preparation of the database must be realized before starting the configuration of PARME. To do that, you need to create the PARME target database and import the provided SQL file (parme-pack/parme.sql) in it.

Database link

To define the link to parme-data which hosts the database containing configuration and user’s data manipulation by PARME, you must define the DATABASE_URL env variable in the .env file.

The easiest way to specify commonly used connection parameters is using a database URL. The scheme is used to specify a driver, the user and password in the URL encode user and password for the connection, followed by the host and port parts (the “authority”). The path after the authority part represents the name of the database, sans the leading slash. Any query parameters are used as additional connection parameters.

The scheme names representing the drivers are either the regular driver names (see below) with any underscores in their name replaced with a hyphen (to make them legal in URL scheme names), or one of the following simplified driver names that serve as aliases:

  • db2: alias for IBM db2
  • mssql: alias for Microsoft SQL Server
  • mysql/mysql2: alias for Mysql
  • pgsql/postgres/postgresql: alias for PostgreSQL
  • sqlite/sqlite3: alias for SQLite

For example, to connect to a “parmedata” MySQL DB running on localhost port 4486 with the charset set to UTF-8, you would use the following URL:

DATABASE_URL=mysql://localhost:4486/parmedata?charset=UTF-8

For the connexion to a SQL Server data base named parmedata hosted on localhost\SQLInstance

DATABASE_URL=sqlsrv://sa:[email protected]\SQLINSTANCE/parmedata

For connecting to an SQLite database, the authority portion of the URL is obviously irrelevant and thus can be omitted. The path part of the URL is, like for all other drivers, stripped of its leading slash, resulting in a relative file name for the database:

DATABASE_URL=sqlite://parmedata.sqlite

This would access parmedata.sqlite in the parme-api public folder and is identical to the following:

DATABASE_URL=sqlite://ignored:[email protected]:1234/parmedata.sqlite

To specify an absolute file path, e.g. C:\data\parmedata.sqlite, simply use that as the database name, which results in two leading slashes for the path part of the URL, and four slashes in total after the URL scheme name and its following colon:

DATABASE_URL=sqlite://C:\data\parmedata.sqlite

Which is, again, identical to supplying ignored user/pass/authority:

DATABASE_URL=sqlite://notused:[email protected]//usr/local/var/db.sqlite

To connect to an in-memory SQLite instance, use :memory: as the database name:

DATABASE_URL=sqlite:///:memory:

To connect to a parmedata PostgreSQL database running on localhost, use the following example:

DATABASE_URL=postgres://localhost/parmedata?pool=5

Any information extracted from the URL overwrites existing values for the parameter in question, but the rest of the information is merged together. You could, for example, have a URL without the charset setting in the query string, and then add a charset connection parameter next to url, to provide a default value in case the URL doesn’t contain a charset value.

SMTP Server link

PARME provides a mailer feature based on mailing servers standards. This mailer supports sending messages with your own mail servers as well as using popular email providers like MandrillSendGridAmazon SES or Gmail.
Al the configuration is done on the parme-api component .env file. You just need update the MAILER_URL of your .env file as it is done here for Gmail:

MAILER_URL=gmail://username:[email protected]

The gmail transport is a shortcut that uses the smtp transport, ssl encryption, login auth mode and smtp.gmail.com host. If your app uses other encryption or auth mode, you must override those values:

MAILER_URL=gmail://username:[email protected]?encryption=tls&auth_mode=oauth

If your Gmail account uses 2-Step-Verification, you must generate an App password and use it as the value of the mailer password. You must also ensure that you allow less secure applications to access your Gmail account.

Using SMTP and Cloud Services to Send Emails

Cloud mailing services are a popular option for companies that don’t want to set up and maintain their own reliable mail servers. To use these services in a PARME, update the value of MAILER_URL in the parme-api component .env file. For example, for Amazon SES (Simple Email Service):

MAILER_URL=smtp://email-smtp.us-east-1.amazonaws.com:587?encryption=tls&username=YOUR_SES_USERNAME&password=YOUR_SES_PASSWORD

Use the same technique for other mail services, as most of the time there is nothing more to it than configuring an SMTP endpoint.

LDAP Link

Before you can use the LDAP calls you will need to know ..

  • The name or address of the directory server you will use
  • The “base dn” of the server (the part of the world directory that is held on this server, which could be “o=My Company,c=US”)
  • Whether you need a password to access the server (many servers will provide read access for an “anonymous bind” but require a password for anything else)

Once all these information and prerequisites are gathered, you can configure them in. parme-api component .env file. In this context, you will need to configure the following statements:

Directory Server

AD_SERVER_URL : Lightweight Directory Access Protocol ldap server hostname
AD_PROTOCOLE : ldaps value must be set in order to secure the link and make password change working
AD_PORT_LDAP : Lightweight Directory Access Protocol tcp port
AD_PORT_LDAPS : Lightweight Directory Access Protocol tcp port over TLS/SSL (LDAPS)
AD_DN_BASE : the directory container distingued name container the users that we have to manage
AD_SUFFIX : for Active directory, set the domain DNS name prefixed by “@” caracter

Technication account credentials

Technication account is thr one used by PARME to access the server to authenticate users or proceed to the password changes or resets. It may have the right to perform the cited operations.

AD_LDAP_RDN : the technical account login name
AD_LDAP_PASS : the technical account login name (crypted format is supported)

HTTPS Configuration

HTTPS is a secure communications channel that is used to exchange information between a client computer and a server. It uses Secure Sockets Layer (SSL). This article describes how to configure the SSL/HTTPS service in Internet Information Services (IIS) and compares this process to the similar process in Apache.

Configuring Your Web Server for SSL

To enable SSL in IIS, you must first obtain a certificate that is used to encrypt and decrypt the information that is transferred over the network. IIS includes its own certificate request tool that you can use to send a certificate request to a certification authority. This tool simplifies the process of obtaining a certificate. If you use Apache, you must obtain the certificate manually.

In both IIS and Apache, you receive a certificate file from the certification authority, which you must configure on the computer. Apache reads the certificate from its source file by using the SSLCACertificateFile directive. However, in IIS, you can configure and manage certificates by using the Directory Security tab of the Web site or folder properties.

You can migrate certificates from Apache to IIS; however, Microsoft recommends that you re-create or obtain a new certificate for IIS.

Configure Folder or Web Site to Use SSL/HTTPS

This procedure assumes that your site has already has a certificate assigned to it.

  1. Log on to the Web server computer as an administrator.
  2. Click Start, point to Settings, and then click Control Panel.
  3. Double-click Administrative Tools, and then double click Internet Services Manager.
  4. Select the parme-api (and later parme-core) among the the list of different web sites served sites in the left pane.
  5. Right-click the Web site, folder, or file for which you want to configure SSL communication, and then click “Edit Bindings”.
  6. Select the corect binding
  7. Click Edit.
  8. Select the suited certificate. Please note that this certificate must have been imported previously on the server.
    Alternatively, to allow a user to supply their own certificate, use Accept client certificates.
  9. To configure client mapping, click Enable client certificate mapping, and then click Edit to map client certificates to users.

    If you configure this functionality, you can map client certificates to individual users in Active Directory. You can use this functionality to automatically identify a user according to the certificate they supplied when they access the Web site. You can map users to certificates on a one-to-one basis (one certificate identifies one user) or you can map many certificates to one user (a list of certificates is matched against a specific user according to specific rules. The first valid match becomes the mapping).
  10. Click OK.

See the following video: https://channel9.msdn.com/Blogs/IIS-NET-Site-Videos/configuring-ssl-in-iis-manager

LDAPS configuration

PARME uses OpenLDAP client to access. If your LDAP server uses security certificate(s), place them in the C:\OpenLDAP directory of your server.

In tis folder, you will find the sysconfig/ldap.conf file where all OpenLDAP client configuration is done

Ensure that your certificates do not have a password. There is an extremely strong probability that these certificates are different than the certificates used to secure a site environment using HTTPS. If you’re unsure, check with your sever administrator to make sure that you are using the correct TLS certificates to communicate with your LDAP server.

OpenLDAP Client configuration

OpenLDAP clients and servers are capable of using the Transport Layer Security (TLS) framework to provide integrity and confidentiality protections and to support LDAP authentication using the SASL EXTERNAL mechanism.

TLS Certificates

TLS uses X.509 certificates to carry client and server identities. All servers are required to have valid certificates, whereas client certificates are optional. Clients must have a valid certificate in order to authenticate via SASL EXTERNAL. For more information on creating and managing certificates, see the OpenSSL documentation.

Server Certificates

The DN of a server certificate must use the CN attribute to name the server, and the CN must carry the server’s fully qualified domain name. Additional alias names and wildcards may be present in the subjectAltName certificate extension. More details on server certificate names are in RFC2830.

Client Certificates

The DN of a client certificate can be used directly as an authentication DN. Since X.509 is a part of the X.500 standard and LDAP is also based on X.500, both use the same DN formats and generally the DN in a user’s X.509 certificate should be identical to the DN of their LDAP entry. However, sometimes the DNs may not be exactly the same, and so the mapping facility described in Mapping Authentication identities to LDAP entries can be applied to these DNs as well.

TLS Configuration

After obtaining the required certificates, a number of options must be configured on both the client and the server to enable TLS and make use of the certificates. At a minimum, the clients must be configured with the filename containing all of the Certificate Authority (CA) certificates it will trust. The server must be configured with the CA certificates and also its own server certificate and private key.

Typically a single CA will have issued the server certificate and all of the trusted client certificates, so the server only needs to trust that one signing CA. However, a client may wish to connect to a variety of secure servers managed by different organizations, with server certificates generated by many different CAs. As such, a client is likely to need a list of many different trusted CAs in its configuration.

Server Configuration

The configuration directives for slapd belong in the global directives section of slapd.conf(5).

TLSCACertificateFile <filename>

This directive specifies the PEM-format file containing certificates for the CA’s that slapd will trust. The certificate for the CA that signed the server certificate must be included among these certificates. If the signing CA was not a top-level (root) CA, certificates for the entire sequence of CA’s from the signing CA to the top-level CA should be present. Multiple certificates are simply appended to the file; the order is not significant.

TLSCACertificatePath <path>

This directive specifies the path of a directory that contains individual CA certificates in separate files. In addition, this directory must be specially managed using the OpenSSL c_rehash utility. When using this feature, the OpenSSL library will attempt to locate certificate files based on a hash of their name and serial number. The c_rehash utility is used to generate symbolic links with the hashed names that point to the actual certificate files. As such, this option can only be used with a filesystem that actually supports symbolic links. In general, it is simpler to use the TLSCACertificateFile directive instead.

TLSCertificateFile <filename>

This directive specifies the file that contains the slapd server certificate. Certificates are generally public information and require no special protection.

TLSCertificateKeyFile <filename>

This directive specifies the file that contains the private key that matches the certificate stored in the TLSCertificateFile file. Private keys themselves are sensitive data and are usually password encrypted for protection. However, the current implementation doesn’t support encrypted keys so the key must not be encrypted and the file itself must be protected carefully.

TLSCipherSuite <cipher-suite-spec>

This directive configures what ciphers will be accepted and the preference order. <cipher-suite-spec> should be a cipher specification for OpenSSL. You can use the command

        openssl ciphers -v ALL

to obtain a verbose list of available cipher specifications. Besides the individual cipher names, the specifiers HIGH, MEDIUM, LOW, EXPORT, and EXPORT40 may be helpful, along with TLSv1, SSLv3, and SSLv2.

TLSRandFile <filename>

This directive specifies the file to obtain random bits from when /dev/urandom is not available. If the system provides /dev/urandom then this option is not needed, otherwise a source of random data must be configured. Some systems (e.g. Linux) provide /dev/urandom by default, while others (e.g. Solaris) require the installation of a patch to provide it, and others may not support it at all. In the latter case, EGD or PRNGD should be installed, and this directive should specify the name of the EGD/PRNGD socket. The environment variable RANDFILE can also be used to specify the filename. Also, in the absence of these options, the .rnd file in the slapd user’s home directory may be used if it exists. To use the .rnd file, just create the file and copy a few hundred bytes of arbitrary data into the file. The file is only used to provide a seed for the pseudo-random number generator, and it doesn’t need very much data to work.

TLSVerifyClient { never | allow | try | demand }

This directive specifies what checks to perform on client certificates in an incoming TLS session, if any. This option is set to never by default, in which case the server never asks the client for a certificate. With a setting of allow the server will ask for a client certificate; if none is provided the session proceeds normally. If a certificate is provided but the server is unable to verify it, the certificate is ignored and the session proceeds normally, as if no certificate had been provided. With a setting of try the certificate is requested, and if none is provided, the session proceeds normally. If a certificate is provided and it cannot be verified, the session is immediately terminated. With a setting of demand the certificate is requested and a valid certificate must be provided, otherwise the session is immediately terminated.


Note: The server must request a client certificate in order to use the SASL EXTERNAL authentication mechanism with a TLS session. As such, a non-default TLSVerifyClient setting must be configured before SASL EXTERNAL authentication may be attempted, and the SASL EXTERNAL mechanism will only be offered to the client if a valid client certificate was received.


Client Configuration

Most of the client configuration directives parallel the server directives. The names of the directives are different, and they go into ldap.conf(5) instead of slapd.conf(5), but their functionality is mostly the same. Also, while most of these options may be configured on a system-wide basis, they may all be overridden by individual users in their .ldaprc files.

TLS_CACERT <filename>

This is equivalent to the server’s TLSCACertificateFile option. As noted in the TLS Configuration section, a client typically may need to know about more CAs than a server, but otherwise the same considerations apply.

TLS_CACERTDIR <path>

This is equivalent to the server’s TLSCACertificatePath option. The specified directory must be managed with the OpenSSL c_rehash utility as well.

TLS_CERT <filename>

This directive specifies the file that contains the client certificate. This is a user-only directive and can only be specified in a user’s .ldaprc file.

TLS_KEY <filename>

This directive specifies the file that contains the private key that matches the certificate stored in the TLS_CERT file. The same constraints mentioned for TLSCertificateKeyFile apply here. This is also a user-only directive.

TLS_RANDFILE <filename>

This directive is the same as the server’s TLSRandFile option.

TLS_REQCERT { never | allow | try | demand }

This directive is equivalent to the server’s TLSVerifyClient option. However, for clients the default value is demand and there generally is no good reason to change this setting.

TLS { never | hard }

This directive specifies whether client connections should use TLS by default. The default setting is never which specifies that connections will be opened in the clear unless TLS is explicitly specified using an “ldaps://” URL. When set to hard all connections will be established with TLS, as if an “ldaps://” URL was specified. Note that the use of ldaps is a holdover from LDAPv2 and this setting is incompatible with the LDAPv3 StartTLS request. As such, it’s best not to use this option.

Was this page helpful?