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.
- 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.
<oauthProvider id="OAuthConfigSample"
authorizationFormTemplate="https://acme.com:9043/oath20/template.html
...>
<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>