SessionManagement Class

Contains methods for verifying users’ identity, creating custom login flows, customizing security levels, and defining 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 user identity verification flows, manage the use of time-based one-time password (TOTP) apps like Google Authenticator, or create custom login flows. Other methods validate a user’s incoming IP address against trusted IP range settings for an organization or profile.

finishLoginFlow()

Finish the Visualforce Page login flow process, and redirect the user to the default home page.

Signature

public static System.PageReference finishLoginFlow()

Return Value

Type: System.PageReference

Usage

Include this method in the Apex controller of the Visualforce Page login flow when creating login flows programmatically. This method indicates that the login flow is finished and redirects the user to the community’s default home page. The login process runs in a restricted session until users complete the process. Calling this method indicates that the login flow is complete, lifts the restriction, and gives users full access to the community.

finishLoginFlow(startUrl)

Finish the Visualforce Page login flow process, and redirect the user to the specified start URL.

Signature

public static System.PageReference finishLoginFlow(String startUrl)

Parameters

startUrl
Type: String
Path to the page that users see when they access the community.

Return Value

Type: System.PageReference

Usage

Include this method in the Apex controller of the Visualforce Page login flow when creating login flows programmatically. This method indicates that the login flow is finished and redirects the user to the specified location in the community. The login process runs in a restricted session until users complete the process. Calling this method indicates that the login flow is complete, lifts the restriction, and gives users full access to the community.

generateVerificationUrl(policy, description, destinationUrl)

Initiates a user identity verification flow with the verification method that the user registered with, and returns a URL to the identity verification screen. For example, if you have a custom Visualforce page that displays sensitive account details, you can prompt the user to verify identity before viewing it.

Signature

public static String generateVerificationUrl(Auth.VerificationPolicy policy, String description, String destinationUrl)

Parameters

policy
Type: Auth.VerificationPolicy
The session security policy required to initiate identity verification for the user’s session. For example, if the policy is set to High Assurance level of session security, and the user’s current session has the standard level of session security, the user’s session is raised to high assurance after successful verification of identity. In the Setup user interface, this value is shown in the Triggered By column of Identity Verification History.
description
Type: String
The custom description that describes the activity requiring identity verification; for example, “Complete purchase and check out”. This text appears to users when they verify their identity in Salesforce and, if they use Salesforce Authenticator version 2 or later, in the Salesforce Authenticator mobile app. In addition, in the Setup user interface, this text is shown in the Activity Message column of Identity Verification History.
destinationUrl
Type: String
The relative or absolute Salesforce URL that you want to redirect the user to after identity verification—for example, /apex/mypage. The user is redirected to destinationUrl when the identity verification flow is complete, regardless of success. For example, if a user chooses to not respond to the identity challenge and cancels it, the user is still redirected to destinationUrl. As a best practice, ensure that your code for this page manually checks that the security policy was satisfied (and the user didn’t just manually type the URL in the browser). For example, if the policy is High Assurance, the target page checks that the user's session is high assurance before allowing access.

Return Value

Type: String

The URL where the user is redirected to verify identity.

Usage

  • If the user is already registered to confirm identity using a time-based one-time password (TOTP), then the user is redirected to the one-time password identity verification flow and asked to provide a code.
  • If the user isn’t registered with any verification method (such as one-time password or Salesforce Authenticator version 2 or later), the user is prompted to download and verify identity using Salesforce Authenticator. The user can also choose a different verification method.

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}

getRequiredSessionLevelForProfile(profileId)

Indicates the required login security session level for the given profile.

Signature

public static Auth.SessionLevel getRequiredSessionLevelForProfile(String profileId)

Parameters

profileId
Type: String

The 15-character profile ID.

Return Value

Type: Auth.SessionLevel

The session security level required at login for the profile with the ID profileId. You can customize the assignment of each level in Session Settings. For example, you can set the High Assurance level to apply only to users who authenticated with two-factor authentication or through a specific identity provider.

ignoreForConcurrentSessionLimit(sessions)

This method is reserved for internal Salesforce use.

Signature

public static Map<String,String> ignoreForConcurrentSessionLimit(Object sessions)

Parameters

sessions
Type: Object

Return Value

Type: Map<String, String>

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 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)

Deprecated. Use validateTotpTokenForKey(totpSharedKey, totpCode, description) instead.

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.

validateTotpTokenForKey(totpSharedKey, totpCode, description)

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

Signature

public static Boolean validateTotpTokenForKey(String totpSharedKey, String totpCode, String description)

Parameters

totpSharedKey
Type: String
The shared (secret) key. The totpSharedKey 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.
description
Type: String
The custom description that describes the activity requiring identity verification; for example, “Complete purchase and check out”. In the Setup user interface, this text is shown in the Activity Message column of Identity Verification History. The description must be 128 characters or fewer. If you provide a value that’s longer, it’s truncated to 128 characters.

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)

Deprecated. Use validateTotpTokenForUser(totpCode, description) instead.

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.

validateTotpTokenForUser(totpCode, description)

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

Signature

public static Boolean validateTotpTokenForUser(String totpCode, String description)

Parameters

totpCode
Type: String
The time-based one-time password (TOTP) code to validate.
description
Type: String
The custom description that describes the activity requiring identity verification; for example, “Complete purchase and check out”. This text appears to users when they verify their identity in Salesforce and, if they use Salesforce Authenticator version 2 or later, in the Salesforce Authenticator mobile app. In addition, in the Setup user interface, this text is shown in the Activity Message column of Identity Verification History. The description must be 128 characters or fewer. If you provide a value that’s longer, it’s truncated to 128 characters.

Return Value

Type: Boolean

Usage

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