Class IDMappingExtUtils

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

public class IDMappingExtUtils extends Object
Implementation for STS Mapping Extension Functions. These functions can be called from XSLT mapping rules by declaring the following in the root <xsl:stylesheet> element: xmlns:mapping-ext="com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils" extension-element-prefixes="mapping-ext" Then using the following format in the body of the mapping rule: invalid input: '<'xsl:value-of select="mapping-ext:throwSTSException('foo')" />
  • Field Details

  • Constructor Details

    • IDMappingExtUtils

      public IDMappingExtUtils()
  • 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.
      Parameters:
      message -
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • throwSTSUserMessageException

      public static void throwSTSUserMessageException(String message) throws com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
      Used to throw STSUserMessageException from XSLT/Javascript mapping rules The error message of this exception is displayed in the response to the client.
      Parameters:
      message -
      Throws:
      com.tivoli.am.fim.trustserver.sts.utilities.STSUserMessageException
    • translatePPID

      public static String translatePPID(String ppid)
      Tranlates a base64 encoded PPID string into a friendly display format according to the Information Card specifications. If the input string cannot be translated for any reason, the input string will be returned.
      Parameters:
      ppid -
      Returns:
      String
    • subStringAfterLast

      public static String subStringAfterLast(String text, String chars)
      Returns the substring of text after the last occurence of chars. If chars is not present in text, returns text. If chars is same as text, or occurs at end of text, returns the empty string.
      Parameters:
      text -
      chars -
      Returns:
      String
    • subStringBeforeLast

      public static String subStringBeforeLast(String text, String chars)
      Returns the substring of text before the last occurence of chars. If chars is not present in text, returns text. If last occurence of chars is at start of text, returns the empty string.
      Parameters:
      text -
      chars -
      Returns:
      String
    • parseRequestedClaims

      public static com.tivoli.am.fim.trustserver.sts.utilities.InfoCardClaim[] parseRequestedClaims(String claimsNode)
      Recursively searches the XML contained in the passed-in string looking for elements which have this format:
                                   <wsid:ClaimType
                                   xmlns:wsid="http://schemas.xmlsoap.org/ws/2005/05/identity"
                                   Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
                                   Optional="true" />
      
       
      If it finds elements that match this qname, they will be added to the result set. If the passed in string cannot be parsed as XML, an empty array will be returned.
      Parameters:
      claimsNode -
      Returns:
    • parseQueryServiceAttributes

      public static QueryServiceAttribute[] parseQueryServiceAttributes(String claimsNode)
      Recursively searches the XML contained in the passed-in string looking for elements which have this format:
                                   <fimqs:Attribute
                                   xmlns:fimqs="urn:ibm:names:ITFIM:queryservice"
                                   name="openid.sreg.email"
                                   type="whatever&quote
                                   optional="true" />
      
       
      If it finds elements that match this qname, they will be added to the result set. If the passed in string cannot be parsed as XML, an empty array will be returned.
      Parameters:
      claimsNode -
      Returns:
    • addAliasForUser

      public static boolean addAliasForUser(String fedContextId, String username, String alias) throws com.tivoli.am.fim.trustserver.sts.STSException
      addAliasForUser will store a mapping from the given federation context id and username to the given alias. The federation context identifier should be an identifier which scopes the mapping of the username to the alias. This method adds the alias to the "SELF" category.
      Parameters:
      fedContextId - - the federation context id
      username - - the TFIM username
      alias - - the alias to associate with the username within the given federation context id
      Returns:
      - true if the storage of the alias succeeded, false otherwise
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • addAliasForUser

      public static boolean addAliasForUser(String fedContextId, String username, String alias, String aliasType) throws com.tivoli.am.fim.trustserver.sts.STSException
      addAliasForUser will store a mapping from the given federation context id and username to the given alias. The federation context identifier should be an identifier which scopes the mapping of the username to the alias.
      Parameters:
      fedContextId - - the federation context id
      username - - the TFIM username
      alias - - the alias to associate with the username within the given federation context id
      aliasType - - the type of alias to add. Must be "self", "partner", or "old".
      Returns:
      - true if the storage of the alias succeeded, false otherwise
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeAliasForUser

      public static boolean removeAliasForUser(String fedContextId, String username, String alias) throws com.tivoli.am.fim.trustserver.sts.STSException
      removeAliasForUser will remove a mapping from the given federation context id and username for the given alias. The federation context identifier should be an identifier which scopes the mapping of the username to the alias. This method removes the alias from the "self" category.
      Parameters:
      fedContextId - - the federation context id
      username - - the TFIM username
      alias - - the alias associated with the username within the given federation context id
      Returns:
      - true if the removal of the alias mapping succeeded (or the alias was not associated with the username in the given federation context), false otherwise
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeAliasForUser

      public static boolean removeAliasForUser(String fedContextId, String username, String alias, String aliasType) throws com.tivoli.am.fim.trustserver.sts.STSException
      removeAliasForUser will remove a mapping from the given federation context id and username for the given alias. The federation context identifier should be an identifier which scopes the mapping of the username to the alias.
      Parameters:
      fedContextId - - the federation context id
      username - - the TFIM username
      alias - - the alias associated with the username within the given federation context id
      aliasType - - the type of alias to remove, must be "self", "partner", or "old".
      Returns:
      - true if the removal of the alias mapping succeeded (or the alias was not associated with the username in the given federation context), false otherwise
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • lookupUserFromAlias

      public static String lookupUserFromAlias(String fedContextId, String alias) throws com.tivoli.am.fim.trustserver.sts.STSException
      Finds and returns the user associated with the given alias within the given federation context id (scope of the alias->username mapping). This method returns "SELF" aliases only.
      Parameters:
      fedContextId - - the federation context id
      alias - - the alias of the associated user within the given federation context id
      Returns:
      - The username if the alias was mapped to a user, or the empty string if the alias could not be mapped to a user
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • lookupUserFromAlias

      public static String lookupUserFromAlias(String fedContextId, String alias, String aliasType) throws com.tivoli.am.fim.trustserver.sts.STSException
      Finds and returns the user associated with the given alias within the given federation context id (scope of the alias->username mapping).
      Parameters:
      fedContextId - - the federation context id
      alias - - the alias of the associated user within the given federation context id
      aliasType - - the type of alias to search for. Valid values are "self", "parnter", or "old".
      Returns:
      - The username if the alias was mapped to a user, or the empty string if the alias could not be mapped to a user
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • lookupAliasesForUserAsStringArray

      public static String[] lookupAliasesForUserAsStringArray(String fedContextId, String username) throws com.tivoli.am.fim.trustserver.sts.STSException
      Returns the list of aliases associated with a given username within a given federation context id.
      Parameters:
      fedContextId - - the federation context id
      username - - the username for which to search for aliases
      Returns:
      The list of aliases for the user within the given federation context id, otherwise an empty array.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • lookupAliasesForUserAsStringArray

      public static String[] lookupAliasesForUserAsStringArray(String fedContextId, String username, String aliasType) throws com.tivoli.am.fim.trustserver.sts.STSException
      Returns the list of aliases associated with a given username within a given federation context id.
      Parameters:
      fedContextId - - the federation context id
      username - - the username for which to search for aliases
      aliasType - - the type of alias to search.
      Returns:
      The list of aliases for the user within the given federation context id, otherwise an empty array.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • lookupAliasesForUserAsDelimitedString

      public static String lookupAliasesForUserAsDelimitedString(String fedContextId, String username, String delimiter) throws com.tivoli.am.fim.trustserver.sts.STSException
      Returns the list of aliases associated with a given username within a given federation context id. The aliases are returned in a single string, separated by a user-supplied delimiter. This is useful for XSLT mapping rules that may want to use this as an extension function since they cannot manage an array return value.
      Parameters:
      fedContextId - - the federation context id
      username - - the username for which to search for aliases
      delimiter - - the string delimiter to put between aliases in the return value
      Returns:
      The list of aliases for the user within the given federation context id, otherwise an empty array.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • lookupAliasesForUserAsDelimitedString

      public static String lookupAliasesForUserAsDelimitedString(String fedContextId, String username, String delimiter, String aliasType) throws com.tivoli.am.fim.trustserver.sts.STSException
      Returns the list of aliases associated with a given username within a given federation context id. The aliases are returned in a single string, separated by a user-supplied delimiter. This is useful for XSLT mapping rules that may want to use this as an extension function since they cannot manage an array return value.
      Parameters:
      fedContextId - - the federation context id
      username - - the username for which to search for aliases
      delimiter - - the string delimiter to put between aliases in the return value
      aliasType - - the type of alias to lookup
      Returns:
      The list of aliases for the user within the given federation context id, otherwise an empty array.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • traceString

      public static void traceString(String str)
      Provides a convenient tracing mechanism for js mapping rule. You can invoke it like this: 1. import the package importPackage(Packages.com.tivoli.am.fim.trustserver.sts.utilities); 2. Call the method IDMappingExtUtils.traceString("str")
      Parameters:
      str - - String to trace
    • traceString

      public static void traceString(String str, Level level)
      Provides a convenient tracing mechanism for js mapping rule. You can invoke it like this: 1. import the package importPackage(Packages.com.tivoli.am.fim.trustserver.sts.utilities); 2. Call the method IDMappingExtUtils.traceString("str", java.util.logging.Level.INFO)
      Parameters:
      str -
      level - , If the null value is passed in, it will use the default value "FINER"
    • getCurrentTimeStringUTC

      public static String getCurrentTimeStringUTC()
      Returns the current time in UTC in XML format. As this timestamp will generally be consumed in OpenID federations with PAPE enabled, the generated timestamp does NOT contain a millisecond field.
      Returns:
    • getTimeStringUTC

      public static String getTimeStringUTC(int year, int month, int day, int hour, int minute, int second)
      Constructs a time string in XML format based on the specified year, month, day, hour, minute and second. The time specified is assumed to be in UTC aka Zulu time. Years must be fully specified (eg "1999" not "99").
      Parameters:
      year -
      month -
      day -
      hour -
      minute -
      second -
      timeZone -
      Returns:
    • getIDMappingExtCache

      public static IDMappingExtCache getIDMappingExtCache()
    • getIDMappingExtCache

      public static IDMappingExtCache getIDMappingExtCache(boolean useRedis)
      This method in the utility class provides flexibility for the customer to choose storage, i.e. Redis or HVBD
      Parameters:
      useRedis - ,if the value is false, it is stored in HVDB. if it is true, it will be stored in the Redis
      Returns:
      cache
    • getSPSSessionID

      public static String getSPSSessionID()
      Returns an id that is guaranteed to be consistent across multiple federation contexts within the Single Sign-On Protocol Service (SPS). This method will only return a value if the mapping module where it is being called from is part of a chain that has been invoked by the Single Sign-On Protocol Service (SPS) (a built-in federation, USC or OTP). This value can be used as a key to store state across federation contexts such as User Self Care (USC) and One Time Password (OTP).
      Returns:
      a session id for the Single Sign-on Protocol Service (SPS)
    • setSPSSessionData

      public static void setSPSSessionData(String key, String value)
      Stores a key/value String pair in the user's Single Sign-on Protocol Service (SPS) session
      Parameters:
      key - the key used to store the entry
      value - the value to store in the user's session
    • getSPSSessionData

      public static String getSPSSessionData(String key)
      Retrieves a String value from the user's Single Sign-on Protocol Service (SPS) session based on a key
      Parameters:
      key - the key used to retrieve the entry
      Returns:
      the value associated with this key in the user's session, or null if a value for the key doesn't exist
    • removeSPSSessionData

      public static String removeSPSSessionData(String key)
      Removes a String value from the user's Single Sign-on Protocol Service (SPS) session based on a key
      Parameters:
      key - the key used to remove the entry
      Returns:
      the value associated with this key in the user's session, or null if a value for the key doesn't exist
    • generateHmacSecretKey

      public static String generateHmacSecretKey(int keyLength) throws com.tivoli.am.fim.trustserver.sts.STSException
      Generate Hmac Secret Key for the length specified.
      Parameters:
      keyLengh - the length of the key to generate. The keyLength should be multiples of 5.
      Returns:
      the base32 encoded generate key
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • storeTotpSecretKey

      public static void storeTotpSecretKey(String user, String value) throws com.tivoli.am.fim.trustserver.sts.STSException
      Store an TOTP secret key for a user
      Parameters:
      user - - user name
      value - - secret key value to store
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • storeTotpSecretKey

      public static void storeTotpSecretKey(String user, String value, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      Store an TOTP secret key for a user
      Parameters:
      user - - user name
      value - - secret key value to store
      secretKeyNamespace - - secret key attribute namespace.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • storeHotpSecretKey

      public static void storeHotpSecretKey(String user, String value) throws com.tivoli.am.fim.trustserver.sts.STSException
      Store an HOTP secret key for a user
      Parameters:
      user - user name
      value - secret key value to store
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • storeHotpSecretKey

      public static void storeHotpSecretKey(String user, String value, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      Store an HOTP secret key for a user
      Parameters:
      user - user name
      value - secret key value to store
      secretKeyNamespace - - secret key attribute namespace.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • storeSecretKey

      public static void storeSecretKey(String otpFederation, String userInfoProviderType, String user, String secretKeyName, String secretKeyNamespace, String value) throws com.tivoli.am.fim.trustserver.sts.STSException
      Stores the secret key for a user given the secretKeyName, secretKeyNamespace and secretKeyDatatype.
      Parameters:
      otpFederation - OTP federation name or group id.
      userInfoProviderType - OTP user info provider type.
      user - user name
      secretKeyName - secret key attribute name.
      secretKeyNamespace - secret key attribute namespace.
      value - The secret key value to store
      secretKeyDatatype - secret key attribute datatype.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • retrieveTotpSecretKey

      public static String retrieveTotpSecretKey(String user) throws com.tivoli.am.fim.trustserver.sts.STSException
      Retrieve a TOTP Secret key for a user
      Parameters:
      user - the user to retrieve
      Returns:
      The users secret key.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • retrieveTotpSecretKey

      public static String retrieveTotpSecretKey(String user, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      Retrieve a TOTP Secret key for a user
      Parameters:
      user - the user to retrieve
      secretKeyNamespace - secret key attribute namespace
      Returns:
      The users secret key.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • retrieveHotpSecretKey

      public static String retrieveHotpSecretKey(String user) throws com.tivoli.am.fim.trustserver.sts.STSException
      Retrieve a HOTP Secret key for a user
      Parameters:
      user - the user to retrieve
      Returns:
      The users secret key.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • retrieveHotpSecretKey

      public static String retrieveHotpSecretKey(String user, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      Retrieve a HOTP Secret key for a user
      Parameters:
      user - the user to retrieve
      secretKeyNamespace - secret key attribute namespace
      Returns:
      The users secret key.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • retrieveSecretKey

      public static String retrieveSecretKey(String otpFederation, String userInfoProviderType, String user, String secretKeyName, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      Retrieves the secret key for a user given the secretKeyName and secretKeyNamespace.
      Parameters:
      otpFederation - OTP federation name or group id.
      userInfoProviderType - OTP user info provider type.
      user - user name
      secretKeyName - secret key attribute name.
      secretKeyNamespace - secret key attribute namespace.
      Returns:
      The retrieved secret key or null if not found.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeTotpSecretKey

      public static String removeTotpSecretKey(String user) throws com.tivoli.am.fim.trustserver.sts.STSException
      remove an TOTP secret key for a user
      Parameters:
      user - - user name
      Returns:
      the secret key removed.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeTotpSecretKey

      public static String removeTotpSecretKey(String user, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      remove an TOTP secret key for a user
      Parameters:
      user - - user name
      secretKeyNamespace - secret key attribute namespace.
      Returns:
      the secret key removed.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeHotpSecretKey

      public static String removeHotpSecretKey(String user) throws com.tivoli.am.fim.trustserver.sts.STSException
      remove an HOTP secret key for a user
      Parameters:
      user - - user name
      Returns:
      the secret key removed.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeHotpSecretKey

      public static String removeHotpSecretKey(String user, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      remove an HOTP secret key for a user
      Parameters:
      user - - user name
      secretKeyNamespace - secret key attribute namespace.
      Returns:
      the secret key removed.
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • removeSecretKey

      public static String removeSecretKey(String otpFederation, String userInfoProviderType, String user, String secretKeyName, String secretKeyNamespace) throws com.tivoli.am.fim.trustserver.sts.STSException
      Deletes the secret key for a user given the secretKeyName and secretKeyNamespace
      Parameters:
      otpFederation - OTP federation name or group id.
      userInfoProviderType - OTP user info provider type.
      user - user name
      secretKeyName - secret key attribute name.
      secretKeyNamespace - secret key attribute namespace.
      Returns:
      Always returns null
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • newXMLDocument

      public static Document newXMLDocument()
    • xmlElementToString

      public static String xmlElementToString(Element element)
    • stringToXMLElement

      public static Element stringToXMLElement(String string) throws com.tivoli.am.fim.trustserver.sts.STSException
      Throws:
      com.tivoli.am.fim.trustserver.sts.STSException
    • sleep

      public static void sleep(long timeInMillis)
      Sleep for a number of milliseconds.
      Parameters:
      timeInMillis - to sleep for
    • extractBinarySecurityToken

      public static String extractBinarySecurityToken(Node node)
      Extract Binary Security Token from STS exchange result.
      Parameters:
      Node - containing BinarySecurityToken element.
    • logCISelfCareAuditEvent

      public static void logCISelfCareAuditEvent(String username, String action, String serverConnection, String rule, String failureReason)
      CI Audit Self Care - Generate CI Self Care audit log event
      Parameters:
      username - user information to include in the audit record; may be null
      action - the self care action to include in the audit record
      serverConnection - the server connection to include in the audit record
      rule - the rule to include in the audit record
      failureReason - the failure reason. set to null if the operation being audited was successful
      Since:
      9.0.5.0
    • logCIAuthAuditEvent

      public static void logCIAuthAuditEvent(String username, String authMethod, String serverConnection, String rule, boolean result, String statusCode, String correlation)
      CI Audit Authentication - Generate CI Auth audit log event
      Parameters:
      username - user information to include in the audit record; may be null
      authMethod - the auth method to include in the audit record
      serverConnection - the server connection to include in the audit record
      rule - the rule to include in the audit record
      result - boolean to indicate if the operation being audited was successful
      statusCode - code to include if the operation being audited was unsuccessful
      Since:
      9.0.5.0
    • logAuditEvent

      public static void logAuditEvent(String username, String message, boolean result)
      Audit - Generate audit log event
      Parameters:
      username - user information to include in the audit record; may be null
      message - the message to include in the audit record
      result - boolean to indicate if the operation being audited was successful
      Since:
      9.0.6.0
    • escapeHtml

      public static String escapeHtml(String s)
      Convert a subset of characters to XML and HTML safe escape sequences. The chars that are escaped by this method are: invalid input: '<' > " invalid input: '&'
      Since:
      10.0.4.0