User Consent

Consenting to requested claims¶

Curity supports user consent based on requested claims or scopes. Scopes are either expanded to claims (e.g. in case of an OpenId Connect scope like profile, email, etc.) or projected on to claims directly. Once user consent is enabled, when a client starts a flow that involves user interaction (i.e. code, implicit, assisted token or device authorization flow), the authenticated user will be asked to confirm that the requested claims are OK to be bound to the delegation. This will result in tokens being issued with claims and scopes that the user confirmed.

Example¶

With user consent enabled, a client client-one redirects the user to Curity authorize a token request for scopes read, openid and email with the following URL:

Listing 151 Example request URL¶

    https://curity.example.com/authorize?client_id=client-one&response_type=code&scope=read%20openid%20email&state=1512320823&redirect_uri=https://client-one.example.com

After the user authenticates as teddie, the following screen will be shown in the user’s browser:

../_images/example-asking-user-consent.png

Asking for consent¶

The user is involved in confirming the requested claims when user consent is enabled for a client. The purpose of asking for user consent, is to involve the user into giving its permission for the requested claims and/or scopes. Once this permission is given, it is established and valid for as long as the delegation that the user consent was bound to. This means that, when a delegation exists for a user that has authenticated for a new request to authorize a token, the claims that were bound to the existing delegation are used to check if they satisfy the new authorization request. In case the new request asks for the same or less permissions than the existing delegation provided, then the user will not be asked to confirm the request, i.e. the currently active delegation’s permissions are still valid and used as such.

If you want to assert that the user is always asked for consent with an authorization request, you can include the prompt=consent parameter in the authorization request (as specified in OpenID Connect).

If the configuration does not allow the claims to be deselected, but they should be for a certain transaction, then prompt=consent_allow_deselection can be provided to enable deselection of certain claims only for that request. If this is used, the prompt value may or may not include consent as well. If consent is not included and the client isn’t configured to require consent, the user will not be prompted (and consequently consent_allow_deselection will have no effect). If consent is enabled on the client, deselection of the claims will be allowed (irrespective of the configured value for deselection). If both consent and consent_allow_deselection are provided, then they should be separated on the query string by a space (that is properly URL encoded).

Example with `prompt`¶

When a client requests authorization for an Access Token, and it wants the user to consent to the requested scopes, it can include prompt=consent in the request parameters and redirect the user to:

Listing 152 Example request URL with prompt=consent¶

https://curity.example.com/authorize?client_id=client-one&response_type=code&scope=read%20openid%20email&state=1512320823&redirect_uri=https://client-one.example.com&prompt=consent

Note

The client does not need to be configered with User Consent enabled, as including prompt=consent in the parameters will also trigger user consent gathering for that request.

When the user is allowed to deselect requested claims during user consent gathering, the client can be configured with Allow Deselection enabled, or it can include the consent_allow_deselection value in the prompt parameter. The URL to redirect the user to will be like this:

Listing 153 Example request URL with prompt=consent and consent_allow_deselection¶

    https://curity.example.com/authorize?client_id=client-one&response_type=code&scope=read%20openid%20email&state=1512320823&redirect_uri=https://client-one.example.com&prompt=consent+consent_allow_deselection

Note

The client does not need to be configered with Allow Deselection enabled, as including prompt=consent_allow_deselection in the parameters will also trigger consent deselection for that request.

Enabling user consent¶

User interactive consent can be enabled per client. It is only available when the client supports user interactive flows. To enable it, toggle the slider.

The user consent template¶

The user interface uses the oauth/consent.vm template to render consent. This template includes the use of the client logo, privacy policy and terms of services URL’s if they are configured. Internationalized messages for the user consent template can be managed in the oauth/messages file, where the translation of the requested claims can also be stored.

Example claim localization¶

The file usr/share/messages/core/en/views/oauth/messages describes the following translations for the sub claim:

consent.claim-names.sub=User ID
consent.claim-descriptions.sub=Your user account ID

You can override these default translations by creating a file usr/share/messages/overrides/en/views/oauth/messages where you can redefine the consent.claim-names.sub claim name and the consent.claim-descriptions.sub description.

Tip

To enforce a particular locale, a client can include the ui_locales parameter in the request, see the paragraph About Locales to learn more about localization

Showing prefix scopes¶

By default, prefix scopes are shown in the User Consent Page. page as any other scope that does not map to a known claim.

The description shown in the User Consent Page is the one that was configured for the scope.

The claim will be shown as the requested value, unless a localized message for the prefix is defined, as we’ll see.

For example, if you have a prefix scope called ttid: (for transaction id) with a configured description Rådande Transaktion, and a client requests the ttid:SN1234567890 scope, the default User Consent screen would appear as shown below:

../_images/user-consent-prefix-scope.png

The description of the scope, in this case, is shown as it is in the scope’s configuration for any Locale.

If you need to localize the description of the scope, you should set the description of the scope to a message key rather than an actual message.

Keeping with the current example, a good message key could be scopes.description.ttid.

The claim itself can also be localized, but for prefix scopes, the message key needs to have the same value as the prefix scope, ttid: in this case.

In summary, supposing you configured a prefix scope called ttid: and set its description to scopes.description.ttid, then you would have to create a message file with values for these keys on each Locale you want to support, as explained in About Locales:

Listing 154 Message entry for the prefix scope in the usr/share/messages/overrides/en/messages.properties file.¶

ttid=Transaction:
scopes.description.ttid=Approve the current transaction

Note

Notice how certain characters, such as the : character above, must be escaped in properties files.

The following image shows what the default template would look after the above messages were defined for the English locale, for a client requesting, among other claims, the ttid:ABC123456 scope:

../_images/user-consent-prefix-scope-custom.png

If you would like to override the default template, templates/overrides/views/oauth/consent.vm, you can simply create a file at templates/overrides/views/oauth/consent.vm and modify it as appropriate.

Currently, the default consent page iterates over the consent entries as follows:

Listing 155 How claim entries are shown by the default user consent template (templates/core/views/oauth/consent.vm)¶

  #foreach ($entry in $_consentEntries.entrySet())
      <li>
      #set ( $keyName = $entry.key )
      #set ( $parameterName = "consent.$keyName")
      #if ($entry.value.scopePrefix != "")
          #define($prefixName)#message("$entry.value.scopePrefix")#end
          #set ( $suffix = $entry.value.scopeSuffix )
          #set ( $claimLabel = "$prefixName$suffix" )
      #else
          #define($claimLabel)#message("$entry.value.displayName")#end
      #end
      <label class="block full-width relative"
      #if ($entry.value.required == "true")
          ><input type="checkbox" name="$parameterName" id="$parameterName" checked disabled>
          <label class="consent-entries-list-checkbox"></label>
              <input type="hidden" name="$parameterName"
      #else
          ><input type="checkbox" name="$parameterName" id="$parameterName" checked
      #end
      >
      <label class="consent-entries-list-checkbox"></label>
      <span class="consent-entries-list-name">$claimLabel</span>
      ...

The highlighted lines show how the entry’s name is selected depending on whether or not the entry represents a prefix scope, setting an appropriate value for the claimLabel variable for each case.

Consentors¶

Curity also supports extending the authorization request with consentors, which are an extensibility mechanism used to perform additional processing, including validation, information retrieval, and user interaction. Consentors are run during the authorization request of the code and implicit grants, and on the assisted token request, after user-consent has been collected.

See the consentors documentation for additional information.

User Consent¶

Consenting to requested claims¶

Example¶

Asking for consent¶

Example user consent gathering¶

Example with prompt¶

Enabling user consent¶

The user consent template¶

Example claim localization¶

Showing prefix scopes¶

Consentors¶

Example with `prompt`¶