Configure API Gateway policy

This section describes how to configure API Gateway for unconstrained credential delegation using Policy Studio. For more information on working in Policy Studio, see the API Gateway Policy Developer Guide.

Configure an intermediary Kerberos service

  1. In the node tree, click Environment Configuration > External Connections > Kerberos Services.
  2. Click Add a Kerberos Service, and enter a name for your Kerberos service (IntermediaryGateway Kerberos Service for Unconstrained Delegation).
  3. On the Kerberos Endpoint tab, set the following:
    • Kerberos Principal: IntermediaryGateway.
    • Enter Password: Enter the password for IntermediaryGateway@AXWAY.COM.
    • Enabled: Select this option.
  4. On the Advanced tab, set the following:
    • Mechanism: SPNEGO_MECHANISM.
    • Extract delegated credentials: Select this option.
Note   Selecting Extract delegated credentials means that API Gateway extracts the Kerberos client’s TGT from the SPNEGO token after the client has been authenticated. API Gateway can then use the TGT to request service tickets to other Kerberos services on behalf of the Kerberos client.

For more details on the fields and options in this configuration window, see Configure Kerberos services in the API Gateway Policy Developer Guide.

Configure a Kerberos client for the delegated credentials

To authenticate to the back-end Kerberos services, API Gateway loads the credentials it extracted from the end user to a Kerberos client of its own.

  1. In the node tree, click Environment Configuration > External Connections > Kerberos Clients.
  2. Click Add a Kerberos Client, and enter a name for your client (Kerberos Client for Unconstrained Delegation).
  3. On the Kerberos Endpoint tab, set the following:
    • Load from delegated credentials: Select this option.
    • Enabled: Make sure this option is selected.
  4. On the Advanced tab, set the following:
    • Mechanism: SPNEGO_MECHANISM.
    • Context Settings: Select the following options:
      • Mutual authentication
      • Integrity
      • Confidentiality
      • Anonymity
      • Replay Detection
      • Sequence Checking
    • Synchronize to Avoid Replay Errors at Service: Deselect this option to improve performance.
    • Refresh when remaining validity is <value> seconds: Set to 300.

For more details on the fields and options in this configuration window, see Configure Kerberos clients in the API Gateway Policy Developer Guide.

Configure a Kerberos profile for the intermediary Kerberos service

  1. In the node tree, click Environment Configuration > External Connections > Client Credentials > Kerberos.
  2. Add a Kerberos profile as follows:
    • Profile Name: Authenticate to Back-End Service using Delegated Credentials.
    • Kerberos Client: Kerberos Client for Unconstrained Delegation.
    • Kerberos Service Principal: <Back-end Kerberos Service>.
    • Send token with first request: Select this option.

For more details on the fields and options in this configuration window, see Configure Kerberos client credential profiles in the API Gateway Policy Developer Guide.

Configure an intermediary policy

The following section describes how to configure the policy for API Gateway delegating the credentials.

To start, add a new policy named, for example, Kerberos Intermediary for Unconstrained Credentials Delegation.

Configure a Kerberos service filter

  1. Open the Authentication category in the filter palette, and drag a Kerberos Service filter onto the policy canvas.
  2. Set Kerberos Service to the intermediary Kerberos service you created (IntermediaryGateway Kerberos Service for Unconstrained Delegation).
  3. Change Kerberos Standard to SPNEGO Over HTTP, and click Finish.
  4. Right-click the Kerberos Service filter, and select Set as Start.

For more details on the fields and options in this configuration window, see Kerberos service authentication in the API Gateway Policy Developer Filter Reference.

Configure retrieving the end user credentials

  1. Open the Attributes category in the palette, and drag a Retrieve from HTTP Header filter onto the policy canvas.
  2. Set the HTTP Header name to WWW-Authenticate and Attribute ID to outer.www.authenticate, and click Finish.
    For more details on the fields and options in this configuration window, see Retrieve attribute from HTTP header in the API Gateway Policy Developer Filter Reference.
  3. Open the Conversion category in the palette, drag a Remove HTTP Header filter onto the policy canvas.
  4. Set HTTP Header Name to WWW-Authenticate.

Configure authentication to the back-end service

  1. Open the Routing category in the palette, and drag a Connect to URL filter onto the canvas.
  2. Enter the URL used to invoke the back-end Kerberos service.
  3. On the Authentication tab, select the Kerberos profile you configured (Authenticate to Back-End Service using Delegated Credentials), and click Finish.
    For more details on the fields and options in this configuration window, see Connect to URL in the API Gateway Policy Developer Filter Reference.
  4. Open the Conversion category in the palette, and drag an Add HTTP Header filter onto the policy canvas.
  5. Set the following, and click Finish:
    • HTTP Header Name: WWW-Authenticate.
    • HTTP Header Value: ${outer.www.authenticate}.
    • Override existing header: Select this option.
    • Add header to HTTP headers attribute: Select this option.

    For more details on the fields and options in this configuration window, see Add HTTP header in the API Gateway Policy Developer Filter Reference.

  6. Open the Utility category in the palette, and drag a Reflect Message filter onto the canvas.

Build the policy

  1. Click on the Add Relative Path icon to create a new relative path /intermediary that links to this policy.
  2. Connect the filters with success paths.
  3. Intermediary policy filters

The policy has the following flow:

  • API Gateway receives a request from the end user, and uses the Kerberos token in the Authorization HTTP header to authenticate the end user.
  • API Gateway extracts the value of the WWW-Authenticate HTTP header and saves the value to a message attribute, so it can be reinstated later. This token is the response to the original token the end user sent.
  • API Gateway retrieves a service ticket for the end user to access the back-end Kerberos service, connects to the back-end Kerberos service, and authenticates using the Kerberos credentials relating to the original end user.
  • API Gateway reinstates the value of the WWW-Authenticate HTTP Header, overriding the value the back-end Kerberos service set.
  • API Gateway sends the response to the Kerberos client.

Configure Kerberos system settings

  1. In the node tree, click Environment Configuration > Server Settings > Security > Kerberos, and click Add Kerberos Configuration.
  2. On the krb5.conf tab, add the Kerberos settings as follows:
  3. [libdefaults]

    default_realm = AXWAY.COM

     

    [realms]

    AXWAY.COM = {

    kdc = dc.axway.com

    }

    Replace the realm settings in the example code with your Kerberos realm, and set the kdc setting to the host name of your Windows Domain Controller.

For more details on the fields and options in this configuration window, see Kerberos configuration in the API Gateway Policy Developer Guide.

Deploy the configuration

To deploy the configuration to API Gateway, click the Deploy icon.

You have now configured and deployed a policy for the authenticating Kerberos service on API Gateway that delegates the SPNEGO credentials to the back-end Kerberos service. The client application calls the policy on relative path /intermediary.

For demonstration purposes, you may want to add API Gateway as the client application and the back-end service. For example configurations, see Demo setup: API Gateway as both Kerberos client and service. When configuring API Gateway as the client application for credentials delegation, the setting forwardable on the krb5.conf tab in the Kerberos system settings must be true:

  • [libdefaults]

    default_realm = AXWAY.COM

    forwardable=true

     

    [realms]

    AXWAY.COM = {

    kdc = dc.axway.com

    }

  • For a list of other use cases covered in this guide, see Kerberos use cases.

    Test the configuration

    Use a client application to call the policy in API Gateway.

    The back-end Kerberos service should send a confirmation on a successful authentication.

    The Traffic Monitor tab on the API Gateway Manager (https://localhost:8090) is an excellent place to view and troubleshoot the message flows. For more details, see Monitor services in API Gateway Manager in the API Gateway Administrator Guide.

    Related Links