ExceptionFactory

Producing content that a reasonable developer might want to read

Integrating Apache NiFi with Okta SAML Authentication

NiFi Security Okta SAML

2022-11-30 • 9 minute read • David Handermann

Background

Security Assertion Markup Language provides an enterprise authentication solution using standard processing profiles with messages formatted according to XML schema definitions. The OASIS Open consortium maintains the official SAML 2.0 specification. The SAML standard defines separation of system roles between Identity Providers and Service Providers, where the SP delegates credential processing to the IdP. The IdP, known as the Asserting Party, is responsible for operations such as password verification, while the SP, known as the Relying Party, is responsible for validating IdP assertions and providing service resources. The SAML 2.0 Web Browser SSO Profile is the most common implementation, describing the message structure and HTTP operations required for authenticating a client user agent. Applications and services that support SAML 2.0 benefit from externalized authentication and access policies that can be managed from a central location.

Introduction

Apache NiFi supports a variety of user authentication strategies through an extensible provider framework. NiFi 1.13.0 added support for SAML 2.0 authentication with a number of configurable application properties for enabling single sign-on, group attribute mapping, and single logout processing. The Spring Security SAML extension library provided the foundation for the initial implementation, but the library is no longer supported as of October 2021. The Spring Security project incorporated SAML 2.0 support in version 5.7.0, which provides the basis for the NiFi implementation in version 1.17.0 and following.

Okta provides flexible identity management services using standard protocols that support integrating with a wide variety of products. Among its service offerings, Okta SAML supports integration with custom applications through basic configuration and advanced settings. The Okta Developer Portal contains extensive documentation for popular languages and frameworks, including a thorough review of SAML concepts and a guide for Spring Security SAML. These references offer helpful background for any SAML integration.

Prerequisites

Configuring Apache NiFi with Okta SAML authentication requires an Okta organization account, and an X.509 certificate with private key for Apache NiFi.

Apache NiFi 1.14.0 and following generate a self-signed X.509 certificate with private key for standalone deployments on initial startup, making it simple to get started with HTTPS access. The generated self-signed certificate is valid for 60 days.

Okta provides a free sign up for the Developer Edition of Okta services, enabling complete integration for a small number of users. Okta integrates with GitHub as one of several authentication providers, which provides a streamlined registration process.

Okta Registration

Registering for the Okta Developer Edition creates a unique domain, 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

NiFi Identification

NiFi does not need a public DNS address for SAML authentication, but it requires a stable hostname for web browser access. Using localhost is sufficient for testing, but a DNS address that is resolvable on the local network is required for standard deployments.

NiFi SAML integration also requires a Service Provider Entity Identifier, which is the element of shared SAML metadata that uniquely identifies the NiFi installation. The SP Entity ID must be a valid Uniform Resource Identifier but it does not need to be a resolvable location.

A stable public URL associated with the NiFi deployment is the best approach. In absence of a public URL, a Uniform Resource Name with a UUID provides an acceptable option. The following URN provides an example of a unique SP Entity ID based on a standard prefix and a random UUID:

urn:org:apache:nifi:sp:e41e8a05-fc9b-4f35-b31e-82221bb5c760

Login Configuration

Authenticating to Apache NiFi with Okta SAML requires registering a custom application in Okta and configuring NiFi with the SAML metadata and entity identifier properties.

The instructions are based on following settings that should be adjusted according to specific deployment environments:

Okta App Integration

Creating an Okta App Integration establishes the SAML 2.0 Identity Provider services necessary for NiFi authentication.

The Okta single sign on URL for SAML 2.0 is constructed from the NiFi Base URL and the login consumer path defined in NiFi SAML REST Resources.

  1. Open the Okta Admin Console
  2. Expand the Applications section and press Applications
  3. Press Create App Integration to begin the registration process
  4. Select SAML 2.0 as the Sign-in method and press Next
  5. Enter a name such as NiFi in the App name field and press Next
  6. Enter the Single sign on URL field as https://localhost:8443/nifi-api/access/saml/login/consumer
  7. Enter the Audience URI (SP Entity ID) field as urn:org:apache:nifi:sp:12345678
  8. Press Next to complete the Configure SAML section
  9. Select I’m an Okta customer adding an internal app and press Finish

The registered application is ready for access assignments and integration.

Application Assignments

Okta requires assigning registered applications in order to allow authenticated users to access the referenced Service Provider. Applications can be assigned to individual users or groups.

Assigning NiFi to the default Everyone group is sufficient for new Developer Edition configurations, but production deployments should use limited custom groups.

  1. Press the Assignments tab for the registered application
  2. Press the Assign button and press Assign to Groups
  3. Press Assign for the group named Everyone
  4. Press Done to save the assignments

Application Sign On

SAML authentication requires the Service Provider to verify login requests using the certificate from the Identity Provider. Okta provisions a signing certificate for use with SHA-2 hashing as part of application registration.

  1. Press the Sign On tab for the registered application
  2. Scroll to SAML Signing Certificates
  3. Press Actions for the row with SHA-2 Type and Active Status
  4. Press View IdP metadata to open the metadata URL
  5. Save the metadata URL for subsequent configuration

NiFi must be configured with the SAML metadata URL in order to load the certificate for request verification.

NiFi Application Settings

The standard NiFi distribution enables HTTPS access with Single User Authentication. Configuring SAML authentication requires disabling the Single User Login Provider, enabling the Managed Authorizer, and configuring SAML properties.

User Security Properties

The standard nifi.properties configuration requires several updates to user security properties.

Remove the User Login Identity Provider.

nifi.security.user.login.identity.provider=

Configure the User Authorizer with the Managed Authorizer.

nifi.security.user.authorizer=managed-authorizer

Configure the Okta IdP metadata URL copied from the browser link opened from the Application Sign On section.

nifi.security.user.saml.idp.metadata.url=https://dev-12345678.okta.com/app/{id}/ssl/saml/metadata

Configure the Service Provider Entity Identifier entered during the App Integration process.

nifi.security.user.saml.sp.entity.id=urn:org:apache:nifi:sp:12345678

Authentication Expiration

The NiFi SAML configuration supports an additional configuration property for controlling the lifespan of authenticated sessions. NiFi returns a signed JSON Web Token after successful SAML authentication, and the authentication expiration property controls the length of time before the token expires. The default setting is 12 hours, which can be reduced to require more frequent authentication with the SAML IdP.

nifi.security.user.saml.authentication.expiration=2 hours

Authorizer Configuration

New deployments of NiFi require configuring an initial user to manage application policies.

NiFi supports custom identity mapping to transform usernames, but the most straightforward configuration involves matching the NiFi initial user with the Okta username. The Okta username includes a domain of github.oktaidp for accounts registered through GitHub.

The standard authorizers.xml requires configuring an initial user identity in multiple locations.

Configure Initial User Identity 1 for the File User Group Provider section.

<userGroupProvider>
  <identifier>file-user-group-provider</identifier>
  <class>org.apache.nifi.authorization.FileUserGroupProvider</class>
  <property name="Users File">./conf/users.xml</property>
  <property name="Legacy Authorized Users File"></property>
  <property name="Initial User Identity 1">username@github.oktaidp</property>
</userGroupProvider>

Configure Initial Admin Identity for the File Access Policy Provider section.

<accessPolicyProvider>
  <identifier>file-access-policy-provider</identifier>
  <class>org.apache.nifi.authorization.FileAccessPolicyProvider</class>
  <property name="User Group Provider">file-user-group-provider</property>
  <property name="Authorizations File">./conf/authorizations.xml</property>
  <property name="Initial Admin Identity">username@github.oktaidp</property>
  <property name="Legacy Authorized Users File"></property>
  <property name="Node Identity 1"></property>
  <property name="Node Group"></property>
</accessPolicyProvider>

Initial Login

Configuring the SAML IdP Metadata URL instructs NiFi to redirect unauthenticated users to the Identity Provider for initial access. After starting NiFi and loading the application in a web browser, flow policies can be configured.

Group Configuration

Okta SAML and Apache NiFi support sending and receiving group membership information through SAML assertions. Okta passes group membership in configurable elements and NiFi translates specified assertions to user group membership.

Okta Application Settings

Enabling group membership requires modifying the Okta Application settings. The Group Attribute configuration supports filtering Okta group names based on several options, including regular expression patterns. Using a generalized pattern instructs Okta to pass all group memberships.

  1. Open the Okta Admin Console
  2. Expand the Applications section and press Applications
  3. Open the registered application
  4. Press the General tab to view settings
  5. Scroll to SAML Settings and press Edit
  6. Press Next to leave the General Settings unchanged
  7. Scroll to Group Attribute Statements
  8. Enter group in the Name field
  9. Select Basic in the Name format field
  10. Select Matches Regex in the Filter field
  11. Enter .* in the filter value field
  12. Press Next to complete the Configure SAML section
  13. Press Finish

NiFi Application Properties

Using Okta group membership requires configuring nifi.properties to read the configured SAML assertion for groups.

Configure the group attribute name as group in the specified SAML property.

nifi.security.user.saml.group.attribute.name=group

Okta group membership configured through the Okta Directory can be used for NiFi policies and permissions. NiFi groups must be defined with names matching Okta groups in order for NiFi to use SAML group membership for authorization.

Logout Configuration

The default NiFi configuration implements logout processing by removing the browser session cookie containing a signed JSON Web Token. This process does not require interacting with the SAML IdP. Local logout is sufficient for revoking the NiFi JWT, but it allows subsequent authentication without entering credentials, because the SAML IdP can retain single sign-on session information.

The SAML standard includes a Single Logout Profile, which enables a SAML Service Provider to initiate logout processing through the IdP. Both Okta and NiFi support Single Logout processing. NiFi must be configured with the Single Logout property enabled, and the Okta App Registration must be configured with the X.509 certificate corresponding to the private key that NiFi uses to sign Single Logout requests.

Okta Single Logout Settings

Okta requires uploading the X.509 certificate from NiFi to verify Single Logout request signatures. The standard NiFi installation generates a key pair and certificate on startup. The X.509 certificate must be extracted to a file for uploading to the Okta application configuration.

Certificate Extraction

The OpenSSL client command can be used to read the server certificate from a running installation.

openssl s_client -connect localhost:8443 < /dev/null | openssl x509 > nifi.crt

The command writes the X.509 certificate encoded in PEM format to a file named nifi.crt suitable for uploading.

Okta Application Single Logout Configuration

Enabling Single Logout requires uploading the server certificate and adjusting Okta Application settings.

  1. Open the Okta Admin Console
  2. Expand the Applications section and press Applications
  3. Open the registered application
  4. Press the General tab to view settings
  5. Scroll to SAML Settings and press Edit
  6. Press Next to leave the General Settings unchanged
  7. Press Show Advanced Settings to expand additional configuration
  8. Press Browse files… for the Signature Certificate field to upload the NiFi certificate
  9. Check the box for the Enable Single Logout field
  10. Enter the Single Logout URL field as https://localhost:8443/nifi-api/access/saml/single-logout/consumer
  11. Enter the SP Issuer field as urn:org:apache:nifi:sp:12345678
  12. Press Next to complete the Configure SAML section
  13. Select I’m an Okta customer adding an internal app and press Finish

NiFi Single Logout Settings

The default nifi.properties configuration requires enabling the Single Logout property.

nifi.security.user.saml.single.logout.enabled=true

The Okta application will accept SAML Single Logout requests after restarting NiFi and initiating the logout process.

Conclusion

NiFi SAML integration enables robust authentication handling using external identity providers. Delegated authentication processing supports additional security measures, such as multi-factor authentication and conditional access, depending on identity provider capabilities. Okta identity services with SAML 2.0 integration enable a number of use cases with straightforward configuration features. Deploying NiFi with Okta SAML authentication provides a reliable identity and access management solution.