Configure a user account in Active Directory

This section describes how to configure a Kerberos service principal for API Gateway in Active Directory acting as the Key Distribution Centre (KDC).

Configure a user account for API Gateway

  1. On the Windows Domain Controller, click Control panel > Administrative Tools > Active Directory User and Computers.
  2. Right-click Users, and select New > User.
  3. Enter the host name of the machine running API Gateway in the First Name and User Logon Name fields. For example, if the host name is gateway.axway.com, enter gateway.
  4. Click Next.
  5. Enter the password, and do the following:
    • User must change password at next logon: Deselect this.
    • User cannot change password: Select this.
    • Password never expires: Select this.

    This ensures that a working API Gateway configuration does not stop working when a user chooses, or is prompted to change their password. API Gateway does not track these actions.

    If these options are not suitable in your implementation and a user password changes in Active Directory, you must then update the password or keytab of the Kerberos client or service related to the user in Policy Studio, and redeploy the configuration to API Gateway.
    If you cannot deselect User must change password at next logon, ensure the user changes the password and that the new password or keytab is deployed to API Gateway before API Gateway attempts to connect as this user.

  6. Tip   You can store Kerberos passwords in a KPS table to update a changed password in runtime. For more details, see Use KPS to store passwords for Kerberos authentication.
  7. Click Next > Finish.
  8. Right-click the new user gateway, and select Properties.
  9. On the Account tab, select Use DES encryption types for this account.
  10. Click Apply > OK.

As a Kerberos service, API Gateway authenticates the client application using Kerberos authentication. For the authentication to succeed, the client application must have an account configured in your Active Directory. For an example configuration, see Configure a user account in Active Directory.

Map an SPN to the user account

You must map a Service Principal Name (SPN) to the user account you created (gateway@AXWAY.COM).

  1. On the Windows Domain Controller, open a command prompt.
  2. Enter the following ktpass command:
  3. > ktpass -princ HTTP/<host>@<Kerberos realm> -mapuser <user> -pass password -out <user>.keytab -crypto rc4-hmac-nt -kvno 0

    The SPN is of the format HTTP/<host>@<Kerberos realm>, where <host> is the name of the host running the Kerberos service, gateway.axway.com in this case:

    > ktpass –princ HTTP/gateway.axway.com@AXWAY.COM –mapuser gateway –pass Axway123 –out gateway.keytab –crypto des-cbc-md5 –kvno 0

    Replace gateway.axway.com with the full host name your browser will use when connecting to API Gateway.
    Replace AXWAY.COM with your Kerberos realm name. Note that the realm name should be uppercase.

This command creates an SPN HTTP/gateway.axway.com@AXWAY.COM, which is mapped to the user account (gateway).

The command also creates a keytab file for the account that you can use later when configuring the Kerberos service in Policy Studio. See Configure Kerberos principal.

Tip   If you do not want to create a keytab file, you can use the following command:
> setspn -A HTTP/<host> <user>

If you view the user properties, you see that the user logon name has changed.

DNS considerations

A web browser is the most likely client application authenticating to API Gateway acting as the Kerberos service.

When a browser requests a service ticket from the Kerberos KDC, the browser presents the SPN for the service it wants to connect to. The SPN is based on the host name in the URL entered in the browser.

For example, if the user enters http://gateway.axway.com:8080/kerberos, the SPN that the browser passes to the Kerberos KDC to acquire a service ticket is HTTP/gateway.axway.com@AXWAY.COM.

If the host name is defined in the DNS as a host (A-name), the SPN is directly resolved from the host:

  • The DNS server has the following DNS record defined:
  • HOST(A): gateway.axway.com
  • The following URL is entered in the client browser:
  • URL: http://gateway.axway.com:8080/kerberos
  • The requested SPN is:
  • HTTP/gateway.axway.com

If DNS aliases (C-names) are used as host names, the SPN is resolved by mapping the C-name to a DNS A-name:

  • The DNS server has the following records defined:
  • HOST(A): gateway.axway.com
  • Alias (CNAME): test -> gateway.axway.com
  • The following URL is entered in the client browser:
  • URL: http://test.axway.com:8080/kerberos
  • The requested SPN is:
  • HTTP/gateway.axway.com

If all host names are defined as hosts (A-names) in the DNS, you must map separate SPNs for the hosts to the user account you configured.

If the DNS uses aliases (C-names), it is not necessary to map additional SPNs.

Map additional SPNs to the user account

You can map more than one SPN to a user account, if many browser users need to refer to the API Gateway machine using different host names, for example, http://gateway.axway.com:8080/kerberos and http://test.axway.com:8080/kerberos.

  1. To map additional SPNs to the user account, enter the following command:
  2. > setspn -A HTTP/test.com gateway
  3. The output looks like this:
    Registering ServicePrincipalNames for CN=gateway,CN=Users,DC=axway,DC=com
    HTTP/test.axway.com
    Updated object
  4. To list the SPNs mapped to a user account, enter the following command:
  5. > setspn –L gateway
  6. The output looks like this:
    Registered ServicePrincipalNames for CN=gateway,CN=Users,DC=axway,DC=com:
    HTTP/test.axway.com
    HTTP/gateway.axway.com

Related Links