SessionManagement Class

Contains methods for customizing security levels, two-factor authentication, and trusted IP ranges for a current session.

Namespace

Auth

SessionManagement Methods

The following are methods for SessionManagement. All methods are static. Use these methods to customize your two-factor authentication implementation and manage the use of time-based one-time password (TOTP) apps like Google Authenticator with a Salesforce organization. Or, use them to validate a user’s incoming IP address against trusted IP range settings for an organization or profile.

getCurrentSession()

Returns a map of attributes for the current session.

Signature

public static Map<String, String> getCurrentSession()

Return Value

Type: Map<String, String>

Usage

The map includes a ParentId value, which is the 18-character ID for the parent session, if one exists (for example, if the current session is for a canvas app). If the current session doesn’t have a parent, this value is null. The map also includes the LogoutUrl assigned to the current session.
Note

Note

When a session is reused, Salesforce updates the LoginHistoryId with the value from the most recent login.

Example

The following example shows the name-value pairs in a map returned by getCurrentSession(). Note that UsersId includes an “s” in the name to match the name of the corresponding field in the AuthSession object.

{
SessionId=0Ak###############, 
UserType=Standard, 
ParentId=0Ak###############, 
NumSecondsValid=7200, 
LoginType=SAML Idp Initiated SSO, 
LoginDomain=null,
LoginHistoryId=0Ya###############,
Username=user@domain.com, 
CreatedDate=Wed Jul 30 19:09:29 GMT 2014, 
SessionType=Visualforce, 
LastModifiedDate=Wed Jul 30 19:09:16 GMT 2014, 
LogoutUrl=https://google.com, 
SessionSecurityLevel=STANDARD,
UsersId=005###############, 
SourceIp=1.1.1.1
}

getQrCode()

Returns a map containing a URL to a quick response (QR) code and a time-based one-time password (TOTP) shared secret to configure two-factor authentication apps or devices.

Signature

public static Map<String, String> getQrCode()

Return Value

Type: Map<String, String>

Usage

The QR code encodes the returned secret as well as the current user's username. The keys are qrCodeUrl and secret. Calling this method does not change any state for the user, nor does it read any state from the user. This method returns a brand new secret every time it is called, does not save that secret anywhere, and does not validate the TOTP token. The admin must explicitly save the values for the user after verifying a TOTP token with the secret.

The secret is a base32-encoded string of a 20-byte shared key.

Example

The following is an example of how to request the QR code.

public String getGetQRCode() {
        return getQRCode();
    }
    public String getQRCode() { 
       Map<String, String> codeResult = Auth.SessionManagement.getQrCode();
       String result = 'URL: '+codeResult.get('qrCodeUrl') + ' SECRET:  ' + codeResult.get('secret');
       return result;
    }

The following is an example of a returned map.

{qrCodeUrl=https://www.salesforce.com/secur/qrCode?w=200&h=200&t=tf&u=user%0000000000.com&s=AAAAA7B5BBBB5AAAAAAA66BBBB,
      secret=AAAAA7B5AAAAAA5BBBBBBBBB66AAA}

inOrgNetworkRange(ipAddress)

Indicates whether the given IP address is within the organization's trusted IP range according to the organization's Network Access settings.

Signature

public static Boolean inOrgNetworkRange(String ipAddress)

Parameters

ipAddress
Type: String
The IP address to validate.

Return Value

Type: Boolean

Usage

If a trusted IP range is not defined, this returns false, and throws an exception if the IP address is not valid.
Trusted IP Range Exists? User is in the Trusted IP Range? Return Value
Yes Yes true
Yes No false
No N/A false

isIpAllowedForProfile(profileId, ipAddress)

Indicates whether the given IP address is within the trusted IP range for the given profile.

Signature

public static Boolean isIpAllowedForProfile(String profileId, String ipAddress)

Parameters

profileId
Type: String
The 15-character alphanumeric string for the current user’s profile ID.
ipAddress
Type: String
The IP address to validate.

Return Value

Type: Boolean

Usage

If a trusted IP range is not defined, this returns true, and throws an exception if the IP address is not valid or if the profile ID is not valid.
Trusted IP Range Exists? User is in the Trusted IP Range? Return Value
Yes Yes true
Yes No false
No N/A true

setSessionLevel(level)

Sets the user's current session security level.

Signature

public static Void setSessionLevel(Auth.SessionLevel level)

Parameters

level
Type: Auth.SessionLevel
The session security level to assign to the user. The meaning of each level can be customized in the Session Settings for each organization, such as setting the High Assurance level to apply only to users who authenticated with two-factor authentication or through a specific identity provider.

Return Value

Type: Void

Usage

This setting affects the session level of all sessions associated with the current session, such as Visualforce, Salesforce Files Sync, or UI access.

Example

The following is an example class for setting the session level.

public class RaiseSessionLevel{ 
    public void setLevelHigh() { 
        Auth.SessionManagement.setSessionLevel(Auth.SessionLevel.HIGH_ASSURANCE); 
    }
    public void setLevelStandard() { 
        Auth.SessionManagement.setSessionLevel(Auth.SessionLevel.STANDARD); 
    } 
}

validateTotpTokenForKey(sharedKey, totpCode)

Indicates whether a given time-based one-time password (TOTP) code (token) is valid for the given shared key.

Signature

public static Boolean validateTotpTokenForKey(String sharedKey, String totpCode)

Parameters

sharedKey
Type: String
The shared (secret) key. The sharedKey must be a base32-encoded string of a 20-byte shared key.
totpCode
Type: String
The time-based one-time password (TOTP) code to validate.

Return Value

Type: Boolean

Usage

If the key is invalid or doesn’t exist, this method throws an invalid parameter value exception or a no data found exception, respectively. If the current user exceeds the maximum of 10 token validation attempts, this method throws a security exception.

validateTotpTokenForUser(totpCode)

Indicates whether a given time-based one-time password (TOTP) code (token) is valid for the current user.

Signature

public static Boolean validateTotpTokenForUser(String totpCode)

Parameters

totpCode
Type: String
The time-based one-time password (TOTP) code to validate.

Return Value

Type: Boolean

Usage

If the current user does not have a TOTP code, this method throws an exception. If the current user has attempted too many validations, this method throws an exception.