This section explains how to prepare your setup before installing the REST services. In order to install and configure REST, you must perform the following tasks:
Ensure to get a pkcs12 server certificate. You can use server certificates generated by any external CA or iManager. For more information, see Creating a Server Certificate Object.
Ensure to get a CA certificate file in .pem format. For example, you can use the eDirectory CA certificate (SSCert.pem).
(Optional) Install and configure OSP before installing REST services. For more information, see Deploying OSP Container.
Create a configuration file with the following configuration parameters. For example, create edirapi.conf file. The values for the configuration file can be changed according to your requirement.
NOTE:Two sample configuration files will be bundled with the tarball image. You can choose to make changes to those files according to your business requirement.
In case, you want to configure REST with OSP, create a configuration file as shown below:
listen = ":9000" ldapserver = "192.168.1.1:636" ldapuser = "cn=admin,o=novell" ldappassword = "novell" pfxpassword = "novell" ospmode = "true" osp-token-endpoint = "https://192.168.1.1:8543/osp/a/idm/auth/oauth2/getattributes" osp-authorize-url = "https://192.168.1.1:8543/osp/a/idm/auth/oauth2/grant" osp-logout-url = "http://192.168.1.1:8543/osp/a/idm/auth/app/logout" osp-redirect-url = "https://10.10.10.10:9000/eDirAPI/v1/edirtree/authcoderedirect" osp-client-id = "edirapi" ospclientpass = "novell" ospcert = "/etc/opt/novell/eDirAPI/conf/ssl/trustedcert/SSCert.pem" bcert = "/etc/opt/novell/eDirAPI/cert/" loglevel = "error" check-origin = "true" origin = "https://10.10.10.10:9000,https://192.168.1.1:9000" enableaudit = "true" enableservicestartaudit = "true" enableservicestopaudit = "true" enablelogsessioncreationaudit = "true" enablelogsessionterminationaudit = "true" auditlogmaxsize = "50 MB" edirapilogmaxsize = "50 MB" scope = "ism"
In case, you want to configure REST without OSP, create a configuration file as shown below, without the OSP parameters:
listen = ":9000" ldapserver = "192.168.1.1:636" ldapuser = "cn=admin,o=novell" ldappassword = "novell" pfxpassword = "novell" ospmode = "false" bcert = "/etc/opt/novell/eDirAPI/cert/" loglevel = "error" check-origin = "true" origin = "https://10.10.10.10:9000,https://192.168.1.1:9000" enableaudit = "true" enableservicestartaudit = "true" enableservicestopaudit = "true" enablelogsessioncreationaudit = "true" enablelogsessionterminationaudit = "true" auditlogmaxsize = "50 MB" edirapilogmaxsize = "50 MB" scope = "ism" max-clients = "500"
Table 27-1 Description of the configuration parameters in the configuration file
Configuration Parameters |
Description |
---|---|
listen |
Specify 9000 as the REST server’s listener port inside the container. |
ldapserver |
Specify the eDirectory host server IP |
ldapuser |
Specify the username of the user with admin rights to the eDirectory tree. IMPORTANT:The username must be in lowercase. The eDirAPI docker container may fail to initialize if the username is in uppercase. |
ldappassword |
Specify the password of the LDAP server |
pfxpassword |
Specify the password of the .pfx certificate file |
ospmode |
Specify true to integrate OSP with Identity Console. If you set this to false, Identity Console will use ldap login |
osp-token-endpoint |
This URL is used to fetch certain attributes from the OSP server to verify the validity of the authentication token |
osp-authorize-url |
This URL is used by the user to provide credentials to obtain an authentication token |
osp-logout-url |
Use this URL to terminate the session between the user and the OSP server |
osp-redirect-url |
The OSP server re-directs the user to this URL after granting the authentication token |
osp-client-id |
Specify the OSP client ID which was provided at the time of the REST registration with OSP |
ospclientpass |
Specify the OSP client password which was provided at the time of the REST registration with OSP |
ospcert |
Specify the location of OSP server’s CA certificate |
bcert |
Specify location of Identity Console”s CA certificate |
loglevel |
Specify the log levels that you want to include in the log file. This parameter can be set to "fatal", "error", "warn" or "info". |
check-origin |
If this is set to true, the REST server compares the origin value of requests. Available options are either true or false. The origin parameter is mandatory even if check-origin parameter value is set to false when DNS configuration is used. |
origin |
eDirAPI compares the origin value of requests with the values specified in this field. NOTE:From eDirAPI 1.4 onward, this parameter is independent of check-origin parameter and is mandatory if DNS configuration is used. |
enableaudit |
Set this option to true to enable auditing for REST services. Available options are either true or false. |
enableservicestartaudit |
Set this option to true to get notified for REST service start events. Available options are either true or false. |
enableservicestopaudit |
Set this option to true to get notified for REST service stop events. Available options are either true or false. |
enablelogsessioncreationaudit |
Set this option to true to get notified for REST service session creation events. Available options are either true or false. |
enablelogsessionterminationaudit |
Set this option to true to get notified for REST service session termination events. Available options are either true or false. |
auditlogmaxsize |
Specify the maximum limit of each REST service’s audit log file size. By default, the file size is 50 MB. |
edirapilogmaxsize |
Specify the maximum limit of each REST server’s log file size. |
scope |
Specify the scope of REST server when it is used as a resource server in OAuth terminology. By default, it is set to edirapi <tree_name>. |
max-clients |
Maximum number of concurrent clients which can access edirapi. Any additional clients beyond this limit have to wait in queue. |
IMPORTANT:
The OSP related configuration parameters should be used only if you plan to integrate OSP along with REST services.
To enable auditing for REST services, you must configure the auditing related parameters in the configuration file.
OSP HTTPS URL should be validated with certificates containing 2048 bit key. This validation fails with certificates that contain 4096 or 8192 bit keys.