Add a Kerberos App

Overview

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

Kerberos Architecture

Implementing Kerberos applications involves the following:

  • Okta Tenant - providing 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 instance(s) - protected applications.


Kerberos end user access patterns include:

Kerberos Application Access Patterns

Where:

  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

  • 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 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.
  • Access Gateway DNS must be served by the Windows DNS server.
Important Note

Important

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 idaasgateway.net is selected.
  4. Click Action > New Host (A or AAAA).
  5. Enter appropriate values for Name, FQDN 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 account.

  1. Return to or sign in to your Windows Server.
  2. Start the the Active Directory Users and Computers application.
  3. Select <gateway instance> > 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.
    Ensure that User cannot change password and
    Password never expires are checked, then click Next.
  6. On the final New Object - User dialog click Next.
  7. Right click the new user and show properties and note the following properties:
    Logon name: oag@idaasgateway.net
    Pre windows 2000 prefix: IDAASGAWAY

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. Navigate to your Access Gateway Instance.

  2. In the Access Gateway Admin UI sign in as administrator.
  3. Select the Settings tab.
  4. Select the Kerberos pane.
  5. Click plus().
  6. Enter the Service Account details previously noted.
  7. Expand the Windows Server commands section.
    This section contains the commands that must be executed on the Windows server to create the required keytab.
  8. 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/gw-iss.idaasgateway.net IDAASGATEWAY\oag
      checking DC=isaasgateway, DC=net
      Registering ServicePrincipleNames for cn=oag service, CN=Users,DC=idaasgateway,DC=net host/gw-iss.idaasgateway.net Updated object
      c:\>
    5. Execute the ktpass command, for example:
      c:\> ktpass /princ host/gw-idiaasgateway.net@IDAASGATEWAY.NET /mapuser oag@idaasgateway.net /out c:\oag.keytab /rndPass /pType KRB5_NT_PRINCIPAL /crypto All
      Targeting domain controller:
      . . . 
      Key created
      Output keytab to oag.keytab:
      . . . 
      c:\> 

      Info

      Note

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

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

Configure Windows Server IIS for Constrained Delegation

  1. Return to or login 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 OAG user.
  8. Select the user, right click and choose properties
  9. Select the Delegation tab.
  10. Configure the account to: enable
    Trust this user for delegation to specified services only.
    Use any authentication protocol
    Then click Add.
  11. Add your IIS host to the delegation,
    Click Check Name to verify that server has joined to the domain.
    Click OK.
  12. In the Add Services dialog, select the delegation protocol, click OK

  13. Exit the Internet Information Services (IIS) application
  14. Validate the configuration.
    To test we will simulate a Kerberos sign in.
    1. Start the the Active Directory Users and Computers application.
    2. Select <gateway instance> > Users > New User.
    3. Create a new Okta Access Gateway user and click Next.
      For example:
      First name: test
      Last name: user
      User logon name: testuser
    4. Complete the new user and exit the application
    5. Return to the Access Gateway admin 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 Gateway application to DNS
    1. Login or return to your Windows Server.
    2. Start the 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. Navigate to your Access Gateway Instance and sign in as admin.
  3. Click the Applications tab
    .Select applications tab
  4. Click + Add to add a new application.
    Click Add.
  5. Select Microsoft IIS IWA from the left column menu, and click Create.
    Info

    Note

    If the Microsoft IIS, OWA or Sharepoint IWA application are disabled (grey) confirm that there is a valid Kerberos service configured in settings.

  6. If required expand the Essentials pane, then enter:
    FieldValue
    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: https://iis.idaasgateway.net
    Protected Web ResourceFully qualified URL to the Microsoft backing application
    GroupThe group containing users who can access the application.
  7. Click Next
  8. In the Application pane, enter:
    FieldValue
    Kerberos RealmEnter the name of the associated realm
  9. Click Next.
  10. In the Attributes pane, enter:
    FieldValue
    iwa_usernameEnter the value of User Principle Name (UPN) in the proper case .
    Enter the domain name portion in upper case, for example: todd@ATKO.COM .
  11. Click Done

The application is added and the Application list page is displayed

Test the Application

  1. Select IDP Initiated from the drop down menu associated with the application.
    Test the application

  2. Verify that you are logged into application normally.

See Also