RelyingPartyState

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 according to `http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.
• 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 RelyingPartyStateAuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.oauth2.openid.rp.RelyingPartyState
Logging	OIDCRelyingParty
Auditing	none
Marker	none
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.
	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 arethe 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 or FTP protocol to fetch the metadata document (depends on the URL configured). It is thus susceptible to HTTP and FTP proxies, as described in chapter Configuring proxies.
	maxAge (integer in seconds)The max_age request parameter used in the authentication request (http://openid.net/specs/openid-connect-core-1_0.html/)
	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.
	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
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.
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 = \ RelyingParty.tokenResponse.access_token =
	session:[AuthStateName].idTokenClaim.[claimName]The value of the claims present in the ID token. For example: RelyingParty.idTokenClaim.sub =
Errors	none
Notes	none

AuthState Config 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.acr_values" 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