ExceptionFactory

Producing content that a reasonable developer might want to read

Integrating Apache NiFi with Okta OIDC Authentication

NiFi Security Okta OIDC

2022-12-21 • 8 minute read • David Handermann

Background

OpenID Connect builds on the OAuth 2.0 standard to provide a codified approach to authentication and user identification. OAuth 2.0 consists of multiple specifications and extensions, defining features for exchanging credentials and granting access over HTTP. OIDC specifies a common JSON format for service discovery that allows integrating applications to interact with an Identity Provider, also known as an Authorization Server. Verified responses provide Access Tokens that allow clients to retrieve information from a protected Resource Server. OpenID Connect also mandates ID Tokens that include well-defined attributes describing the authenticated principal. The layers of standards and formats can be difficult to follow, but as an open specification with multiple extension points, OIDC has become a popular approach to interoperable identity and access management.

Introduction

Apache NiFi implements configurable authentication and authorization using a number of different strategies, including Kerberos, SAML, and mutual TLS, in addition to extensible Login Identity Providers. NiFi 1.4.0 introduced OpenID Connect authentication using configurable application properties to enable single sign-on and logout handling. The implementation leverages several Nimbus libraries from Connect2id to prepare OAuth 2.0 requests and process token information. NiFi 1.19.0 added group membership mapping from ID token claims to the OIDC implementation.

Okta supports authentication and access solutions using both open protocols and proprietary capabilities. Okta OpenID Connect enables integration with custom applications starting with simple settings and allowing advanced configuration. The Okta Developer Portal includes reference documentation for OpenID Connect and OAuth 2.0 services, covering supported request and response formats.

Both NiFi and Okta support SAML 2.0 as an alternative single sign-on solution. Integrating NiFi with Okta SAML Authentication describes the steps required for configuring SAML 2.0 authentication, as well as optional features. NiFi maintains support for both OIDC and SAML to enable integration with a wide array of access solutions. Although OIDC and SAML have similar fundamental features, they differ in both data exchange format and processing flow. NiFi operates in a similar manner with either protocol, but differences in session lifecycle management are worth noting. Understanding the configuration steps and supported features of both protocols provides a helpful basis for further comparison.

OpenID Connect Capabilities

NiFi operates as a confidential client as defined according to OAuth 2.0 RFC 6749 Section 2.1. Confidential clients interact with Identity Providers using protected credentials, such as a Client Identifier and Client Password. The NiFi OIDC integration approach fits into the web application client profile of OAuth 2.0, and the NiFi server does not transmit the access token to the web browser.

As a confidential client, NiFi supports the Authorization Code Grant type defined in RFC 6749 Section 4.1. This flow defines client-initiated authentication from a web browser, and requires the resource server to exchange an ephemeral authorization code for an access token. As the resource server, NiFi receives the authorization code through an HTTP redirect, which the Identity Provider initiates following successful authentication.

Following the OpenID Connect standard, NiFi receives both an access token and an ID token. The ID token provides the username and expiration claims that NiFi translates into a new JSON Web Token for subsequent application access.

Prerequisites

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

NiFi 1.14.0 introduced automatic certificate generation for standalone deployments on initial startup, enabling HTTPS in the default configuration. This certificate is suitable for testing, but must be replaced with a new certificate to avoid the default expiration of 60 days.

The Okta Developer Edition provides a free sign up for Okta services, enabling complete integration using standard features. Okta integrates with GitHub as one of several external authentication providers for streamlined account registration.

Okta Registration

Registering for the Okta Developer Edition creates a unique domain for accessing Okta services. Okta Developer domains consist of a unique identifier with the following pattern:

dev-12345678.okta.com

NiFi Addressing

NiFi requires a stable DNS address for OIDC application registration. The NiFi host address does not need to include a public domain, and the localhost address can be used for testing.

Login Configuration

Integrating Apache NiFi with Okta OIDC requires registering a custom application in Okta and configuring NiFi to access the OpenID Connect discovery information.

The configuration instructions are based on the following settings, which should be adjusted to match the details of specific deployments:

Okta App Integration

Registering an Okta App Integration enables OIDC Identity Provider services for NiFi authentication.

Okta requires defining sign-in and sign-out redirect URIs to ensure authentication security. These URIs must be defined using the NiFi Base URL and standard resources paths. The sign-in redirects must include paths for both login and logout callbacks to support successful operation. The sign-out redirect must define the application path that indicates the completion of the logout process.

  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 OIDC - OpenID Connect as the Sign-in method
  5. Select Web application as the Application type
  6. Press Next to load the registration fields
  7. Enter a name such as NiFi in the App integration name field
  8. The Authorization Code option is enabled as the default Grant type for access
  9. Enter a Sign-in redirect URI value of https://localhost:8443/nifi-api/access/oidc/callback
  10. Add a Sign-in redirect URI value of https://localhost:8443/nifi-api/access/oidc/logoutCallback
  11. Enter a Sign-out redirect URI value of https://localhost:8443/nifi-api/../nifi/logout-complete
  12. Select Limit access to selected groups for Controlled access
  13. Enter Everyone for Selected group(s)
  14. Press Save to complete the registration

The application is registered and ready for integration using the default Authorization Code flow.

Okta Client Credentials

The General tab of the registered Okta application includes a Client Credentials section that provides the Client ID and Client Secret required for access. The Client ID and Client Secret must be copied and provided in NiFi application properties.

The Okta OpenID Connect API documentation defines the OpenID discovery configuration URL based on the Okta organization domain. Okta follows OpenID Connect Discovery 1.0 Section 4.1 and provides the OpenID Connect configuration according to the following URL pattern:

https://${domain}.okta.com/.well-known/openid-configuration

NiFi Application Settings

Enabling OIDC authentication in NiFi requires disabling Login Identity Providers, including the Single User Login Provider present in the standard NiFi distribution. Additional steps include enabling the Managed Authorizer and configuring OIDC properties.

User Security Properties

The default nifi.properties requires several changes to enable OIDC authentication.

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 OIDC Configuration Discovery URL based on the registered Okta domain.

nifi.security.user.oidc.discovery.url=https://dev-12345678.okta.com/.well-known/openid-configuration

Configure the OIDC Client ID of the Okta registered application.

nifi.security.user.oidc.client.id=GENERATED_CLIENT_ID

Configure the OIDC Client Secret of the Okta registered application.

nifi.security.user.oidc.client.secret=GENERATED_CLIENT_SECRET

User Identification

The NiFi OIDC implementation defaults to identifying authenticated users using the email address defined in the email claim of the ID token.

NiFi can derive the username from other claims, such as preferred_username using an additional application property.

nifi.security.user.oidc.claim.identifying.user=preferred_username

Authorizer Configuration

NiFi requires an initial user to create application policies prior to configuring data flows.

The standard authorizers.xml requires configuring an initial user identity in the User Group Provider and Access Policy Provider. The following examples define username@apache.org as a placeholder email address, which must be replaced with the email address of the administrator user registered in Okta.

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@apache.org</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@apache.org</property>
  <property name="Legacy Authorized Users File"></property>
  <property name="Node Identity 1"></property>
  <property name="Node Group"></property>
</accessPolicyProvider>

Initial Login

Configuring the OIDC Discovery URL instructs NiFi to redirect unauthenticated users to the Identity Provider for access verification. The initial administrator identity can define NiFi policies following successful authentication.

Session Expiration

The NiFi OIDC implementation translates ID token claims to an internal JWT for application access after initial authentication. The implementation uses the expiration claim of the ID token to set the expiration of the application token. The Okta token lifetime documentation defines a hard-coded expiration of 60 minutes for ID tokens. This requires users to initiate a new NiFi session after one hour.

Okta supports refresh tokens for transparent access renewal, but NiFi 1.19.1 and earlier do not support the refresh token flow. RFC 6749 Section 1.5 defines refresh tokens as part of the standard OAuth 2.0 specification, which highlights this feature as an area for future improvement in NiFi OIDC integration.

Group Configuration

Apache NiFi 1.19.0 added support for retrieving group membership from an ID token claim. The default setting defines groups as the claim from which to read membership information. NiFi processes the claim as an array of string names and converts the names to NiFi groups for authorization.

NiFi Application Properties

The ID token group claim setting can be defined in nifi.properties as follows:

nifi.security.user.oidc.claim.groups=groups

This setting aligns with the default Okta ID token configuration and does not need to be changed.

NiFi groups must be defined with names matching Okta groups in order for NiFi to use membership for authorization.

Okta Application Settings

Okta provides straightforward instructions for customizing tokens with a groups claim through updates to a registered application. Providing a wildcard regular expression pattern configures Okta to send all groups of which the user is a member.

  1. Open the Okta Admin Console
  2. Expand the Applications section and press Applications
  3. Open the registered application
  4. Press the Sign On tab to view settings
  5. Scroll to OpenID Connect ID Token and press Edit
  6. Leave groups in the first field for Groups claim filter
  7. Select Matches regex in the second field
  8. Enter .* as the pattern in the third field
  9. Press Save

Subsequent authentications will now include Okta group membership information.

Conclusion

With initial setup requiring a small number of properties, the NiFi OIDC implementation enables rapid integration with standard access solutions. The Okta platform supports configurable policies that enable conditional access handling based on different credentials or environmental factors. Building on these capabilities enables strong security guarantees for NiFi access. Okta OpenID Connect integration provides robust authentication for NiFi installations using well-documented specifications.