ConsentState

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.

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 and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.oauth2.consentstate.ConsentState
Logging	OAuth2
Auditing	none
Marker	none
Methods	process, generate

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.httpclient.* (String)

  Configure the outgoing HTTP communication to nevisMeta. For a list of valid HTTP properties, see HTTP Client.

Input

• Requested scopes from session:oauth2.authorization_request.scope
• Requesting client from session:oauth2.authorization_request.client_id
• Unfiltered 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"},
            ...
            }
  }
  

• 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="Terms of Service"
                name="clientToS"
                optional="true"
                type="link"
                value="${notes:tos_uri}" />
          <GuiElem
                label="Policy"
                name="clientPolicy"
                optional="true"
                type="link"
                value="${notes:policy_uri}" />
          <GuiElem
                label=""
                name="consentInformation"
                optional="true"
                type="hidden"
                value="${notes:consentInformation}" />
        </Gui>
      </Response>

</AuthState>