OAuthMappingExtUtils

Various helper methods.

1. Associate/Disassociate methods

Use the following methods to associate key-value pair for a particular authorization grant that is based on state ID. To remove the association, use disassociate.

Return type	Method	Description
Boolean	associate(stateID, attrKey, attrValue)	Associates the attribute key-value pair to authorization grant state ID. Returns `true` if succeeded, otherwise `false`
string	disassociate(stateID, attrKey)	Disassociates the attribute key-value pair from the authorization grant state ID. Returns attribute value of disassociated attribute. Null if attribute not found.
string	getAssociation(stateID, attrKey)	Get an attribute value that is associated with the specified state ID and attribute key. Return attribute value. Null if not found.
string[]	getAssociationKeys(stateID)	Get all the attribute keys associated with the specified authorization grant state ID. Returns a String array of all attribute keys that are associated with the authorization grant state ID. Returns null if state ID is invalid, problem retrieving from token cache, or no associated attributes.
JS Object	retrieveAllAssociations(stateID)	Retrieve all associations for a specified `grant/state-id` this method is to be as performant as possible.
string	batchCreate(stateID, attributes)	Perform a batch creation of associated attributes. Return any processing error, otherwise null.
string	batchUpdate(stateID, attributes)	Perform a batch modification of associated attributes. Return any processing error, otherwise null.
string	batchDelete(stateID, attrKeys)	Perform a batch removal of the associated attributes of a grant based on the keys provided. Return any processing error, otherwise null.

The following table describes the method of arguments:

Name	Data type	Required	Description
stateID	string	Yes	Authorization grant ID.
attrKeys	string[]	Yes	List of attribute keys.
attrKey	string	Yes	Attribute key.
attrValue	string	Yes	Attribute value.
attributes	JS Object	Yes	Map of attribute key-value.

Example usage:

  var attrs = {
    "given_name": "John",
    "family_name": "Smith",
    "age": "25"
  }
  var createErr = OAuthMappingExtUtils.batchCreate("asaa282-sa248834-bed72aa", attrs);
  if (createErr == null) {
    var arr = OAuthMappingExtUtils.getAssociationKeys("asaa282-sa248834-bed72aa");
    var deleteErr = batchDelete("asaa282-sa248834-bed72aa", arr);
    if (deleteErr != null) {
      // do something
    }
  }

2. Throw exception methods

Throw type	Method	Description
JS Error	throwSTSException(message)	Throw (500) `server_error` error, with error description specified.
JS Error	throwSTSUserMessageException(message, details)	Throw (500) `server_error` error, with error description and details specified.
JS Error	throwSTSCustomUserPageException(message, statusCode, errorCode)	Throw custom error message, giving the status code, error code, and error description.
JS Error	throwSTSCustomUserMessageException(message, statusCode, errorCode)	Throw custom error message, giving the status code, error code, and error description.
JS Error	throwSTSInvalidGrantMessageException(message, details)	Throw (400) `invalid_grant` error, with error description and details specified.
JS Error	throwSTSAccessDeniedMessageException(message, details)	Throw (403) `access_denied` error, with error description and details specified.

The following table describes the method of arguments:

Name	Data type	Required	Description
statusCode	integer	Yes	Wanted HTTP status code returned.
errorCode	string	Yes	Error code. For OAuth/OIDC standard error, this argument populates the `error` field.
message	string	Yes	Error message. For OAuth/OIDC standard error, this argument populates the `error_description` field.
details	string	Yes	Error details. The details populate the error hint.

Example usage:

  if (isAccessDenied) {
    OAuthMappingExtUtils.throwSTSCustomUserMessageException("my error message", 403, "access_denied");
  } else {
    OAuthMappingExtUtils.throwSTSInvalidGrantMessageException("my error message", "my error details");
  }

3. Grant and token retrieval

Return type	Method	Description
JSON array of grants	getGrants(username, Number of grants to be retrieved)	Retrieves the number of grants for a specific user.
null	deleteGrants(grantIds[])	Deletes all grant associated with the array of state ids
null	deleteGrant(grantId)	Deletes grant associated with the state id or grant id
null	deleteToken(username, clientid)	Deletes tokens associated with the specific user and token.

The following table describes the items returned by the grant array:

Name	Data type	Description
ClientID	String	ClientID associated with the grant
StateID	String	The grant id

Example usage:

importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);
importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.OAuthMappingExtUtils);


IDMappingExtUtils.traceString("grant Util "); 

var outJSON = [];
var grants = OAuthMappingExtUtils.getGrants('peter',5);
IDMappingExtUtils.traceString("grant :"+grants.length); 
var stateids = [];
for(let i=0; i< grants.length; i++){
    var grant = grants[i];
    stateids.push(''+grant["StateID"])
}

OAuthMappingExtUtils.deleteGrant(stateids[0]);

OAuthMappingExtUtils.deleteGrants(stateids);

OAuthMappingExtUtils.deleteTokens('peter', 'client01');

IDMappingExtUtils.traceString("grant Util done");