RelyingPartyState

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

Designated usage of the RelyingPartyState and integration with nevisProxy

The AuthState RelyingPartyState implements the authorization code flow and can be used to implement login in a Nevis-protected web application via an OpenID Connect identity provider. This is achieved by configuring nevisProxy to intercept unauthenticated requests to the web application and requiring authentication by nevisAuth. A nevisAuth instance configured with the RelyingPartyState will issue an authentication request to the OpenID Connect provider via an HTTP redirect. The OpenID Connect provider will then require the end user to authenticate. If successfully completed, the provider will redirect the end user back to the relying party with an authorization code. Upon receipt of an authorization code, the RelyingPartyState will redeem it for an ID and access token at the provider. The ID token returned by the provider will then be verified by the RelyingPartyState, the user ID will be set to the subject claim in the ID token and further claims contained in the ID token will be propagated in the session. nevisAuth will respond to nevisProxy with AUTH_DONE and a SecToken, which nevisProxy can then delegate to the originally requested web application. This flow is also depicted in the following figure.

Preconditions and limitations

The following preconditions and limitations exist:

• The RelyingPartyState AuthState requires the OpenID Connect provider to provide a metadata document.
• Required key material must be provided as a JWK document under the URL provided in the jwks_uri field of the metadata document.
• Only ID tokens provided as plain JWT or JWS (signed with RSA signature scheme) are supported.
• acr claims are ignored.

Description

The following table describes the characteristics of the RelyingPartyState AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.oauth2.openid.rp.RelyingPartyState
Logging	OIDCRelyingParty
Auditing	none
Marker	none
Methods	process Issues an authentication request and a token request upon receipt of a successful authentication response. Authenticates end user and propagates claims if authentication response contains valid ID token.

Properties

• redirectURI (string (URL))

  The redirect_uri used in the authentication request. A valid URL or a variable which is substituted with a valid URL during runtime is supported.

• clientId (string)

  The client_id used in the authentication and token request.

• clientSecret (string)

  The client_secret used in the token request. The AuthState supports both a fixed client secret and a variable that is substituted during runtime.

• scope (space-separated string)

  Requested scope used in the authentication request.

• claimsRequest (string)

  The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

• providerConfiguration (string)

  Supported values are

  • the URL of the provider metadata document,
  • a string containing provider metadata as per specification, or
  • a variable containing a provider metadata document.

  This AuthState uses the HTTP protocol to fetch the metadata document (depends on the URL configured). It is thus susceptible to HTTP proxies, as described in chapter [Configuring proxies](Configuring proxies).

• maxAge (integer in seconds)

  The max_age request parameter used in the authentication request

  info

  The max_age property is not supported by Google IdP (they return an invalid expire time), so do not add this property while using Google as IdP.

• acr_values (string)

  Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value. The acr Claim is requested as a Voluntary Claim by this parameter.

• arbitraryAuthRequestParam.[paramName] (string)

  Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

  Example

  <property name="arbitraryAuthRequestParam.[paramName]" value="[paramValue]" />

• userId (string, "${sess:[AuthStateName].idTokenClaim.sub}")

  The user ID by which the user will be authenticated. The AuthState supports both a fixed user ID or a variable one that is substituted during runtime.

• clientAuthMethod (string, "client_secret_basic")

  The secret can be sent to the token endpoint in two ways:

  • client_secret_basic (default)

    The client secret and clientID are sent to the token endpoint with the HTTP Basic authentication scheme.

  • client_secret_post

    The client secret and clientID are sent to the token endpoint with the HTTP Post scheme.

  • client_secret_jwt

    The client secret and the client ID are sent to the token endpoint using JWT Bearer token.

• responseMode (string, "query")

  The way to handle authorization callback (to nevisAuth)

  • query (default)

    The callback via GET request

  • form_post

    The callback via POST request

• allowRedirect (boolean, true)

  After receiving a response from the OpenID Connect identity provider, RelyingPartyState will automatically set redirect to the original request URL. Set this variable to "false" to disable this behavior.

  info

  After you disable the redirect here, add another AuthState for redirecting back to the original request URL.

• httpclient.* (String)

  Configure the outgoing HTTP communication towards the metadata provider. For a list of valid HTTP properties, see HTTP Client.

Input

none

Transitions

• failed

  Authentication was not successful, the ID token was not valid or an internal error occurred.

• ok

  Authentication was successful and the ID token is valid.

Output

• session:[AuthStateName].tokenResponse.[field]

  The value of fields of the received token response. For example:

  RelyingParty.tokenResponse.id_token = [encodedIDToken]
  RelyingParty.tokenResponse.access_token = [encodedAccessToken]

• session:[AuthStateName].idTokenClaim.[claimName]

  The value of the claims present in the ID token. For example:

  RelyingParty.idTokenClaim.sub = [username]

Errors

none

Notes

none

Example

<AuthState name="RelyingParty" class="ch.nevis.esauth.auth.states.oauth2.openid.rp.RelyingPartyState" final="false">
        <ResultCond name="ok" next="AuthDone"/>
        <ResultCond name="failed" next="AuthError"/>   
        <property name="redirectURI" value="[redirectURI]" />
        <property name="clientId" value="[clientId]" />
        <property name="scope" value="openid email" />
        <property name="claimsRequest"
            value="{&quot;id_token&quot;:{&quot;given_name&quot;:null}, &quot;userinfo&quot;:{&quot;address&quot;:null}}" />
        <property name="clientSecret" value="[clientSecret]" />
        <property name="providerConfiguration" value="[providerMetadataDocumentURI]" />
        <property name="maxAge" value="3600" />
        <property name="arbitraryAuthRequestParam.access_type" value="offline" />
        <property name="arbitraryAuthRequestParam.new_value" value="#{StringUtils.contains(inargs['auth-strength'],'2') ? 'qoa2':'qoa1'}" />
</AuthState>

If not present yet, add the root certificate to the truststore (-Djavax.net.ssl.trustStore) that is defined in the JAVA_OPTS configuration option in the env.conf file. See also the following sample code snippet. The root certificate is used to prove the authenticity of the provider configuration and to verify the authenticity of the token and authorization endpoints.

keytool -import -keystore /var/opt/keybox/default/truststore.jks -file GeoTrustGlobalCA.pem