Add a Kerberos app


The purpose of this tutorial is to step through the process of setting up a Kerberos application with Okta through theAccess Gateway Admin UI console.

Kerberos Architecture

Implementing Kerberos applications involves the following:

  • Okta tenant - Provides IDP
  • Okta Access Gateway - Uses constrained delegation to protect IIS/Kerberos applications.
  • Keytab - Allows Access Gateway to participate in constrained delegation using pairs of Kerberos principals and encrypted keys.
  • Microsoft Active Directory instance - Provides directory services.
  • Microsoft IIS Server instances - Protected applications.

Kerberos end user access patterns include:

Kerberos Application Access Patterns


  1. Users access the application using a tile within their Okta tenant.
  2. Users access the application using the external application proxy URL.


Before you begin

Ensure that:

  • Access Gateway is installed and configured for use.
    See Manage Access Gateway deployment.
  • Access Gateway has been configured to use your Okta tenant as IDP.
    See Configure your Okta tenant as an Identity Provider for more information about configuring your Okta tenant as an IDP.
  • You have administrator rights on your Okta tenant and can assign applications to users and create groups.
  • Window server configured with IIS application and Active Directory Services running as a Domain Controller and implementing Kerberos (IWA) SSO.
    Note this is an example architecture. It would be unusual in large production environments to have an application server (IIS), also be a DC.
  • Access Gateway DNS must be served by the Windows DNS server.
  • Confirm that the external app version is supported. Supported Kerberos app versions include:
    • Microsoft IIS IWA -iIS 7 or later
    • Microsoft OWA IWA - IIS 7 or later
Important Note


If Access Gateway is hosted within a customer environment, DNS changes can be made by using the command line management console. For example, select Static Networking(option 1), and define the Windows DNS IP and any other required values.
See the Network section in Access Gateway Command Line Management Console Reference for complete details.

Add Access Gateway to Windows DNS service

Windows must be the DNS provider for Access Gateway. Using Windows DNS manager you can perform common administrative tasks.
In this section we will add appropriate Windows DNS entries for Access Gateway instances.

  1. Sign in to your Windows server.
  2. Start the DNS Manager application.
  3. Select your domain.  
    In this example, is used as an example.
  4. Click Action > New Host (A or AAAA).
  5. Enter appropriate values for name (FQDN or fully qualified domain name) and IP address.
    For example:
    Name: gw-iis
    FQDN: gw-iis.access-gateway.tld
    IP Address: IP Address of Access Gateway instance.
  6. Click Add Host.
  7. Exit Windows DNS manager.

Configure Windows Access Gateway service account

Access Gateway requires a set of known Windows credentials, which will be used by the instance to configure the Kerberos service. We refer to this user as the OAG service or Access Gateway service account.

  1. Return to or sign in to your Windows server.
  2. Start the Active Directory Users and Computers application.
  3. Select the appropriate instance for Access Gateway, in this example, and then  Users > New User.
  4. Create a new Okta Access Gateway user and click Next.
    For example:
    First name: oag
    Last name: service
    User logon name: oag
  5. Specify an appropriate password.
  6. Ensure that User cannot change password and
    Password never expires check boxes are selected, then click Next.
  7. In the final New Object - User dialog box, click Next.
  8. Right click the new user and show properties and note the following properties:
    User logon name:
    Pre windows 2000 prefix: IDAASGATEWAY

Add Kerberos service to Access Gateway

In order to interact with Windows using Kerberos, a Kerberos configuration is required.
In this section, we will use the credentials created in the prior section to configure Kerberos settings.

  1. Sign into the Access Gateway Admin UI console.
  2. Select the Settings tab.
  3. Select the Kerberos pane.
  4. Click Add .
  5. Enter the service account details noted earlier.
  6. Expand the Windows Server Commands section.
    This section contains the commands that you must execute on the Windows server to create the required keytab.
  7. Execute the Windows server commands on the Windows domain controller to create the required keytab:
    1. Return to the Windows domain controller.
    2. Open a command prompt
    3. Change directory to the root using a command similar to:
      cd /
    4. Execute the setspn command, for example:
      c:\> setspn -s host/ IDAASGATEWAY\oag
      checking DC=isaasgateway, DC=net
      Registering ServicePrincipleNames for cn=oag service, CN=Users,DC=idaasgateway,DC=net host/ Updated object
    5. Execute the ktpass command, for example:
      c:\> ktpass /princ host/ /mapuser /out c:\oag.keytab /rndPass /pType KRB5_NT_PRINCIPAL /crypto All
      Targeting domain controller:
      . . . 
      Key created
      Output keytab to oag.keytab:
      . . . 



      The generated keytab file is required to finalize the Kerberos configuration in Access Gateway and must be accessible to Access Gateway.

  8. Return to Access Gateway.
  9. Expand the Configuration section.
  10. Click Choose File.
  11. Navigate to the directory containing the keytab file and upload
  12. Click Validate. The keytab file must be validated before continuing.
  13. Click Okay.

Configure Windows Server IIS for Constrained Delegation

  1. Return to or sign in to your Windows Server.
  2. Start theInternet Information Services (IIS) application.
  3. Navigate to the Default Web Site.
  4. Double-click Authentication. and configure:
    Anonymous access Disabled
    Windows Authentication Enabled
  5. Exit Internet Information Services (IIS).
  6. Start the Active Directory Users and Computers application.
  7. Navigate to the previously added Access Gateway service account user.
  8. Select the user, right-click and select properties.
  9. Select the Delegation tab.
  10. Select Trust this user for delegation to specified services only and enable Use any authentication protocol.
  11. Click Add.
  12. Add your IIS host to the delegation.
  13. Click Check Name to verify that server has joined to the domain.
  14. Click OK.
  15. In the Add Services dialog box, select the delegation protocol and click OK

  16. Exit the Internet Information Services (IIS) application
  17. Validate the configuration.
    To test, we will simulate a Kerberos sign in.
    1. Start the the Active Directory Users and Computers application.
    2. Select Access Gateway instance, in this example, and then > Users > New User.
    3. Create a new Okta Access Gatewayuser and click Next.
      For example:
      First name: test
      Last name: user
      User logon name: testuser
    4. Complete the new user.
    5. Return to the Access Gateway Admin UI console.
    6. Click the Simulate button.
    7. Enter test user and host. Specifically use the test user and the FQDN of the IIS server host, which is the same as the DC.

Create an IWA application in Access Gateway

  1. Add a public facing DNS entry for the Access Gatewayapplication to DNS.
    1. Sign in or return to your Windows server.
    2. Start the DNS Manager application.
    3. Click Action > New Host (A or AAAA).
    4. Add an entry that matches the Access Gateway instance.
      For example:
    5. Click Add Host and then exit the application.
  2. Sign in to the Access Gateway Admin UI console.
  3. Click the Applications tab.

  4. Click +Add to add a new application.

  5. Select Microsoft IIS IWA from the left column menu, and click Create.


    If the Microsoft IIS, OWA, or Sharepoint IWA applications are disabled, ensure that there is a valid Kerberos service configured in settings.

  6. If required, expand the Essentials pane and enter:
    LabelThe name of the application, as shown in your Okta Tenant.
    For example:Microsoft IIS Application
    Public DomainThe externally facing URL of the application.
    For example:
    Protected Web ResourceFully qualified URL to the Microsoft backing application.
    GroupThe group containing users who can access the application.
  7. Important Note


    While optional, Okta recommends that all applications include certificates.
    See About Access Gateway certificates for general information about certificate.
    See Certificate management tasks for a general task flow for obtaining and assigning certificates.  

  8. Expand the Certificates tab.


    By default a wild card self signed certificate is created and assigned to the application when the application is initially created.

  9. Optional. Click Generate self-signed certificate

    A self-signed certificate is created and automatically assigned to the application.
  10. Optional. Select an existing certificate from the list of provided certificates.
    Use the Search field to narrow the set of certificates by common name.
    Use the page forward (>)and backward(<) arrows to navigate through the list of available certificates.

  11. Click Next
  12. In the Application pane, enter:
    Kerberos RealmEnter the name of the associated realm
  13. Click Next.
  14. In the Attributes pane:
    1. Click Add attribute to add an attribute what corresponds to sAMAccountName.

    2. Enter the following values:

      Data Source



      IDP attribute that correlates with the users sAMAccountName



    3. Click Save.
  15. Click Done.

The application is added and the Application list page is displayed

Test the Application

  1. Select Goto Application > IDP Initiated.
    Test the application

  2. Verify that you are signed in to the application.

Related topics