SessionManagement Class
Namespace
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.
finishLoginDiscovery(method, userId)
Signature
public static System.PageReference finishLoginDiscovery(Auth.LoginDiscoveryMethod method, Id userId)
Parameters
- method
- Type: Auth.LoginDiscoveryMethod LoginDiscoveryMethod Enum
- Verification method used with My Domain Login Discovery.
- userId
- Type: Id
- ID used to log in the user. The user must be active.
Return Value
Type: System.PageReference
Usage
Include this method when implementing the MyDomainLoginDiscoveryHandler interface to direct users to an authentication mechanism, and then log them in. If users enter a username in the login page, they are sent to the password page for authentication. If users are enrolled in Lightning Login, they are directed to the Salesforce Authenticator to authenticate. If users are SSO-enabled, they are sent to the suitable identity provider (IdP) to authenticate.
The calling user requires Manage Users permission. If the user passed in is frozen or inactive, the method throws an exception.
After implementing the MyDomainLoginDiscoveryHandler interface, register the Login Discovery handler from the My Domain Setup page. Under Authentication Configuration, select this handler from the list of Apex classes.
finishLoginFlow()
Signature
public static System.PageReference finishLoginFlow()
Return Value
Type: System.PageReference
Usage
finishLoginFlow(startUrl)
Signature
public static System.PageReference finishLoginFlow(String startUrl)
Parameters
- startUrl
- Type: String
- Path to the page that users see when they access the Experience Cloud site.
Return Value
Type: System.PageReference
Usage
generateVerificationUrl(policy, description, destinationUrl)
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.
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()
Signature
public static Map<String, String> getCurrentSession()
Usage
If you create an Apex test method that calls this method, the test fails with an error such as, “Unexpected Exception: Current session unavailable." An error occurs because there isn’t a session in the context through which the test is being run.
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
}
getLightningLoginEligibility(userId)
Signature
public static Auth.LightningLoginEligibility getLightningLoginEligibility(Id userId)
Parameters
- userId
- Type: Id
- ID of the user who is logging in.
Example
Auth.LightningLoginEligibility eligibility =
Auth.SessionManagement.getLightningLoginEligibility(id);
if (eligibility == Auth.LightningLoginEligibility.ELIGIBLE) {
// success
}
getQrCode()
Signature
public static Map<String, String> getQrCode()
Usage
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)
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 multi-factor authentication (MFA) or through a specific identity provider.
inOrgNetworkRange(ipAddress)
Signature
public static Boolean inOrgNetworkRange(String ipAddress)
Parameters
- ipAddress
- Type: String
- The IP address to validate.
Return Value
Type: Boolean
Usage
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)
Signature
public static Boolean isIpAllowedForProfile(String profileId, String ipAddress)
Parameters
Return Value
Type: Boolean
Usage
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)
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 multi-factor authentication (MFA) or through a specific identity provider.
Return Value
Type: Void
Usage
If you create an Apex test method that calls this method, the test fails with an error such as, “Unexpected Exception: Current session unavailable." An error occurs because there isn’t a session in the context through which the test is being run.
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)
Signature
public static Boolean validateTotpTokenForKey(String sharedKey, String totpCode)
Parameters
Return Value
Type: Boolean
Usage
validateTotpTokenForKey(totpSharedKey, totpCode, description)
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
validateTotpTokenForUser(totpCode)
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
validateTotpTokenForUser(totpCode, description)
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
verifyDeviceFlow(userCode, startUrl)
Signature
public static System.PageReference verifyDeviceFlow(String userCode, String startUrl)
Parameters
- userCode
- Type: String
-
Human-readable user code provided to the user by Salesforce. The user must enter this code at the verification URL to approve device access to Salesforce data.
- startURL
- Type: String
-
The URL for the page that the user is redirected to after successful login and approval of the device to access Salesforce data. If you don’t specify a start URL, the user is redirected to the Home page.
Return Value
Type:System.PageReference