Apex Reference Guide
jRegistrationHandler Interface
Namespace
Usage
RegistrationHandler Methods
The following are methods for RegistrationHandler.
createUser(portalId, userData)
Signature
public User createUser(ID portalId, Auth.UserData userData)
Parameters
- portalId
- Type: ID
- userData
- Type: Auth.UserData
Return Value
Type: User
updateUser(userId, portalId, userData)
Signature
public Void updateUser(ID userId, ID portalId, Auth.UserData userData)
Parameters
- userId
- Type: ID
- portalId
- Type: ID
- userData
- Type: Auth.UserData
Return Value
Type: Void
Storing User Information and Getting Access Tokens
The Auth.UserData class is used to store user information for Auth.RegistrationHandler. The third-party identity provider can send back a large collection of data about the user, including their username, email address, locale, and more. The Salesforce authentication provider framework converts this data into a common format with the Auth.UserData class and then sendsit to the registration handler.
If the registration handler wants to use the rest of the data, the Auth.UserData class has an attributeMap variable. The attribute map is a map of strings (Map<String, String>) for the raw values of all the data from the third party. Because the map is <String, String>, values that the third party returns that aren't strings (like an array of URLs or a map) are converted into an appropriate string representation. The map includes everything returned by the third-party authentication provider, including the items automatically converted into the common format.
To learn about Auth.UserData properties, see Auth.UserData Class.
For all authentication providers except Janrain, after a user is authenticated using a provider, the access token associated with that provider for this user can be obtained in Apex using the Auth.AuthToken Apex class. Auth.AuthToken provides two methods to retrieve access tokens. One is getAccessToken, which obtains a single access token. Use this method if the user ID is mapped to a single third-party user. If the user ID is mapped to multiple third-party users, use getAccessTokenMap, which returns a map of access tokens for each third-party user. For more information about authentication providers, see Authentication Providers in Salesforce Help.
When using Janrain as an authentication provider, you must use the Janrain accessCredentials dictionary values to retrieve the access token or its equivalent. Only some providers supported by Janrain provide an access token, while other providers use other fields. The Janrain accessCredentials fields are returned in the attributeMap variable of the Auth.UserData class. See the Janrain auth_info documentation for more information on accessCredentials.
To learn about the Auth.AuthToken methods, see Auth.AuthToken Class.
User Information in the ID Token and User Info Response
Some identity providers send additional user information in an ID token or in a user info response. To extract user information from these responses, there are some extra steps.
An ID token is formatted as a JWT and includes information about the authenticated user. If the identity provider sends an ID token, Salesforce stores the full encoded JWT in the idToken property. Salesforce also stores the decoded JWT payload of the ID token in the idTokenJSONString property.
Salesforce doesn't validate the ID token. To validate it, use methods in the Auth.JWTUtil class and pass in the encoded JWT stored in the idToken property. The methods in the Auth.JWTUtil class all return an instance of the Auth.JWT object.
Once you validate the JWT, you can use methods in the Auth.JWT class to access specific claims. For example, the Apex code in this snippet validates the ID token using a public keys endpoint from the identity provider and then retrieves the value of an email claim stored in the token.
Alternatively, to access specific claims in the idTokenJSONString property, you can deserialize the JSON string and then write code to retrieve the claim you want. To deserialize the idTokenJSONString, use the JSON.deserialize (jsonString, apexType) method in the System.JSON class.
The user info response, if returned by the identity provider, is also a JSON object that has been serialized into a string. The user info response is stored in the userInfoJSONString property. You can use the JSON.deserialize (jsonString, apexType) method to deserialize the user info response so that you can retrieve specific information.
This example snippet creates a custom class to store the user info response. It then deserializes the user info response in the userInfoJSONString into this custom class structure.
Auth.RegistrationHandler Example Implementation
This example implements the Auth.RegistrationHandler interface that creates as well as updates a standard user based on data provided by the authentication provider. Error checking has been omitted to keep the example simple.
The following example tests the above code.
Auth.RegistrationHandler Error Example
To limit this example to the custom exception, some code was omitted.