SessionManagement Class

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.

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

Note

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.

1{
2SessionId=0Ak###############, 
3UserType=Standard, 
4ParentId=0Ak###############, 
5NumSecondsValid=7200, 
6LoginType=SAML Idp Initiated SSO, 
7LoginDomain=null,
8LoginHistoryId=0Ya###############,
9Username=user@domain.com, 
10CreatedDate=Wed Jul 30 19:09:29 GMT 2014, 
11SessionType=Visualforce, 
12LastModifiedDate=Wed Jul 30 19:09:16 GMT 2014, 
13LogoutUrl=https://google.com, 
14SessionSecurityLevel=STANDARD,
15UsersId=005###############, 
16SourceIp=1.1.1.1
17}

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.

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.

1public String getGetQRCode() {
2        return getQRCode();
3    }
4    public String getQRCode() { 
5       Map<String, String> codeResult = Auth.SessionManagement.getQrCode();
6       String result = 'URL: '+codeResult.get('qrCodeUrl') + ' SECRET:  ' + codeResult.get('secret');
7       return result;
8    }

The following is an example of a returned map.

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

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, Salesforce Files Sync, or UI access.

Example

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

1public class RaiseSessionLevel{ 
2    public void setLevelHigh() { 
3        Auth.SessionManagement.setSessionLevel(Auth.SessionLevel.HIGH_ASSURANCE); 
4    }
5    public void setLevelStandard() { 
6        Auth.SessionManagement.setSessionLevel(Auth.SessionLevel.STANDARD); 
7    } 
8}

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.

Apex Developer Guide

Namespace

SessionManagement Methods

generateVerificationUrl(policy, description, destinationUrl)

Signature

Parameters

Return Value

Usage

getCurrentSession()

Signature

Return Value

Usage

Example

getRequiredSessionLevelForProfile(profileId)

Signature

Parameters

Return Value

getQrCode()

Signature

Return Value

Usage

Example

ignoreForConcurrentSessionLimit(sessions)

Signature

Parameters

Return Value

inOrgNetworkRange(ipAddress)

Signature

Parameters

Return Value

Usage

isIpAllowedForProfile(profileId, ipAddress)

Signature

Parameters

Return Value

Usage

setSessionLevel(level)

Signature

Parameters

Return Value

Usage

Example

validateTotpTokenForKey(sharedKey, totpCode)

Signature

Parameters

Return Value

Usage

validateTotpTokenForKey(totpSharedKey, totpCode, description)

Signature

Parameters

Return Value

Usage

validateTotpTokenForUser(totpCode)

Signature

Parameters

Return Value

Usage

validateTotpTokenForUser(totpCode, description)

Signature

Parameters

Return Value

Usage