Software AG Products 10.7 | Using API Gateway | API Gateway Administration | Security Configuration | Ports | Adding an API Gateway External Port
 
Adding an API Gateway External Port
The API Gateway external and registration ports work as a pair. One port is not functional without the other.
*To add an API Gateway external port
1. Expand the menu options icon , in the title bar, and select Administration.
2. Select Security > Ports.
The ports page lists all the ports configured with API Gateway, if any.
3. Click Add Ports.
4. Select the type of port as API Gateway external and click Add.
5. Provide the following information:
Field
Description
API Gateway external listener configuration. Provide the following details to configure the HTTP listener set up.
External port
Specifies the port number you want to use for the external port.
Use a number that is not already in use. This is the port that clients connect to through your outer firewall.
Alias
Specifies an alias for the port.
An alias must be between 1 and 255 characters in length and include one or more of the following: letters (a -z, A-Z), numbers (0-9), underscore (_), period (.), and hyphen (-).
Description (optional)
A description of the port.
Protocol
Specifies the protocol to use for this port (HTTP or HTTPS).
If you select HTTPS, additional security and credential boxes appear for which you have to provide the required values.
Bind address (optional)
Specifies the IP address to which to bind this port.
Specify a bind address if your machine has multiple IP addresses and you want the port to use this specific address. If you do not specify a bind address, API Gateway picks one for you.
Backlog
Specifies the number of requests that can remain in the queue for an enabled port before API Gateway begins rejecting requests.
The default is 200. The maximum value is 65535.
Keep alive timeout
Specifies when to close the connection if the server has not received a request from the client within this timeout value (in milliseconds) or when to close the connection if the client has explicitly placed a close request with the server.
The default value is 20000ms.
Private threadpool configuration. Specifies whether to create a private thread pool for this port or use the common thread pool.
Enable
Select to enable the private threadpool configuration for this port.
Threadpool min
Specifies the minimum number of threads for this private threadpool. The default value is 1.
Threadpool max
Specifies the maximum number of threads for this private thread pool. The default value is 5.
Thread priority
Specifies the Java thread priority. The default value is 5.
Security configuration. Provide the following details to configure security parameters.
Client authentication
For the external port, specify the type of client authentication required.
Select one of the following:
*Username/Password . API Gateway does not request client certificates. The server looks for user and password information in the header of requests coming from an external client.
*Digest. API Gateway uses password digest authentication. API Gateway looks for password digest information in the header of requests coming from an external client.
*Request kerberos ticket. API Gateway looks for a Kerberos ticket in the HTTP Authorization header using the Negotiate authentication scheme. If it does not find the ticket, API Gateway uses username and password for basic authentication. If the client does not provide any authentication information, API Gateway returns an HTTP WWW-Authenticate header with negotiate scheme to the client requesting for authentication information. If the client provides the required authentication information, API Gateway verifies and validates the request.
*Require kerberos ticket. API Gateway looks for a Kerberos ticket in the HTTP Authorization header using the Negotiate authentication scheme. If it does not find the ticket, API Gateway fails the authentication. If the client does not provide any authentication information, API Gateway returns an HTTP WWW-Authenticate header with negotiate scheme to the client requesting for authentication information. If the client provides the required authentication information, API Gateway verifies and validates the request.
*Request client certificate. This option appears only if you select the HTTPS option in the Protocol field of the API Gateway external listener configuration section. API Gateway requests client certificates for all requests. If the client does not provide a certificate, the server prompts the client for a userid and password. The server checks whether the certificate exactly matches a client certificate on file and is signed by a trusted authority. If so, the client is logged in as the user to which the certificate is mapped in API Gateway. If not, the client request fails, unless central user management is configured.
*Require client certificate. This option appears only if you select the HTTPS option in the Protocol field of the API Gateway external listener configuration section. API Gateway requires client certificates for all requests. The server behaves as described for Request Client Certificates, except that the client must always provide a certificate.
You have to enable Kerberos by providing the following Kerberos properties with details that are used for handling service requests that come with a Kerberos ticket:
*JAAS context. Specify the custom JAAS context used for Kerberos authentication.
*Principal. Specify the name of the principal to use for Kerberos authentication.
*Principal password. Specify the password for the principal that is used to authenticate the principal to the KDC.
*Retype principal password. Retype the principal password.
*Service principal name. Specify the name of the principal used with the service that the Kerberos client wants to access. API Gateway supports the username format for Service Principal Names (SPNs). This format represents the principal name as a named user defined in the LDAP or central user directory used for authentication to the KDC.
Use JSSE
This field appears only if you select the HTTPS option in the Protocol field of the API Gateway external listener configuration sectionSelect Yes to create the port using the Java Secure Socket Extension (JSSE) socket factory for the port to support TLS 1.1 or TLS 1.2. The default value is Yes.
If you set this value to No, the port supports only SSL 3.0 and TLS 1.0.
Listener specific credentials (optional). This section appears only if you select the HTTPS option in the Protocol field of the API Gateway external listener configuration section. Provide the following details to configure listener specific credentials.
Keystore alias
Specifies a user-specified, text identifier for an API Gateway keystore.
The alias points to a repository of private keys and their associated certificates. Although each listener points to one keystore, there can be multiple keys and their certificates in the same keystore, and more than one listener can use the same keystore alias.
Key alias (signing)
Specifies the private key of keystore.
Truststore alias
Specifies the public certificates of truststore.
The alias points to a repository of public certificates.
API Gateway registration listener configuration . Provide the following details to configure listener specific credentials.
Registration port
Specifies the number you want to use for the registration port.
Use a number that is not already in use. It is best not to use a standard port such as 80 (the standard port for HTTP) or 443 (the standard port for HTTPS) because the external firewall allows access to those ports from the outside world.
You can add multiple registration ports by clicking +Add.
Alias
Specifies an alias for the port.
An alias must be between 1 and 255 characters in length and include one or more of the following: leers (a -z, A-Z), numbers (0-9), underscore (_), period (.), and hyphen (-).
Description (optional)
A description of the port.
Protocol
Specifies the protocol to use for this port (HTTP or HTTPS).
If you select HTTPS, additional security and credential boxes appear for which you have to provide the required values.
Bind address (optional)
Specifies the IP address to which to bind this port.
Specify a bind address if your machine has multiple IP addresses and you want the port to use this specific address. If you do not specify a bind address, API Gateway picks one for you.
Security configuration. Provide the following details to configure security parameters.
Client authentication
For the external port, specify the type of client authentication required.
Select one of the following:
*Username/Password . API Gateway does not request client certificates. The server looks for user and password information in the header of requests coming from an external client.
*Request client certificate. This option appears only if you select the HTTPS option in the Protocol field of the API Gateway registration listener configuration section. API Gateway requests client certificates for all requests. If the client does not provide a certificate, the server prompts the client for a userid and password. The server checks whether the certificate exactly matches a client certificate on file and is signed by a trusted authority. If so, the client is logged in as the user to which the certificate is mapped in API Gateway. If not, the client request fails, unless central user management is configured.
*Require client certificate. This option appears only if you select the HTTPS option in the Protocol field of the API Gateway registration listener configuration section.API Gateway requires client certificates for all requests. The server behaves as described for Request Client Certificates, except that the client must always provide a certificate.
Use JSSE
This field appears only if you select the HTTPS option in the Protocol field of the API Gateway registration listener configuration section. Select Yes to create the port using the Java Secure Socket Extension (JSSE) socket factory for the port to support TLS 1.1 or TLS 1.2. The default value is Yes.
If you set this value to No, the port supports only SSL 3.0 and TLS 1.0.
Listener specific credentials (optional). This section appears only if you select HTTPS in the Protocol field of the API Gateway registration listener configuration section.. Provide the following details to configure listener specific credentials.
Keystore alias
Specifies a user-specified, text identifier for an API Gateway keystore.
The alias points to a repository of private keys and their associated certificates. Although each listener points to one keystore, there can be multiple keys and their certificates in the same keystore, and more than one listener can use the same keystore alias.
Key alias (signing)
Specifies the private key of keystore.
Truststore alias
Specifies the public certificates of truststore.
The alias points to a repository of public certificates.
6. Click Add.
The port is created and is listed in the ports table.
Important:
The global IP access mode will be applied to the newly created external and registration listener ports. You can modify the IP access mode as per your requirement. For information on modifying IP access mode of ports, see Configuring IP Access Mode for a Port.
7. Click the icon in the Enabled column next to the external and registration ports to enable them.
The port is enabled and a success message appears.