mtien-apache commented on code in PR #7013: URL: https://github.com/apache/nifi/pull/7013#discussion_r1147898961
########## nifi-docs/src/main/asciidoc/administration-guide.adoc: ########## @@ -490,31 +490,81 @@ See also <<kerberos_service>> to allow single sign-on access via client Kerberos NOTE: For changes to _nifi.properties_ and _login-identity-providers.xml_ to take effect, NiFi needs to be restarted. If NiFi is clustered, configuration files must be the same on all nodes. [[openid_connect]] -=== OpenId Connect - -To enable authentication via OpenId Connect the following properties must be configured in _nifi.properties_. +=== OpenID Connect + +OpenID Connect integration provides single sign-on using a specified Authorization Server. +The implementation supports the Authorization Code Grant Type as described in +link:https://www.rfc-editor.org/rfc/rfc6749#section-4.1[RFC 6749 Section 4.1^] and +link:https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowSteps[OpenID Connect Core Section 3.1.1^]. + +After successful authentication with the Authorization Server, NiFi generates an application Bearer Token with an +expiration based on the OAuth2 Access Token expiration. NiFi stores authorized tokens using the local State +Provider and encrypts serialized information using the application Sensitive Properties Key. + +The implementation enables +link:https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout 1.0^] when the +Authorization Server includes an `end_session_endpoint` element in the OpenID Discovery configuration. + +OpenID Connect integration supports using Refresh Tokens as described in +link:https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens[OpenID Connect Core Section 12]. +NiFi tracks the expiration of the application Bearer Token and uses the stored Refresh Token to renew +access prior to Bearer Token expiration, based on the configured token refresh window. NiFi does not require OpenID +Connect Providers to support Refresh Tokens. When an OpenID Connect Provider does not return a Refresh Token, NiFi +requires the user to initiate a new session when the application Bearer Token expires. + +The Refresh Token implementation allows the NiFi session to continue as long as the Refresh Token is valid and the +user agent presents a valid Bearer Token. The default value for the token refresh window is 60 seconds. For an Access +Token with an expiration of one hour, NiFi will attempt to renew access using the Refresh Token when receiving an HTTP +request 59 minutes after authenticating the Access Token. Revoked Refresh Tokens or expired application Bearer Tokens +result in standard session timeout behavior, requiring the user to initiate a new session. + +The OpenID Connect implementation supports OAuth 2.0 Token Revocation as defined in +link:https://www.rfc-editor.org/rfc/rfc7009[RFC 7009^]. OpenID Connect Discovery configuration must include a +`revocation_endpoint` element that supports RFC 7009 standards. The application sends revocation requests for Refresh +Tokens when the authenticated Resource Owner initiates the logout process. + +The implementation includes a scheduled process for removing and revoking expired Refresh Tokens when the corresponding +Access Token has expired, indicating that the Resource Owner has terminated the application session. Scheduled session +termination occurs when the user closes the browser without initiating the logout process. The scheduled process avoids +extended storage of Refresh Tokens for users who are no longer interacting with the application. + +OpenID Connect integration supports the following settings in _nifi.properties_. [options="header"] |================================================================================================================================================== -| Property Name | Description -|`nifi.security.user.oidc.discovery.url` | The discovery URL for the desired OpenId Connect Provider (link:http://openid.net/specs/openid-connect-discovery-1_0.html[http://openid.net/specs/openid-connect-discovery-1_0.html^]). -|`nifi.security.user.oidc.connect.timeout` | Connect timeout when communicating with the OpenId Connect Provider. The default value is `5 secs`. -|`nifi.security.user.oidc.read.timeout` | Read timeout when communicating with the OpenId Connect Provider. The default value is `5 secs`. -|`nifi.security.user.oidc.client.id` | The client id for NiFi after registration with the OpenId Connect Provider. -|`nifi.security.user.oidc.client.secret` | The client secret for NiFi after registration with the OpenId Connect Provider. -|`nifi.security.user.oidc.preferred.jwsalgorithm` | The preferred algorithm for validating identity tokens. If this value is blank, it will default to `RS256` which is required to be supported -by the OpenId Connect Provider according to the specification. If this value is `HS256`, `HS384`, or `HS512`, NiFi will attempt to validate HMAC protected tokens using the specified client secret. +| Property Name | Description +|`nifi.security.user.oidc.discovery.url` | The link:http://openid.net/specs/openid-connect-discovery-1_0.html[Discovery Configuration URL^] for the OpenID Connect Provider +|`nifi.security.user.oidc.connect.timeout` | Socket Connect timeout when communicating with the OpenID Connect Provider. The default value is `5 secs` +|`nifi.security.user.oidc.read.timeout` | Socket Read timeout when communicating with the OpenID Connect Provider. The default value is `5 secs` +|`nifi.security.user.oidc.client.id` | The Client ID for NiFi registered with the OpenID Connect Provider +|`nifi.security.user.oidc.client.secret` | The Client Secret for NiFi registered with the OpenID Connect Provider +|`nifi.security.user.oidc.preferred.jwsalgorithm` | The preferred algorithm for validating identity tokens. If this value is blank, it will default to `RS256` which is required to be supported +by the OpenID Connect Provider according to the specification. If this value is `HS256`, `HS384`, or `HS512`, NiFi will attempt to validate HMAC protected tokens using the specified client secret. If this value is `none`, NiFi will attempt to validate unsecured/plain tokens. Other values for this algorithm will attempt to parse as an RSA or EC algorithm to be used in conjunction with the -JSON Web Key (JWK) provided through the jwks_uri in the metadata found at the discovery URL. -|`nifi.security.user.oidc.additional.scopes` | Comma separated scopes that are sent to OpenId Connect Provider in addition to `openid` and `email`. -|`nifi.security.user.oidc.claim.identifying.user` | Claim that identifies the user to be logged in; default is `email`. May need to be requested via the `nifi.security.user.oidc.additional.scopes` before usage. -|`nifi.security.user.oidc.fallback.claims.identifying.user` | Comma separated possible fallback claims used to identify the user in case `nifi.security.user.oidc.claim.identifying.user` claim is not present for the login user. -|`nifi.security.user.oidc.claim.groups` | Name of the ID token claim that contains an array of group names of which the +JSON Web Key (JWK) provided through the jwks_uri in the metadata found at the discovery URL +|`nifi.security.user.oidc.additional.scopes` | Comma separated scopes that are sent to OpenID Connect Provider in addition to `openid` and `email` +|`nifi.security.user.oidc.claim.identifying.user` | Claim that identifies the authenticated user. The default value is `email`. Claim names may need to be requested using the `nifi.security.user.oidc.additional.scopes` property +|`nifi.security.user.oidc.fallback.claims.identifying.user` | Comma-separated list of possible fallback claims used to identify the user when the `nifi.security.user.oidc.claim.identifying.user` claim is not found. +|`nifi.security.user.oidc.claim.groups` | Name of the ID token claim that contains an array of group names of which the user is a member. Application groups must be supplied from a User Group Provider with matching names in order for the authorization process to use ID token claim groups. The default value is `groups`. -|`nifi.security.user.oidc.truststore.strategy` | If value is `NIFI`, use the NiFi truststore when connecting to the OIDC service, otherwise if value is `JDK` use Java's default `cacerts` truststore. The default value is `JDK`. +|`nifi.security.user.oidc.truststore.strategy` | HTTPS Certificate Trust Store Strategy defines the source of certificate authorities that NiFi uses when communicating with the OpenID Connect Provider. +The value of `JDK` uses the Java platform default configuration stored in `cacerts` under the Java Home directory. +The value of `NIFI` enables using the trust store configured in the `nifi.security.truststore` property. The default value is `JDK` +|`nifi.security.user.oidc.token.refresh.window` | The Token Refresh Window specifies the amount of time before the NiFi authorization session expires when the application will attempt to renew access using a cached Refresh Token. The default is `60 secs` |================================================================================================================================================== +==== OpenID Connect REST Resources + +OpenID Connect authentication enables the following REST resources for integration with an OpenID Connect 1.0 Authorization Server: + +[options="header"] +|====================================== +| Resource Path | Description +| /nifi-api/access/oidc/callback/consumer | Process OIDC 1.0 Login Authentication Responses from an Authentication Server. +| /nifi/logout-complete | Path for redirect after successful OIDC RP-Initiated Logout 1.0 processing +|====================================== + Review Comment: Very helpful to have. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
