Custom consent form template

The OAuth authorization server provides a template to acquire user consent information about which OAuth clients are authorized to access the protected resource in given scopes. The authorization request from the OAuth client includes a list of requested scopes from the template.

WebSphere® Application Server allows the consent form template to be either a static HTML page or a dynamic web page. In both cases, the template must be provided as an unprotected web resource. The form retriever in WebSphere Application Server integration does not perform any authentication when accessing this template URL.

The WebSphere Application Server OAuth provider includes a sample consent form template, and allows customization by using oauthFormData variable.

To customize the consent form, you must edit the oauthFormData variable by using Javascript. The following variables are included in the form data:

authorizationUrl - the authorization URL where the form is being submitted
clientDisplayName - the display name of the client
nonce - random generated number to prevent cross-site request forgery (CSRF)
client_id - see the OAuth 2.0 specification
response_type - see the OAuth 2.0 specification
redirect_uri - see the OAuth 2.0 specification
state - see the OAuth 2.0 specification
scope - see the OAuth 2.0 specification

The developer of a form template must include the content of the oauthFormData variable, by using Javascript. The developer must interpret the scope value to be a meaningful value to a user. When a user authorizes the request, the developer can call the submitForm(oauthFormData) method to perform the authorization. The submitForm method is provided by default. However, if developers are familiar with OAuth 2.0 protocol, they can implement their own function to submit the OAuth authorization request.

A cancel(oauthFormData) method is provided by default and can be used to allow a user to cancel the authorization request.

The consent form can also be modified to allow the user's consent selection to be cached. This means that if the same OpenID Connect client makes a new authorization request with the same approved scopes or reduced scopes, the user is not be prompted with the consent form. Instead, the previously allowed scopes are considered authorized and passed to the protected resource accordingly.

If client registration is in localStore mode, the user's consent selection is cached in the browser session. The approved scopes remain cached for the given user until the session is closed or until a set amount of time (specified in the server configuration) has elapsed.

If client registration is in databaseStore mode, the user's consent selection can be persistent in a database table, OAuthDBSchema.OAUTH20CONSENTCACHE. The scopes remain cached for the given user until a set amount of time (specified in the server configuration) has elapsed. The OpenID Connect provider tries to create the consent cache table automatically, but it is suggested that the user explicitly create the consent table when configuring a database for an OAuth2.0 provider and OpenID Connect provider, see Persistent OAuth service configuration for further details.

To use this functionality, the developer of a form template must include a prompt value within the oauthFormData JavaScript object. In order to cache the user's affirmative response and prevent the consent form from being displayed again in the same session, the prompt value is set to the string none. To allow the user to submit an affirmative response without caching the approval, the prompt value is set to the string consent.

You can use a dynamic page that returns globalized content according to the Accept-Language header in the request. When retrieving the template, the Accept-Language header is forwarded, and the template developer must decide which content to return regarding the preferred language.

Note: The clientDisplayName variable is not escaped in HTML. The template developer must sanitize the value, as the value is input by a user during client registration.

To use a custom consent form template page for a specific OAuth 2.0 service provider, you must update the service provider definition in the server.xml file. In the provider configuration, you must use the authorizationFormTemplate attribute of the oauthProvider element and add the template URL as the value. The following example shows a sample template entry in the provider configuration:

<oauthProvider id="OAuthConfigSample"
  authorizationFormTemplate="https://acme.com:9043/oath20/template.html
  ...>

The following example illustrates a sample consent form:

<oauthProvider id="OAuthConfigSample"
  authorizationLoginURL="https://acme.com:9043/oath20/login.jsp"
  ...>

function escapeHTML(str) {
    var ele = document.createElement("div");
    ele.innerText = ele.textContent = str;
    return ele.innerHTML;
}
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>OAuth authorization form</title>
<script language="javascript">
function init() {
	var scope = oauthFormData.scope;
	var scopeEle = document.getElementById("oauth_scope");
	var ul = document.createElement("ul");
	if(scope) {
		for(var i=0; i< scope.length; i++) {
			var n = document.createElement("li");
			n.innerHTML = scope[i];
			ul.appendChild(n);
		}
	}
	scopeEle.appendChild(ul);
	// set client name
	var clientEle = document.getElementById("client_name");
	clientEle.innerHTML = escapeHTML(oauthFormData.clientDisplayName);
}

function escapeHTML(str) {
    var ele = document.createElement("div");
    ele.innerText = ele.textContent = str;
    return ele.innerHTML;
}
</script>
</head>
<body onload="init()">
       <div>Do you want to allow client <span id=client_name style="font-weight:bold">xxxxxxx</span> to access your data?</div>
       <div id="oauth_scope">
       </div>
       <div>
              <form action="javascript:submitForm(oauthFormData);">    
                     <input type="submit" value="Allow, remember my decision" onclick="javascript:oauthFormData.prompt = 'none';"/>
                     <input type="submit" value="Allow once" onclick="javascript:oauthFormData.prompt = 'consent';"/>
                     <input type="button" value="Cancel" onclick="javascript:cancel(oauthFormData);"/>
              </form>  
       </div>
</body>
</html>