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 are the URL of the provider metadata document, a string containing provider metadata as per specification or a variable containing a provider metadata document.
	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 requestExample: <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.
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" />
</AuthState>

The root certificate which is used to prove authenticity of the provider configuration and to verify the authenticity of the token and authorization endpoints must be added to the truststore defined in vmargs.conf if not present yet. For example:

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