Aliases

An alias in API Gateway holds environment-specific property values that can be used in policy routing configuration. The aliases can be referred to in routing endpoints, routing rules, endpoint connection properties, and outbound authentication tokens instead of providing a real value. The corresponding alias value is substituted in place of an alias name during run-time. Thus the same alias can be referred to in multiple policies and the change in a particular alias would affect all the policy properties in which it is being referred. When an API is exported and imported to a different environment, you can update the alias values specific to the environment instead of updating the policy with environment specific values. You can create six types of alias:

  • Simple alias
  • Endpoint alias
  • HTTP transport security alias
  • SOAP message security alias
  • webMethods IS Service alias
  • XSLT Transformation alias

Creating a Simple Alias

You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

A simple alias holds simple key property values. The name of the alias can be used in the configuration of the properties of a routing policy or an email destination for the Log Invocation, Monitor SLA, Monitor Performance, and Traffic Optimization policies.

To create a simple alias

  1. Expand the menu options icon icon, in the title bar, and select Aliases.

  2. Click Create alias.

  3. In the Basic information section, provide the following information:

    Field Description
    Name Name of the alias.
    Type Select Simple alias.
    Description Description of the alias.
  4. Click Technical information and specify a value in the Default value field.

  5. Specify a stage, if you want the alias to be applicable to a specific stage.

  6. Click Save.

    Note: For example, if you create a simple alias called hostname with value dev.com and in the routing policy you can specify the https://dev.com/v2 endpoint as https://${hostname}/v2. At runtime invocation the simple alias ${hostname} will be replaced with its value dev.com. .

Creating an Endpoint Alias

You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

An endpoint alias stores the endpoint value along with additional properties such as connection timeout, read timeout, whether to pass security headers or not, keystore alias, key alias, and so on.

To create an endpoint alias

  1. Expand the menu options icon icon, in the title bar, and select Aliases.

  2. Click Create alias.

  3. In the Basic information section, provide the following information:

    Field Description
    Name Name of the alias.
    Type Select Endpoint alias.
    Description Description of the alias.
  4. Click Technical information and provide the following information:

    Field Description
    Optimization technique This is applicable only for a SOAP API. Specify the optimization technique for the SOAP request received. Select any one of the following:
    • None. This is the default value. API Gateway does not use any optimization method to parse the SOAP requests to the API.
    • MTOM. Indicates that API Gateway expects to receive a request with a Message Transmission Optimization Mechanism (MTOM) attachment and forwards the attachment to the native service.
    • SWA. Indicates that API Gateway expects to receive a SOAP with Attachment (SWA) request and forwards the attachment to the native service.
    Pass WS-Security Headers Passes the security header.
    Endpoint URI Specify the default URI or components of the URI such as service name.
    Connection timeout Specify the time interval (in seconds) after which a connection attempt times out. The precedence of the Connection Timeout configuration is as follows:
    1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
    2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
    3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.connectionTimeout property.
    4. If you do not specify any value for pg.endpoint.connectionTimeout, then API Gateway uses the default value of 30 seconds.
    Read timeout Specify the time interval (in seconds) after which a socket read attempt times out. The precedence of the Read Timeout configuration is as follows:
    1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
    2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
    3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.readTimeout property.
    4. If you do not specify any value for pg.endpoint.readTimeout, then API Gateway uses the default value of 30 seconds.
    Keystore alias Specifies the keystore alias configured in API Gateway. This value (along with the value of Client Certificate Alias) is used for performing SSL client authentication.
    Lists all available keystores. If you have not configured any keystore, the list is empty.
    Key alias Specifies the alias for the private key, which must be stored in the keystore specified by the keystore alias.
    Truststore alias Specifies the alias for the truststore that contains the list of CA certificates that API Gateway uses to validate the trust relationship with the native API.
    If you do not configure any truststore alias, it implies that API Gateway does not validate the certificates provided by native APIs.
    Stage Specif a stage, if you want the alias to be applicable to a specific stage.
  5. Click Save.

Creating an HTTP Transport Security Alias

You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

An HTTP Transport security alias contains transport level security information required while accessing the native API. Transport level security that are supported in API Gateway outbound are as follows:

To create an HTTP transport secure alias

  1. Expand the menu options icon icon, in the title bar, and select Aliases.

  2. Click Create alias.

  3. In the Basic information section, provide the following information:

    Field Description
    Name Name of the alias.
    Type Select HTTP transport security alias.
    Description Description of the alias.
  4. Click Technical information and provide the following information:

    Field Description
    Authentication scheme Specify the type of authentication you want to use while communicating with the native API.

    Select one of the following:

    • Basic. Uses basic authentication (user name and password).
    • Kerberos. Uses Kerberos authentication.
    • NTLM. Uses NTLM authentication.
    • OAuth2. Uses OAuth2 authentication.
    • JWT. Uses JWT authentication.
    For the Authentication type Basic, authenticate using the following:
    Custom credentials Specifies the values provided in the policy required to access the native API.

    Provide the following information:

    • Username. Specify a username to access the native API.
    • Password. Specify a password to access the native API.
    • Domain. Specify a domain to access the native API.
    Incoming HTTP basic auth credentials No properties required. Considers the incoming HTTP basic authentication credentials.
    For Authentication type Kerberos, authenticate using any of the following:
    Custom credentials Specifies the values provided in the policy required to obtain the Kerberos token to access the native API.
    Provide the following information:
    • Client principal. A valid client LDAP user name.
    • Client password. A valid password of the client LDAP user.
    • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
      • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
      • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
    Delegate incoming credentials Specifies the values provided in the policy required by the API providers to select whether to delegate the incoming Kerberos token or act as a normal client.

    Provide the following information:

    • Client principal. A valid client LDAP user name.
    • Client password. A valid password of the client LDAP user.
    • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
      • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
      • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
    Incoming HTTP basic auth credentials Specifies the incoming HTTP basic authentication credentials in the transport header of the incoming request for client principal and client password.

    Provide the following information:

    • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Available values are:
      • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
      • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
    Incoming kerberos credentials No properties required. Considers the incoming kerberos credentials.
    For Authentication type NTLM, authenticate using any of the following:
    Custom credentials Specifies the credentials that are required for the NTLM handshake.

    Provide the following information:

    • Username. Name of a consumer who is available in the Integration Server on which API Gateway is running.
    • Password. A valid password of the consumer.
    • Domain. The domain used by the server to authenticate the consumer.
    Incoming HTTP basic auth credentials No properties required. Considers the incoming HTTP basic authentication credentials.
    Transparent No properties required.
    For the Authentication type OAuth2, authenticate using any of the following:
    Custom credentials Specifies the OAuth2 token value that would be added as bearer token in the transport header while accessing the native API.
    Incoming OAuth token Considers the incoming OAuth token to access the native API.
    For Authentication type JWT, authenticate using any of the following:
    Incoming JWT Considers the incoming JSON web token to access the native API.
  5. Specify a stage, if you want the alias to be applicable to a specific stage.

  6. Click Save.

Creating a SOAP Message Security Alias

You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

A SOAP message security alias contains message level security information that is requires to access the native API. If the native service is enforced with any WS security policy, API Gateway enforces those policies in the outbound request while accessing the native API using the configuration parameters specified in the alias.

To create SOAP message secure alias

  1. Expand the menu options icon icon, in the title bar, and select Aliases.

  2. Click Create alias.

  3. In the Basic information section, provide the following information:

    Field Description
    Name Name of the alias.
    Type Select SOAP message secure alias.
    Description Description of the alias.
  4. Click Technical information and provide the following information:

    Field Description
    Authentication scheme Specify the type of authentication scheme you want to use to authenticate the client.

    Available values are:

    • None. Does not use any authentication types to authenticate the client.
    • WSS Username. Generates a WSS username token and sends it in the soap header to the native API.
    • Kerberos. Fetches a Kerberos token and sends it to the native API.
    • SAML. Fetches a SAML token and sends it to the native API.
    For Authentication scheme None. Does not require any properties.
    For Authentication type WSS Username, authenticate using any of the following:
    Custom credentials Specifies the values provided in the policy to be used to obtain the WSS username token to access the native API.
    Provide the following information:
    • Username. Specifies a username used to generate the WSS username token.
    • Password. Specifies the password used to generate the WSS username token.
    For Authentication type Kerberos, authenticate using any of the following:
    Custom Credentials Uses the Basic authentication credentials coming in the transport header of the incoming request for client principal and client password.
    Provide the following information:
    • Client principal. A valid client LDAP user name.
    • Client password. A valid password of the client LDAP user.
    • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
      • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
      • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
    Delegate incoming credentials Specifies the values provided in the policy to be used by the API providers to select whether to delegate the incoming Kerberos token or act as a normal client.

    Provide the following information:

    • Client principal. A valid client LDAP user name.
    • Client password. A valid password of the client LDAP user.
    • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.
    • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Available values are:
      • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
      • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
    Incoming HTTP basic auth credentials Specifies the incoming HTTP basic authentication credentials to access the native API.

    Provide the following information:

    • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:
      • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.
      • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
    For Authentication type SAML
    SAML issuer configuration Specifies the SAML issuer configuration that is used by the API Gateway to fetch the SAML token which is then added in the SOAP header and sent to the native API.

    This field is visible and required only if you have configured a SAML issuer in Administration > Security > SAML issuer section.

    Signing configurations
    Keystore alias Specify the keystore that needs to be used by API Gateway while sending the request to the native API. A keystore is a repository of private key and its corresponding public certificate.
    Key alias The key alias is the private key that is used sign the request sent to the native API.
    Encryption configurations
    Truststore alias Select the truststore to be used by API Gateway when sending the request to the native API. Truststore is a repository that holds all the trusted public certificates.
    Certificate alias Select the certificate from the truststore that is used to encrypt the request that is sent to the native API.
    Stage Specify a stage, if you want the alias to be applicable to a specific stage.
  5. Click Save.

Creating a webMethods Integration Server Service Alias

You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

A webMethods Integration Server service alias holds the IS service value. The name of the alias can be used to invoke the Invoke webMethods IS policy for request and response processing.

To create a webMethods IS service alias

  1. Expand the menu options icon icon, in the title bar, and select User management.

  2. Click Create alias.

  3. In the Basic information section, provide the following information:

    Field Description
    Name Name of the alias.
    Type Select webMethods IS Service alias.
    Description Description of the alias.
  4. Click Technical information and provide the following information.

    Field Description
    Service name Specify the IS service name.
    Note: The IS service must be available in the Integration Server, to which the aliases are deployed.
    Comply to IS Spec (pub.apigateway.invokeISService.specifications) Select Comply to IS Spec, if you want the input and output parameters to comply to the IS Spec specified.
    Stage Specify a stage, if you want the alias to be applicable to a specific stage.
  5. Click Save.

Creating an XSLT Transformation Alias

You must have the API Gateway’s manage aliases functional privilege assigned to perform this task.

An XSLT transformation alias holds a list of XSLT style sheets. The name of the alias can be used in the XSLT Transformation policies for request and response processing.

To create a transformation alias

  1. Expand the menu options icon icon, in the title bar, and select User management.

  2. Click Create alias.

  3. In the Basic information section, provide the following information:

    Field Description
    Name Name of the alias.
    Type Select XSLT Transformation alias.
    Description Description of the alias.
  4. Click Technical information and browse and select an XSLT style sheet in the Select transformation file field.

  5. Specify a stage, if you want the alias to be applicable to a specific stage.

  6. Click Save.