Class OAuthMappingExtUtils

java.lang.Object
com.tivoli.am.fim.trustserver.sts.utilities.OAuthMappingExtUtils

public class OAuthMappingExtUtils extends Object
Implementation of STS Mapping Extension Functions for OAuth.
  • Field Details

  • Constructor Details

    • OAuthMappingExtUtils

      public OAuthMappingExtUtils()
  • Method Details

    • throwSTSException

      public static void throwSTSException(String message) throws com.tivoli.am.fim.trustserver.sts.STSException
      Used to throw STS Messages from Javascript mapping rules. use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • generateRandomString

      public static String generateRandomString(int length)
      Generate a random string of specified length. Charset will include:
      • A-Z
      • a-z
      • 0-9
      Parameters:
      length - of the string to create.
      Returns:
      a String of specified length
    • throwSTSUserMessageException

      public static void throwSTSUserMessageException(String message) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STS Messages from Javascript mapping rules. use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • throwSTSCustomUserPageException

      public static void throwSTSCustomUserPageException(String message, int statusCode, String errorType) throws com.tivoli.am.fim.trustserver.sts.utilities.STSCustomUserPageException
      Used to thrown an error page with user-supplied message, status code and error type from XLST/Javascript mapping rules.
      Parameters:
      message - to include as error_description in the error page
      statusCode - to return Http status code
      errorType - to include as error
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSCustomUserPageException
    • throwSTSCustomUserMessageException

      public static void throwSTSCustomUserMessageException(String message, int statusCode) throws com.tivoli.am.fim.trustserver.sts.utilities.STSCustomUserMessageException
      Used to throw STS Messages with user-supplied status code from Javascript mapping rules.
      Parameters:
      message - to include as error_description
      statusCode - to return Http status code
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSCustomUserMessageException
    • throwSTSCustomUserMessageException

      public static void throwSTSCustomUserMessageException(String message, int statusCode, String errorType) throws com.tivoli.am.fim.trustserver.sts.utilities.STSCustomUserMessageException
      Used to throw STS Messages with user-supplied status code and error type from Javascript mapping rules.
      Parameters:
      message - to include as error_description
      statusCode - to return Http status code
      errorType - to include as error
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSCustomUserMessageException
    • throwSTSUserMessageException

      public static void throwSTSUserMessageException(String message, String details) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STS Messages from Javascript mapping rules.
      Parameters:
      details - string of details to include. If valid json will be parsed and included as a json object, otherwise will be presented as a string. use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • throwSTSInvalidGrantMessageException

      public static void throwSTSInvalidGrantMessageException(String message) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STS Messages from Javascript mapping rules and to return a 400 with the error "invalid_grant"
      Parameters:
      message - to include as a error_description use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • throwSTSInvalidGrantMessageException

      public static void throwSTSInvalidGrantMessageException(String message, String details) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STS Messages from Javascript mapping rules and to return a 400 with the error "invalid_grant"
      Parameters:
      message - to include as a error_description
      details - string or object use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • throwSTSAccessDeniedMessageException

      public static void throwSTSAccessDeniedMessageException(String message) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STS Messages from Javascript mapping rules and to return a 401. use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • throwSTSAccessDeniedMessageException

      public static void throwSTSAccessDeniedMessageException(String message, String details) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STS Messages from Javascript mapping rules and to return a 401.
      Parameters:
      details - string of details to include. If valid json will be parsed and included as a json object, otherwise will be presented as a string. use IDMappingExtUtils.throwSTSException(String) instead
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • associate

      public static boolean associate(String stateID, String attrKey, String attrValue)
      Associates the attribute key-value pair to authorization grant state ID. This method will set the sensitive and readonly properties to false.
      Parameters:
      stateID - State ID of the authorization grant
      attrKey - Attribute key
      attrValue - Attribute value
      Returns:
      Whether or not it succeeded.
    • associate

      public static boolean associate(String stateID, String attrKey, String attrValue, boolean sensitive, boolean readonly)
      Associates the attribute key-value pair to authorization grant state ID. When updating an existing property, this method does not allow changes to be made to the immutable sensitive and readonly properties. Will not mark a sensitive attributes as non-sensitive, or a non-sensitive attribute as sensitive. The same applies for readonly.
      Parameters:
      stateID - State ID of the authorization grant
      attrKey - Attribute key
      attrValue - Attribute value
      sensitive - If this value should be stored as a sensitive value. If the attribute already exists, its sensitive state will be preserved.
      readonly - If this value should be stored as a readonly value. If this attribute already exists, its readonly state will be preserved.
      Returns:
      Whether or not it succeeded.
    • updateToken

      public static boolean updateToken(String tokenId, Long newLifetime, Long newLastUsed, Boolean enabled)
      Update a tokens lifetime lastused or enabled state One of newLifetime, newLastUsed and enabled must not be null.
      Parameters:
      tokenId - identifier of the token to update. Cannot be null.
      newLifetime - the new lifetime of the token in seconds. If null the lifetime will not be changed.
      newLastUsed - the new date last used of the token in milliseconds since the epoch (i.e. 01 January 1970 00:00:00 UTC). If null the date last used will not be changed.
      enabled - whether or not the token is enabled.
    • disassociate

      public static String disassociate(String stateID, String attrKey)
      Disassociates the attribute key-value pair from the authorization grant state ID.
      Parameters:
      stateID - State ID of the authorization grant
      attrKey - Attribute key
      Returns:
      Attribute value of disassociated attribute. Null if attribute not found.
    • getToken

      public static Token getToken(String tokenId)
      Retrieve a token based off its tokenId. If token hashing is enabled, the is function will handle hashing the token for the lookup. The token returned may have expired and not yet been cleaned up.
      Parameters:
      tokenId - to lookup
    • getActiveToken

      public static Token getActiveToken(String tokenId)
      Retrieve a token based off its tokenId. If token hashing is enabled, the is function will handle hashing the token for the lookup. Expired tokens will not be returned.
      Parameters:
      tokenId - to lookup
    • getAllTokensForUser

      public static Token[] getAllTokensForUser(String username)
      Get all the tokens for a given user Some of the tokens returned may have expired and not been cleaned up. Some of the tokens may not belong to this client.
      Parameters:
      username - which identifies a grant
      Returns:
      An array of tokens issued for the provided user
    • getAllActiveTokensForUser

      public static Token[] getAllActiveTokensForUser(String username)
      Get all the tokens for a given user Expired tokens will not be returned. Some of the tokens may not belong to this client.
      Parameters:
      username - which identifies a grant
      Returns:
      An array of tokens issued for the provided user
    • getTokens

      public static Token[] getTokens(String stateId)
      Get the tokens associated with the given stateId Some of the tokens returned may have expired and not been cleaned up.
      Parameters:
      StateId - which identifies a grant
      Returns:
      An array of tokens associated with the given stateId.
    • getActiveTokens

      public static Token[] getActiveTokens(String stateId)
      Get the tokens associated with the given stateId Expired tokens will not be returned.
      Parameters:
      StateId - which identifies a grant
      Returns:
      An array of tokens associated with the given stateId.
    • getTokens

      public static Token[] getTokens(String clientId, String username)
      Get the tokens associated with the given username and client ID Some of the tokens returned may have expired and not been cleaned up.
      Parameters:
      clientId - The client id of the token. This parameter cannot be null or empty.
      username - The user name of the token. This parameter cannot be null or empty.
      Returns:
      An array of tokens associated with the given username and client ID. Null if no tokens found.
    • getActiveTokens

      public static Token[] getActiveTokens(String clientId, String username)
      Get the tokens associated with the given username and client ID Expired tokens will not be returned.
      Parameters:
      clientId - The client id of the token. This parameter cannot be null or empty.
      username - The user name of the token. This parameter cannot be null or empty.
      Returns:
      An array of tokens associated with the given username and client ID. Null if no tokens found.
    • deleteAllTokensForUser

      public static int deleteAllTokensForUser(String username)
      Delete all tokens owned by a user from the cache
      Parameters:
      username - username of the OAuth tokens to be deleted. This cannot be null or empty.
      Returns:
      false- No tokens deleted true- Tokens deleted
    • deleteTokens

      public static int deleteTokens(String username, String clientId)
      Delete all tokens owned by a user for a specific client from the cache
      Parameters:
      username - username of the OAuth tokens to be deleted. This cannot be null or empty.
      clientId - clientId of the OAuth tokens to be deleted. This cannot be null or empty.
      Returns:
      false- No tokens deleted true- Tokens deleted
    • deleteTokens

      public static int deleteTokens(String username, String clientId, int batchSize)
      Delete all tokens owned by a user for a specific client from the cache
      Parameters:
      username - username of the OAuth tokens to be deleted. This cannot be null or empty.
      clientId - clientId of the OAuth tokens to be deleted. This cannot be null or empty.
      batchSize - The number of tokens to delete in a single batch.
      Returns:
      false- No tokens deleted true- Tokens deleted
    • deleteToken

      public static boolean deleteToken(String tokenID)
      Delete an OAuth token from the cache.
      Parameters:
      tokenID - ID of the OAuth token to be deleted. This cannot be null or empty.
      Returns:
      false- No token deleted true- Token deleted
    • deleteHashedToken

      public static boolean deleteHashedToken(String tokenID)
      Delete a Hashed OAuth token from the cache.
      Parameters:
      tokenID - ID of the OAuth token to be deleted. This cannot be null or empty.
      Returns:
      false- No token deleted true- Token deleted
    • getGrants

      public static Grant[] getGrants(String username)
      Get the grants associated with the given username.
      Parameters:
      username - The username of the grant. This parameter cannot be null or empty.
      Returns:
      An array of grants associated with the given username. Null if no grants found.
    • deleteGrant

      public static boolean deleteGrant(String stateID)
      Delete an OAuth grant from the cache.
      Parameters:
      stateID - ID of the OAuth grant to be deleted. This cannot be null or empty.
      Returns:
      false- No grant deleted true- Grant deleted
    • deleteGrant

      public static boolean deleteGrant(String stateID, Boolean cleanAttributes)
      Delete an OAuth grant from the cache.
      Parameters:
      stateID - ID of the OAuth grant to be deleted. This cannot be null or empty.
      cleanAttributes - Flag to clean the extra attributes associated.
      Returns:
      false- No grant deleted true- Grant deleted
    • getAssociationKeys

      public static String[] getAssociationKeys(String stateID)
      Get all the attribute keys associated with the given authorization grant state ID.
      Parameters:
      stateID - State ID of the authorization grant
      Returns:
      A String array of all attribute keys associated with the authorization grant state ID. Returns null if state ID is invalid, problem retrieving from token cache, or no associated attributes.
    • getAssociation

      public static String getAssociation(String stateID, String attrKey)
      Get an attribute value associated with the given state ID and attibute key.
      Parameters:
      stateID - State ID of the authorization grant
      Returns:
      Attribute value. Null if not found.
    • retrieveAllAssociations

      public static Map<String,String> retrieveAllAssociations(String stateID)
      retrieve all associations for a given grant/state-id this is to be as performant as possible
      Parameters:
      stateID - of the grant/token to retireve
    • batchDelete

      public static String batchDelete(String stateID, List<String> attributesToDelete)
      Perform a batch removal of the associated attributes of a grant This will remove the attributes with the provided names. If an error occurs, the database connection is rolled back.
      Parameters:
      attributesToDelete - list of attribute names to be deleted from the token/grants extra attributes
      stateId - the token/grant to update.
      Returns:
      null if all processing was successful / A string containing any SQL error output.
    • getEmptyMap

      public static Map<String,String> getEmptyMap()
    • batchCreate

      public static String batchCreate(String stateID, Map<String,String> attributesToCreate)
      Perform a batch creation of associated attributes. This will create attributes as provided by the input parameters via a single SQL statement to be as performant as possible. If an error occurs, the connection is rolled back.
      Parameters:
      attributesToCreate - map of key/value attributes to create. The key will not be checked prior to insertion, thus primary key violations may occur if an attempt to create an attribute which exists are made.
      stateId - the token/grant to update.
      attributesToUpdate - map of key/value attributes to update. The key will not be checked prior to update, so no update will occur on a key which does not exist
      Returns:
      null if all processing was successful / A string containing any SQL error output.
    • batchUpdate

      public static String batchUpdate(String stateID, Map<String,String> attributesToUpdate)
      Perform a batch modification of associated attributes. This will create attributes as provided by the input parameters via a single SQL statement to be as performant as possible. If an error occurs, the connection is rolled back.
      Parameters:
      attributesToUpdate - map of key/value attributes to update. The key will not be checked prior to update, so no update will occur on a key which does not exist
      stateId - the token/grant to update.
      Returns:
      null if all processing was successful / A string containing any SQL error output.
    • httpGet

      public static HttpResponse httpGet(String urlstr)
      HTTP client GET method.
      Parameters:
      urlstr - URL
      Returns:
      The HTTP response. Null if invalid URL or no response.
    • httpGet

      public static HttpResponse httpGet(String urlstr, Map headers, String httpsTrustStore, String basicAuthUsername, String basicAuthPassword, String clientKeyStore, String clientKeyAlias)
      HTTP client GET method.
      Parameters:
      urlstr - URL
      headers - A Map (String,String) to be added to the request header.
      httpsTrustStore - The name of the trust store to use. If a HTTPS connection is required and this is set to NULL, the default trust store specified in the override configs will be used.
      basicAuthUsername - Basic-auth username. If null, basic-auth will be disabled.
      basicAuthPassword - Basic-auth password. If null, basic-auth will be disabled.
      clientKeyStore - Client key store. If null, client cert auth will be disabled.
      clientKeyAlias - Client key alias. If null, client cert auth will be disabled.
      Returns:
      The HTTP response. Null if invalid URL or no response.
    • httpPost

      public static HttpResponse httpPost(String urlstr, Map params)
      HTTP client POST method.
      Parameters:
      urlstr - URL
      params - A Map (String,String) to be added to the request body.
      Returns:
      The HTTP response. Null if invalid URL or no response.
    • httpPost

      public static HttpResponse httpPost(String urlstr, Map headers, Map params, String httpsTrustStore, String basicAuthUsername, String basicAuthPassword, String clientKeyStore, String clientKeyAlias)
      HTTP client POST method.
      Parameters:
      urlstr - URL
      headers - A Map (String,String) to be added to the request header.
      params - A Map (String,String) to be added to the request body.
      httpsTrustStore - The trust store to use. If a HTTPS connection is required and this is set to NULL, the default trust store specified in the override configs will be used.
      basicAuthUsername - Basic-auth username. If null, basic-auth will be disabled.
      basicAuthPassword - Basic-auth password. If null, basic-auth will be disabled.
      clientKeyStore - Client key store. If null, client cert auth will be disabled.
      clientKeyAlias - Client key alias. If null, client cert auth will be disabled.
      Returns:
      The HTTP response. Null if invalid URL or no response.
    • getClient

      public static Client getClient(String clientId)
      Retrive a client with the given clientId. Client IDs are unique across all definitions, there is a guarantee that only one client is returned.
      Parameters:
      clientId - to lookup
      Returns:
      a Client object on success / null on error or no client found
    • getClientsByEmail

      public static Client[] getClientsByEmail(String emailAddress)
      Gets a list of clients which have an email address which matches the provided value
      Parameters:
      emailAddress - to search for clients with
      Returns:
      Array of clients, may be empty. null on error.
    • getClientsByContactPerson

      public static Client[] getClientsByContactPerson(String person)
      Gets a list of clients which have an contact person which matches the provided value
      Parameters:
      person - to search for clients with
      Returns:
      Array of clients, may be empty. null on error.
    • getClientsByCompanyName

      public static Client[] getClientsByCompanyName(String companyName)
      Gets a list of clients which have an company name which matches the provided value
      Parameters:
      companyName - to search for clients with
      Returns:
      Array of clients, may be empty. null on error.
    • createClient

      public static boolean createClient(String definitionName, String clientId, String clientName, String companyName, String clientSecret, String[] redirectUris, String companyUrl, String contactPerson, String emailAddress, String phoneNumber, String contactType, String otherInfo, boolean requirePkce, String jwksUri, String encryptionDb, String encryptionCert)
      Creates a client. This client will be available for use as soon as this function is called.
      Null and empty string are OK for some values.
      Required values are:
      • definitionName
      • clientId
      • clientName
      • companyName

      RedirectUri and companyUrl if provided must be valid URIs.
      If client secret is null the client will be considered non-confidential
      Contact type must be one of:
      • ADMINISTRATIVE
      • BILLING
      • OTHER
      • SUPPORT
      • TECHNICAL
      Parameters:
      definitionName - of the definition to add this client to
      clientId - identifier of this client.
      clientName - friendly name of the client.
      companyName - to identify which entity this client belongs to
      clientSecret - OPTIONAL secret for confidential clients
      companyUrl -
      contactPerson -
      emailAddress -
      phoneNumber -
      contactType -
      otherInfo -
      redirectUri -
      Returns:
      true on successful create / false if the client was not created.
    • deleteClient

      public static boolean deleteClient(String clientId)
      Remove a client by clientId.
      Parameters:
      clientId - to identify the client to remove.
      Returns:
      true if a client was removed / false if the client didn't exist or an error occurred.
    • updateClient

      public static boolean updateClient(String clientId, String clientName, String clientSecret, String[] redirectUris, boolean requirePkce)
      Update a client. No update will be performed if a value is null. This means to update a client to be non-confidential "" should be used.
      Parameters:
      clientId - to identify the client to update.
      clientName - new name of the client. Cannot be empty.
      clientSecret - new client secret.
      redirectUri - new redirectUri
      Returns:
      true if a client was update / false if the client didn't exist or an error occurred.
    • SHA512Sum

      public static byte[] SHA512Sum(String value)
      Get a SHA-512 hash of the provided value. This byte array can be converted to a base64 encoded string using the Base64Utility. Example: Base64Utility.encode(SHA512Sum(myValue));
      Parameters:
      value - to sum.
    • SHA384Sum

      public static byte[] SHA384Sum(String value)
    • SHA256Sum

      public static byte[] SHA256Sum(String value)
      Get a SHA-256 hash of the provided value. This byte array can be converted to a base64 encoded string using the Base64Utility. Example: Base64Utility.encode(SHA256Sum(myValue));
      Parameters:
      value - to sum.
    • getCertificateThumbprint

      public static String getCertificateThumbprint(String keystore, String alias) throws Exception
      Retrieving Certificate Thumbprint(x5t) value based on
      Parameters:
      value - to certificate thumbprint in sha-1.
      Throws:
      Exception
    • getCertificateThumbprint_S256

      public static String getCertificateThumbprint_S256(String keystore, String alias) throws Exception
      Retrieving Certificate Thumbprint(x5tS256) value based on
      Parameters:
      value - to certificate thumbprint in sha-256.
      Throws:
      Exception
    • getCertificateChain

      public static String[] getCertificateChain(String keystore, String alias) throws Exception
      Retrieving Certificate chain value based on
      Parameters:
      value - to certificate chain
      Throws:
      Exception
    • getDefinition

      public static Definition getDefinition(String definitionName)
      Retrive a definition with the given definitionName. DefinitionNames are unique across all definitions, there is a guarantee that only one definition is returned.
      Parameters:
      definitionName - to lookup
      Returns:
      a Definition object on success / null on error or no client found
    • getDefinitionByID

      public static Definition getDefinitionByID(long definitionID)
      Retrive a definition with the given definitionID. DefinitionID are unique across all definitions, there is a guarantee that only one definition is returned.
      Parameters:
      definitionID - to lookup
      Returns:
      a Definition object on success / null on error or no client found
    • isIncludeIssByDefinitionID

      public static boolean isIncludeIssByDefinitionID(long definitionID)
      Retrieve includeIssuer In Authorization response Flag with the given definitionID. DefinitionName are unique across all definitions, there is a guarantee that only one definition is returned.
      Parameters:
      DefinitionName - to lookup
      Returns:
      a boolean result will be returned, True if Definition has been configured to be include Iss and False otherwise.
    • isOidcCompliantByDefinitionID

      public static boolean isOidcCompliantByDefinitionID(long definitionID)
      Retrieve oidcCompliant Flag with the given definitionID. DefinitionName are unique across all definitions, there is a guarantee that only one definition is returned.
      Parameters:
      DefinitionName - to lookup
      Returns:
      a boolean result will be returned, True if Definition has been configured to be OIDC Compliant and False otherwise.
    • isFapiCompliantByDefinitionID

      public static boolean isFapiCompliantByDefinitionID(long definitionID)
      Retrive fapiCompliant Flag with the given definitionID. DefinitionName are unique across all definitions, there is a guarantee that only one definition is returned.
      Parameters:
      DefinitionName - to lookup
      Returns:
      a boolean result will be returned, True if Definition has been configured to be OIDC Compliant and False otherwise.
    • extractIssuer

      public static String extractIssuer(String token, String tokenType) throws Exception
      Extract issuer from the token based on different token type. This method is being used prior to STS callouts. Issuer will be extraced and used to verify which chain to call. Supported token types are: 1. urn:ietf:params:oauth:token-type:jwt 2. urn:ietf:params:oauth:token-type:saml1 3. urn:ietf:params:oauth:token-type:saml2
      Parameters:
      token - to be analyzed to get the issuer.
      tokenType - is the type of the token.
      Returns:
      issuer string
      Throws:
      Exception
    • createTokenElement

      public static Element createTokenElement(String token, String tokenType) throws Exception
      Generate the element object based on the token passed in Supported token types are: 1. urn:ietf:params:oauth:token-type:jwt
      Parameters:
      token - to be used to generate the Element Object.
      tokenType - is the type of the token.
      Returns:
      Element object
      Throws:
      Exception
    • parseSTSUUToJson

      public static String parseSTSUUToJson(STSUniversalUser sts, String tokenType, String universalNameMapJson) throws Exception
      Parse the attribute in STSUU object to a JSON.
      Parameters:
      sts - is the STSUU object which contains the attribute.
      tokenType - is the type of the token.
      universalNameMapJson - is the JSON string which contains the universal and original name mapping.
      Returns:
      JSON String
      Throws:
      Exception
    • storeJwtActor

      public static void storeJwtActor(String act, String stateId) throws Exception
      Store the JWT token "act" claims into OAuth Token extra attributes table.
      Parameters:
      act - is the "act" claims in the jwt token.
      stateId - is the State ID of the authorization grant.
      Throws:
      Exception
    • retrieveActor

      public static String retrieveActor(String stateId)
      Retrieve the act claims from the OAuth Token extra attributes table.
      Parameters:
      stateId - is State ID of the authorization grant.
      Returns:
      JSON String
    • createUUID

      public static String createUUID()
      Create a UUID String
      Returns:
      UUID string