Version: 4.32.x.x LTS

ConsentState

Introduction and overview

OAuth2 requires the authorization server to obtain an authorization decision by asking the resource owner or by establishing approval via other means. When asked for his consent, the end user is usually informed about what client is requesting authorization and for what scope.

The ConsentState can be used to prepare information required to request end-user consent via a consent screen. In particular, this includes information about the requested scope and the requesting client. This information is propagated in a format prepared to be interpreted and evaluated by nevisLogRend.

Information is only prepared and propagated if end-user approval is necessary. Whether end-user approval is required is decided based on the requesting client and the scope policy.

Information about the requested scopes (and already accepted scopes) is propagated as follows:

Source of information is the scope metadata in session:oauth2.scope.[scopeName].metadata. .*
Only the best suited translation of metadata is added (selected based on the requested language and language tags on metadata, e.g., scope_name#de).
The metadata is added without the prefix oauth2.scope.[scopeName].metadata. and the language tag. For example: oauth2.scope.scopeA.metadata.scope_name#de becomes scope_name.
Scope metadata is written into a JSON object formatted as follows:

{
 "scopeA":{ "scope_description":"Scope A Description",
    "scope_name":"Scope A Name"},
 "scopeB":{  "scope_description":"Scope B Description",
    "scope_name":"Scope B Name"},
 ...
}

The JSON object itself is added as value of requestedScopesRequiringConsent (requested scopes) and requestedScopesWithExistingConsent (already accepted scopes in case of persisted consent) field to another JSON object. This object is propagated in the consentInformation field of the configured propagation scope. For example, a possible value of the consentInformation field is:

{
"requestedScopesRequiringConsent": {
 "scopeA":{ "scope_description":"Scope A Description",
    "scope_name":"Scope A Name"},
 "scopeB":{ "scope_description":"Scope B Description",
    "scope_name":"Scope B Name"},
 ...
 },
"requestedScopesWithExistingConsent" : {
 "scopeC":{ "scope_description":"Scope C Description",
    "scope_name":"Scope C Name"},
 ...
 }
}

Information about the requesting client is propagated as follows:

Source of information is the client metadata in *session:oauth2.client.metadata.**
Only the best suited translation of metadata is added. The selection is based on the requested language and language tags on metadata (e.g., client_name#de).
The metadata is added to the notes without the prefix oauth2.client.metadata. and language tag. I.e., oauth2.client.metadata.client_name#de becomes client_name.

If the final flag of ConsentState is set to false and no consent is required because no scope requires consent, the result is set to ok without propagating any metadata or generating a GUI. If a GUI has been presented and the accept button was clicked, the result is set to ok. Otherwise, it is set to default.

Description

The following table describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.oauth2.consentstate.ConsentState
Logging	OAuth2
Auditing	none
Properties	propagationScope (string, "notes")Define scope in which the consentInformation object is propagated.
	dataSource (string, "session")The data source that is used to store and query the status of persisted consents.Possible values:session: The Nevis session of the user nevismeta: A nevisMeta instance
	nevismeta.location (string, -)The entity endpoint of a nevisMeta instance (e.g., `https://[server]:[port]/nevismeta/rest/modules/oauthv2/setups/[setup_id]/entities`)
	nevismeta.http.connection.timeout (int, 10)The time-out (in seconds) for establishing connections to a nevisMeta instance.
	nevismeta.http.socket.timeout (int, 30)The time-out (in seconds) for reading data from a nevisMeta instance.
Methods	process: Will try to validate the access token provided by the client.
	generate: Will try to validate the access token provided by the client.
Input	Requested scopes from session:oauth2.authorization_request.scopeRequesting client from session:oauth2.authorization_request.client_idUnfiltered scope metadata from session:oauth2.scope.[scopeName].metadata.Unfiltered client metadata from session:oauth2.client.metadata.**
Transitions	ok: The end-user has accepted all required scopes (or approval is not required).
	default: The end-user has not accepted all required scopes yet.
	<Button_name>: Use Button name as transitions to react to specific responses of ConsentState. See Defining transitions through buttons and checkboxes for further details.
Output	[propagationScope]:consentInformation

Example:

{
 "requestedScopesRequiringConsent": {
   "scopeA":{ "scope_description":"Scope A Description",
      "scope_name":"Scope A Name"},
   "scopeB":{ "scope_description":"Scope B Description",
       "scope_name":"Scope B Name"},
   ...
   }
}

Topic	Description
	notes:[clientMetadata]The metadata is added to the notes without the prefix oauth2.client.metadata. and language tag. For example, oauth2.client.metadata.client_name#de becomes client_name.
Errors	none
Notes	none

Example

<AuthState
class="ch.nevis.esauth.auth.states.oauth2.consentstate.ConsentState"
    final="false"
 name="ConsentState"
 resumeState="true">
 <ResultCond
 name="ok"
 next="AuthDone" />
 <ResultCond
 name="reject"
 next="AuthError" />
 <Response
 value="AUTH_CONTINUE">
  <Gui
 name="ConsentDialog">
 <GuiElem
 label="accept.label"
 name="accept"
 optional="false"
 type="button"
 value="approve" />
 <GuiElem

 label="reject.label"
 name="reject"
 optional="false"
 type="button"
 value="deny" />
 <GuiElem
 label="oauth.prompt"
 name="prompt"
 optional="false"
 type="info"
 value="" />
 <GuiElem
 label=""
 name="clientName"
 optional="false"
 type="info"
 value="${notes:client_name}" />
 <GuiElem
 label=""
 name="clientLogo"
 optional="false"
 type="image"
 value="${notes:logo_uri}" />
 <GuiElem
 label=""
 name="consentInformation"
 optional="true"
 type="hidden"
 value="${notes:consentInformation}" />
 </Gui>
 </Response>

</AuthState>

ConsentState

Example​

Example