-
Notifications
You must be signed in to change notification settings - Fork 138
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add pkispawn EST deployment documentation
- Loading branch information
Showing
3 changed files
with
271 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # EST installation using `pki-server` | ||
|
|
||
| After the prerequisite in [Installing | ||
| EST](Installing_EST.md), it is possible to installa **EST**. | ||
|
|
||
| An instance has to be already available, if it is not present then it | ||
| is possible to create a new one with `pki-server create`, more details | ||
| [here](https://github.com/dogtagpki/pki/wiki/PKI-Server-Create-CLI). | ||
|
|
||
|
|
||
| Create the *EST subsytem* inside the pki server instance: | ||
|
|
||
| ``` | ||
| # pki-server est-create | ||
| ``` | ||
|
|
||
| Configure the issuance backend. The class `org.dogtagpki.est.DogtagRABackend` is used for the *Dogtag CA*. This requires: | ||
|
|
||
| - the **url** parameter pointing to the CA subsystem; | ||
| - credentials of an RA account, **username** and **password**, that is authorised to issue certificates using the configured profile; | ||
| - is also possible to use TLS client certificate authentication to authenticate to the CA subsystem. | ||
| - the **profile**. | ||
|
|
||
|
|
||
| ``` | ||
| # cat >/var/lib/pki/pki-tomcat/conf/est/backend.conf <<EOF | ||
| class=org.dogtagpki.est.DogtagRABackend | ||
| url=https://$(hostname):8443 | ||
| profile=estServiceCert | ||
| username=est-ra-1 | ||
| password=est4ever | ||
| EOF | ||
| ``` | ||
|
|
||
| Configure request authorization. The class `org.dogtagpki.est.ExternalProcessRequestAuthorizer` allows to delegate the authorization to an external process configured with the paramter **executable**: | ||
|
|
||
| ``` | ||
| # cat >/var/lib/pki/pki-tomcat/conf/est/authorizer.conf <<EOF | ||
| class=org.dogtagpki.est.ExternalProcessRequestAuthorizer | ||
| executable=/usr/local/libexec/estauthz | ||
| EOF | ||
| ``` | ||
|
|
||
| The executable should exist and have the right permission. Here an example: | ||
|
|
||
| ``` | ||
| # cat >/usr/local/libexec/estauthz <<EOF | ||
| #!/usr/bin/python3 | ||
| import json, sys | ||
| ALLOWED_ROLE = 'estclient' | ||
| obj = json.loads(sys.stdin.read()) | ||
| if not ALLOWED_ROLE in obj['authzData']['principal']['roles']: | ||
| print(f'Principal does not have required role {ALLOWED_ROLE!r}') | ||
| sys.exit(1) | ||
| EOF | ||
| # chmod +x /usr/local/libexec/estauthz | ||
| ``` | ||
|
|
||
| Deploy the EST application: | ||
|
|
||
| ``` | ||
| # pki-server est-deploy | ||
| ``` | ||
|
|
||
| Configure the authentication. The authentication is build on `com.netscape.cms.tomcat.ProxyRealm` class which allows to use realms from *tomcat* or developed for dogtag. As an example we use an in memory realm: | ||
|
|
||
| ``` | ||
| # cat >/var/lib/pki/pki-tomcat/conf/est/realm.conf <<EOF | ||
| class=com.netscape.cms.realm.PKIInMemoryRealm | ||
| username=alice | ||
| password=4me2Test | ||
| roles=estclient | ||
| EOF | ||
| ``` | ||
|
|
||
| Finally, restart the server: | ||
|
|
||
| ``` | ||
| # pki-server restart --wait | ||
| ``` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| # EST installation using `pkispawn` | ||
|
|
||
| After the prerequisite in [Installing | ||
| EST](Installing_EST.md), it is possible to installa **EST**. | ||
|
|
||
| ## REALM user DB | ||
|
|
||
|
|
||
| **EST** subsystem has its own realm authtnetication with a separate | ||
| user DB. Out of the box *LDAP*, *PostreSQL* and file based DB are | ||
| supported. User management is currently not performed by the subsystem | ||
| so the DB has to be prepared in advance. | ||
|
|
||
| ### LDAP based DB | ||
|
|
||
| The user DB requires a node containing the users (*inetOrgPerson*) and | ||
| a node containing the groups (*groupOfUniqueNames*). Therefore, if | ||
| the base dn is like `dc=pki,dc=example,dc=com` it is possible create a | ||
| tree with a user using the command: | ||
|
|
||
| ``` | ||
| ldapadd -x -H ldap://estds.example.com:3389 \ | ||
| -D "cn=Directory Manager" -w Secret.123 << EOF | ||
| dn: dc=est,dc=pki,dc=example,dc=com | ||
| objectClass: domain | ||
| dc: est | ||
| dn: ou=people,dc=est,dc=pki,dc=example,dc=com | ||
| ou: people | ||
| objectClass: top | ||
| objectClass: organizationalUnit | ||
| dn: ou=groups,dc=est,dc=pki,dc=example,dc=com | ||
| ou: groups | ||
| objectClass: top | ||
| objectClass: organizationalUnit | ||
| dn: uid=est-test-user,ou=people,dc=est,dc=pki,dc=example,dc=com | ||
| objectClass: top | ||
| objectClass: person | ||
| objectClass: organizationalPerson | ||
| objectClass: inetOrgPerson | ||
| uid: est-test-user | ||
| sn: EST TEST USER | ||
| cn: EST TEST USER | ||
| userPassword: Secret.123 | ||
| dn: cn=estclient,ou=groups,dc=est,dc=pki,dc=example,dc=com | ||
| objectClass: top | ||
| objectClass: groupOfUniqueNames | ||
| cn: estclient | ||
| uniqueMember: uid=est-test-user,ou=People,dc=est,dc=pki,dc=example,dc=com | ||
| EOF | ||
| ``` | ||
|
|
||
| ### PostgreSQL based DB | ||
|
|
||
| To use the *PostreSQL* DB the user tables should be created with the sql | ||
| file provided in `/usr/share/pki/est/conf/realm/postgresql/create.sql` | ||
| and then filled with the user information. | ||
|
|
||
| It is possible to use different schemas but in this case a custom | ||
| `statements.conf` file (provided in the same folder) has to be | ||
| provided in order to retrieve the user information from the DB. | ||
|
|
||
|
|
||
| ## Installation | ||
|
|
||
| An example installation configuration is provided in | ||
| `/usr/share/pki/server/examples/installation/est.cfg`. To install EST | ||
| in the same instance of the CA and with the DS realm run the command: | ||
|
|
||
| ``` | ||
| $ pkispawn \ | ||
| -f /usr/share/pki/server/examples/installation/est.cfg \ | ||
| -s EST \ | ||
| -D est_realm_url=ldap://ds.example.com:3389 \ | ||
| -v | ||
| ``` | ||
|
|
||
| The `est_realm_url` points to the user DB. The other configurations that could be modified according to the deployment are: | ||
|
|
||
| ``` | ||
| est_ca_profile=estServiceCert | ||
| est_ca_user_name= | ||
| est_ca_user_password= | ||
| est_ca_user_password_file= | ||
| est_ca_user_certificate= | ||
| est_realm_type= | ||
| est_realm_custom= | ||
| est_realm_url= | ||
| est_realm_auth_type=BasicAuth | ||
| est_realm_bind_dn=cn=Directory Manager | ||
| est_realm_bind_password= | ||
| est_realm_nickname= | ||
| est_realm_user= | ||
| est_realm_username= | ||
| est_realm_password= | ||
| est_realm_users_dn=ou=people,dc=est,dc=pki,dc=example,dc=com | ||
| est_realm_groups_dn=ou=groups,dc=est,dc=pki,dc=example,dc=com | ||
| est_realm_statements=/usr/share/pki/est/conf/realm/postgresql/statements.conf | ||
| est_authorizer_exec_path=/usr/share/pki/est/bin/estauthz | ||
| ``` | ||
|
|
||
| The `est_ca_*` provides information related to the user and profile | ||
| configured in the CA for the EST subsystem. | ||
|
|
||
| The `est_authorizer_exec_path` is the executable responsible to verify | ||
| the authorisation. The provided script checks only that the user has | ||
| the role *estclient*. | ||
|
|
||
| The `est_realm_*` options allow to customise the realm. Possible types | ||
| are: ds, postgresql and in-memory. As an example, to install EST with | ||
| PostgreSQL the command will be | ||
|
|
||
| ``` | ||
| pkispawn \ | ||
| -f /usr/share/pki/server/examples/installation/est.cfg \ | ||
| -s EST \ | ||
| -D est_realm_url="jdbc:postgresql://postgresql.example.com:5432/est?ssl=true&sslmode=require" \ | ||
| -D est_realm_type=postgresql \ | ||
| -D est_realm_user=est \ | ||
| -D est_realm_password=mysecretpassword \ | ||
| -v | ||
| ``` | ||
|
|
||
| The `est_realm_custom` is a path to a custom realm configuration for | ||
| tomcat and if provided it will overwrite all other realm related | ||
| configurations. | ||
|
|
||
| ### Installation on separate instance | ||
|
|
||
| When installed on a separate instance the CA URL and the signing | ||
| certificate has to be provided. This is done with the command: | ||
|
|
||
| ``` | ||
| pkispawn \ | ||
| -f /usr/share/pki/server/examples/installation/est.cfg \ | ||
| -s EST \ | ||
| -D est_realm_url=ldap://estds.example.com:3389 \ | ||
| -D pki_ca_uri=https://ca.example.com:8443 \ | ||
| -D pki_cert_chain_path=ca_signing.crt \ | ||
| -D pki_cert_chain_nickname=caSigning \ | ||
| -v | ||
| ``` | ||
|
|
||
| EST will get the SSL server certificate through the EST provided user | ||
| and profile. If the SSL certificate (and the user certificate if it is | ||
| needed to connect to the CA) should be created differently then it is | ||
| possible to provide a PKCS12 bundle including the certificate and the | ||
| full chain. It is important that the certificate aliases in PKCS12 match | ||
| with the nickname used by EST. For SSL certificate the nickname | ||
| configured in `est.cfg` is `sslserver` but can be modified. The | ||
| command to deploy with the certificate bundle is: | ||
|
|
||
| ``` | ||
| pkispawn \ | ||
| -f /usr/share/pki/server/examples/installation/est.cfg \ | ||
| -s EST \ | ||
| -D est_realm_url=ldap://estds.example.com:3389 \ | ||
| -D pki_ca_uri=https://ca.example.com:8443 \ | ||
| -D est_ca_user_password= \ | ||
| -D est_ca_user_certificate=estUser \ | ||
| -D pki_server_pkcs12_path=$SHARED/est_server.p12 \ | ||
| -D pki_server_pkcs12_password=Secret.123 \ | ||
| -v | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| ## Removing EST | ||
|
|
||
| To remove the EST subsystem it is possible to use the `pkidestroy` command as follow: | ||
|
|
||
| ``` | ||
| pkidestroy -i pki-tomcat -s CA -v | ||
| ``` | ||
|
|
||
| Note: the configuration and log folders are not removed. To remove | ||
| everything add the the options: `--remove-conf` `--remove-logs`. |