OAuthMappingExtUtils Utility

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 typeMethodDescription
Booleanassociate(stateID, attrKey, attrValue)Associates the attribute key-value pair to authorization grant state ID. Returns true if succeeded, otherwise false
stringdisassociate(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.
stringgetAssociation(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 ObjectretrieveAllAssociations(stateID)Retrieve all associations for a specified grant/state-id this method is to be as performant as possible.
stringbatchCreate(stateID, attributes)Perform a batch creation of associated attributes. Return any processing error, otherwise null.
stringbatchUpdate(stateID, attributes)Perform a batch modification of associated attributes. Return any processing error, otherwise null.
stringbatchDelete(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:

NameData typeRequiredDescription
stateIDstringYesAuthorization grant ID.
attrKeysstring[]YesList of attribute keys.
attrKeystringYesAttribute key.
attrValuestringYesAttribute value.
attributesJS ObjectYesMap 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 typeMethodDescription
JS ErrorthrowSTSException(message)Throw (500) server_error error, with error description specified.
JS ErrorthrowSTSUserMessageException(message, details)Throw (500) server_error error, with error description and details specified.
JS ErrorthrowSTSCustomUserPageException(message, statusCode, errorCode)Throw custom error message, giving the status code, error code, and error description.
JS ErrorthrowSTSCustomUserMessageException(message, statusCode, errorCode)Throw custom error message, giving the status code, error code, and error description.
JS ErrorthrowSTSInvalidGrantMessageException(message, details)Throw (400) invalid_grant error, with error description and details specified.
JS ErrorthrowSTSAccessDeniedMessageException(message, details)Throw (403) access_denied error, with error description and details specified.

The following table describes the method of arguments:

NameData typeRequiredDescription
statusCodeintegerYesWanted HTTP status code returned.
errorCodestringYesError code. For OAuth/OIDC standard error, this argument populates the error field.
messagestringYesError message. For OAuth/OIDC standard error, this argument populates the error_description field.
detailsstringYesError 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 typeMethodDescription
JSON array of grantsgetGrants(username, Number of grants to be retrieved)Retrieves the number of grants for a specific user.
nulldeleteGrants(grantIds[])Deletes all grant associated with the array of state ids
nulldeleteGrant(grantId)Deletes grant associated with the state id or grant id
nulldeleteToken(username, clientid)Deletes tokens associated with the specific user and token.

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

NameData typeDescription
ClientIDStringClientID associated with the grant
StateIDStringThe 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");