ExceptionFactory

Producing content that a reasonable developer might want to read

Integrating Apache NiFi with Okta LDAP Groups

NiFi Security Okta LDAP

2023-01-26 • 8 minute read • David Handermann

Introduction

Apache NiFi supports a number of configurable solutions for user authentication and multi-tenant authorization. Lightweight Directory Access Protocol provides a standard storage and communication architecture for user and group information, enabling an LDAP server to support both authentication and authorization. Using different extension points, NiFi decouples authentication and authorization settings, which supports integrating single sign-on authentication together with authorization based on LDAP group membership. The Okta identity platform provides single sign-on using either OpenID Connect or SAML, and also supports access to user and group information through an LDAP interface. Configuring the NiFi User Group Provider for Okta LDAP extends single sign-on integration and simplifies access policies using centralized group membership.

Prerequisites

The Okta Developer Edition provides free access to Okta services for a small number of users. Okta integrates with GitHub authentication, which simplifies the initial registration process.

NiFi should be configured with Okta single sign-on using SAML or OIDC prior to configuring LDAP.

Okta Domain

The Okta account domain is an essential element of both the authentication and authorization configuration. The Okta Developer Edition provisions a domain with a unique number, which serves as the central access point for Okta services. Okta Developer domains contain a unique identifier according to the following pattern:

dev-12345678.okta.com

Directory Configuration

LDAP access to Okta Directory information is an optional feature that must be enabled. Okta lists several LDAP interface known issues that should be reviewed. The Okta LDAP Interface connection settings provide a helpful listing of standard client configuration properties.

Limiting Directory Access

Okta requires an account with administrative permissions to access the LDAP interface. Although the account created during initial Developer Edition registration has the required permissions, creating a dedicated account with the Read-only Administrator role provides better security.

A dedicated account with limited permissions can be created using the Okta Admin Console under the Directory section.

The following instructions describe creating a Directory Manager user, but alternative naming can be used based on operational requirements. The Username must be formatted as an email address. The account can be created without email address verification, but a valid address is necessary for account recovery. The following instructions use manager@localhost.local as the username and email address.

  1. Open the Okta Admin Console
  2. Expand the Directory section and press People
  3. Press Add person
  4. Enter Directory for the First name field
  5. Enter Manager for the Last name field
  6. Enter manager@localhost.local for the Username field
  7. The Primary email field will be populated from the Username field
  8. Select I will set password and enter a password
  9. Deselect User must change password on first login
  10. Press Save to create the user
  11. Select the created account to change additional settings
  12. Press the Admin roles tab
  13. Press Edit individual assignments
  14. Select Read-only Administrator for the Role field
  15. Press Save Changes

The username and password will provide access to the LDAP interface.

Enabling LDAP Access

Access to Okta user and group information requires enabling the LDAP interface under Okta Directory Integrations.

  1. Open the Okta Admin Console
  2. Expand the Directory section and press Directory Integrations
  3. Press Add LDAP Interface

Adding the LDAP Interface sets the default status to Active. The Settings section displays the information necessary to read information from the LDAP server.

The registered Okta domain is present in both the LDAP Host field and the first domain component of the Base DN field.

Okta uses the standard registered TCP port of 636 for LDAP with TLS, which Okta recommends for optimal security.

The values of the Host field, User base DN field, and Group base DN field are necessary for configuring the NiFi LDAP User Group Provider.

Authorizer Configuration

As part of configuring single sign-on authentication, the Managed Authorizer should be specified in the nifi.properties configuration. The Managed Authorizer brings together access policies with user and group information.

Confirm that the User Authorizer is set to the Managed Authorizer.

nifi.security.user.authorizer=managed-authorizer

User Group Provider Configuration

The standard NiFi distribution includes an authorizers.xml configuration with a commented example of the LdapUserGroupProvider definition. Configuring the provider to read from Okta LDAP requires setting several properties and referencing the identifier in the Access Policy Provider.

Okta uses X.509 certificates issued from standard authorities, so it is not necessary to configure custom TLS properties in the LDAP provider. Enabling TLS access uses the certificate authorities provided with the Java distribution.

The instructions use the following Okta settings that must be adjusted based on the account registration.

Account Domain Properties

The following NiFi LDAP User Group Provider properties are specific to the registered Okta domain and will be different based on account settings:

Standard Provider Properties

Configure the LDAP User Group Provider using settings defined for the LDAP Interface in the Okta Dashboard.

Properties shown provide required values and recommendations.

Properties not listed can be omitted or left blank as provided in the default configuration.

<userGroupProvider>
  <identifier>ldap-user-group-provider</identifier>
  <class>org.apache.nifi.ldap.tenants.LdapUserGroupProvider</class>
  
  <property name="Manager DN">uid=manager@localhost.local, ou=users, dc=dev-12345678, dc=okta, dc=com</property>
  <property name="Manager Password">PASSWORD</property>
  
  <property name="Authentication Strategy">LDAPS</property>
  <property name="Url">ldaps://dev-12345678.ldap.okta.com</property>
  
  <property name="Referral Strategy">FOLLOW</property>
  <property name="Connect Timeout">10 secs</property>
  <property name="Read Timeout">10 secs</property>
    
  <property name="Page Size">1000</property>
  <property name="Sync Interval">30 mins</property>

  <property name="User Search Base">ou=users, dc=dev-12345678, dc=okta, dc=com</property>
  <property name="User Object Class">inetOrgPerson</property>
  <property name="User Search Scope">ONE_LEVEL</property>
  <property name="User Identity Attribute">uid</property>

  <property name="Group Search Base">ou=groups, dc=dev-12345678, dc=okta, dc=com</property>
  <property name="Group Object Class">groupofUniqueNames</property>
  <property name="Group Search Scope">ONE_LEVEL</property>
  <property name="Group Name Attribute">cn</property>
  <property name="Group Member Attribute">uniqueMember</property>
  <property name="Group Membership - Enforce Case Sensitivity">false</property>
</userGroupProvider>

Provider Property Description

The identifier and class elements use the default values from the standard NiFi distribution.

The Manager DN property starts with the uid field and the username of the Okta account with administrative access. Each element should be separated with a space and a comma character. The dc=dev-12345678 component should reflect the Okta account domain.

The Authentication Strategy property should be set to LDAPS to enable TLS communication for the connection. The Url property should start with ldaps to enable TLS connections using the standard TCP port 636.

The Referral Strategy defaults to FOLLOW to enable potential references to other directory elements.

The Connect Timeout and Read Timeout settings default to 10 secs, which should be sufficient for standard network communications.

The Page Size property should be set to 1000 to align with Okta maximum supported results.

The Sync Interval property defaults to 30 mins, which controls how often the NiFi Provider queries Okta LDAP for updates.

The User Search Base property should be configured with the value of User base DN from the Okta LDAP Interface Settings. The User Object Class should be set to inetOrgPerson to match the specific schema of user objects within Okta LDAP. The default ONE_LEVEL setting for User Search Scope avoids unnecessary recursive lookups. The User Identity Attribute should specified as uid to use the Okta username field.

The Group Search Base property should be configured with the value of Group base DN from the Okta LDAP Interface Settings. The Group Object Class must be set to groupofUniqueNames in order to find group objects in the directory. The Group Search Scope should be set to ONE_LEVEL following the same setting as the User Search Scope property. The Group Name Attribute must be set to cn to use the common name field as the name for each group. The Group Member Attribute must be set to uniqueMember for the NiFi Provider to enumerate members of each group.

The Group Member - Enforce Case Sensitivity property controls the strictness that the NiFi Provider applies to group membership matching. This setting should be false unless different group names share the same wording with different uppercase and lowercase characters.

Access Policy Provider Configuration

The LDAP User Group Provider must be linked to the Access Policy Provider for the Managed Authorizer to use LDAP information.

The Access Policy Provider property named User Group Provider must be updated using the value of the identifier element from the LDAP User Group Provider. The default value for the LDAP Provider identifier is ldap-user-group-provider. The Initial Admin Identity property should be defined with the Okta username created during account registration. The following example uses administrator@localhost.local as the initial admin identity.

<accessPolicyProvider>
  <identifier>file-access-policy-provider</identifier>
  <class>org.apache.nifi.authorization.FileAccessPolicyProvider</class>
  <property name="User Group Provider">ldap-user-group-provider</property>
  <property name="Authorizations File">./conf/authorizations.xml</property>
  <property name="Initial Admin Identity">administrator@localhost.local</property>
</accessPolicyProvider>

Troubleshooting

The LDAP User Group Provider includes a number of properties that must be configured properly for successful operation.

Some errors provide clearer messages than others. Okta maintains a list of error codes and descriptions, which is a helpful reference for troubleshooting some problems.

Authentication Failures

An incorrect Manager DN or Manager Password results in an extended stack trace with java.naming.AuthenticationException as the root cause. The error message associated with the AuthenticationException includes both the LDAP error code and the Okta error code.

[LDAP: error code 49 - Authentication failed : (Refer to Okta error Code E0000004)]

Communication Failures

An incorrect Url results in a java.naming.CommunicationsException with different types of root causes. Network connection failures can throw a java.net.SocketTimeoutException when the LDAP User Group Provider is unable to connect to the Okta LDAP server within the configured Connect Timeout duration.

An incorrect Url can also result in a java.net.UnknownHostException when the LDAP User Group Provider fails to resolve the DNS address of the Okta LDAP server.

Group Membership Debugging

The NiFi user interface displays group membership information under the Users section. Debug logging can be enabled for the LDAP User Group Provider to observe the results of user and group searches.

The Logback configuration in logback.xml can be updated with an additional logger element to enable search debugging.

<logger name="org.apache.nifi.ldap" level="DEBUG" />

Debug log messages from LdapUserGroupProvider contain both the names and identifiers of user and group information.

Conclusion

The Okta LDAP Interface extends centralized access management from single sign-on authentication to group-based authorization for Apache NiFi. The LDAP User Group Provider supports a number of configurable properties, and additional settings can be used to filter available groups. With support for encrypted communication using TLS, and accounts with limited permissions, connections between NiFi and Okta incorporate strong security characteristics. Following successful configuration, NiFi with Okta single sign-on and LDAP provides a reliable solution for centralized access control.