User profile (v6.1)
When the user is successfully authenticated by pac4j, his data are retrieved from the identity provider and a user profile is built. His profile has:
- an identifier (
getId()
) - attributes (
getAttributes()
,getAttribute(name)
) - authentication-related attributes (
getAuthenticationAttributes()
,getAuthenticationAttribute(name)
) - roles (
getRoles()
) - permissions (
getPermissions()
) - a client name (
getClientName()
) - a remember-me nature (
isRemembered()
) - a linked identifier (
getLinkedId()
)
In fact, the root class of the profiles hierarchy is the UserProfile
. Though, it’s an abstract class which is never referenced and used directly.
The first user profile which must be considered is the CommonProfile
which defines the most common methods available in most profiles.
1) Identifier
Each user profile must have a unique identifier. Thus, when building the user profile, the pac4j clients use for the profile identifier a value enforcing uniqueness from the identity provider.
This works well accross the profiles provided from the same identity provider, though this can become a problem when using multiple identity providers. We could have a collision between the identifiers chosen from the identity provider. To avoid that issue, there is a “typed identifier” adding the profile class name before the profile identifier.
Example:
profile.getId() // 00001
profile.getTypedId() // org.pac4j.oauth.profile.facebook.FacebookProfile#00001
As the identifier must be a String
, you may use the ProfileHelper.sanitizeIdentifier
method to convert other Java types and remove the “typed” part of the identifier.
2) Attributes
User profiles have attributes, populated from the data retrieved from the identity provider (after conversion).
3) Authentication-related attributes
Some identity providers will include attributes related to the authentication itself, such as authentication method, time period for which the authentication is valid, or metadata about the identity provider. These attributes are stored seperately from the user’s attributes.
4) Roles and permissions
Roles and permissions can be added to the user profile via the addRole(role)
, addRoles(roles)
, addPermission(permission)
and addPermissions(permissions)
methods.
They are generally computed in an AuthorizationGenerator
.
5) Client name
During the login process, the name of the client is saved into the user profile via the setClientName(name)
method and can be retrieved later on via the getClientName()
method.
6) Remember-me
A user profile can be defined as remember-me as opposed to fully authenticated via the setRemembered(boolean)
method. The isRemembered()
method returns if the user profile is remembered.
7) Common methods of the CommonProfile
The CommonProfile
has the following methods:
Method | Type | Returns |
---|---|---|
getEmail() |
String |
The email attribute |
getFirstName() |
String |
The first_name attribute |
getFamilyName() |
String |
The family_name attribute |
getDisplayName() |
String |
The display_name attribute |
getUsername() |
String |
The username attribute |
getGender() |
Gender |
The gender attribute |
getLocale() |
Locale |
The locale attribute |
getPictureUrl() |
URI |
The picture_url attribute |
getProfileUrl() |
URI |
The profile_url attribute |
getLocation() |
String |
The location attribute |
asPrincipal() |
Principal |
An object containing the name of the current authenticated user |
isExpired() |
boolean |
false if the current profile is expired |
8) Profile definition
The profile class and attributes are defined via ProfileDefinition
implementations.
The setProfileFactory
method allows you to define the instance class to return for the user profile while the primary
and secondary
methods allow you to define attributes with their specific converters.
Many attribute converters already exists: BooleanConverter
, ColorConverter
… Check the org.pac4j.core.profile.converter package.
As a result, the newProfile
method returns a new class instance while the convertAndAdd
methods convert the attributes if there is an associated converter and adds them to the profile.
9) Profile hierarchy
In fact, most clients never return a CommonProfile
, but specific profiles like the FacebookProfile
, the OidcProfile
… which:
- (partially) override the common methods of the
CommonProfile
with specific implementations - add their specific getters for their specific attributes.
10) Linked identifier
Each user profile may have a linked identifier, it’s the identifier of another user profile. This way, both user profiles are linked and it allows you to authenticate via an account for a user
and load the linked user defined in the first user, especially by using the LoadLinkedUserAuthorizationGenerator
.