Default user schema

The following tables provide information about the default schema employed by the user entity type, the entity type included with each new Identity Cloud application (and, as such, each new Hosted Login implementation). Although you can add new attributes to the schema, ​Akamai​ strongly recommends that you do not remove any of the default attributes: in some cases, at least, removing attributes can disable Hosted Login functionality. For example, if you remove the [egal acceptances plural then you won't be able to employ the authorization.rules.legal_accepted authorization rule.

The new default schema differs from previous Identity Cloud schemas in at least two ways:

  • A number of user profile attributes (database fields) – including such attributes as  profiles.profile.bodyType.hairColor, profiles.profile.turnOffs, profiles.profile.happiestWhen, profiles.profile.scaredOf – have been removed from the schema. By removing these seldom-used attributes, the current schema contains about one-fourth the number of attributes found in the previous schema.

    But what if you need the profiles.profile.turnOffs attribute? That’s fine: you can add an attribute to a schema anytime you want.

  • A handful of new attributes – accountDeleteRequestTime, consents.marketing.granted, etc. – have been added to the schema. These new attributes are typically used with Hosted Login.

Let’s take a closer look at the attributes found in the new user schema.


Default attributes

Attributes (and attribute values) that the Identity Cloud automatically adds to all new user profiles. These attributes are added when a user profile is created, and the attribute values can never be changed: if a user is given the uuid 3580bf7c-0a73-4bc0-9636-b4193f810e74 then that user will always have the uuid 3580bf7c-0a73-4bc0-9636-b4193f810e74.

Attribute NameTypeDescription
idstringSimple, and globally-unique, identifier for the user account. For example:

13

In case you’re wondering, “globally unique” means that the id is unique within the given entity type. If you have more than one entity type, however, the same id could be used in each of those entity types. For example, entity types A, B, C, and D could each have a user with the id 13.
uuidstringUniversally-unique identifier for the user account. For example:

3580bf7c-0a73-4bc0-9636-b4193f810e74

A “universally unique” attribute means that the value can only be assigned to a single user. For example, out of all the millions of user accounts in the ​Akamai​ Identity Cloud, only one of those accounts can have the uuid 3580bf7c-0a73-4bc0-9636-b4193f810e74.
createdstringDate and time that the user account was created. For example:

2020-01-22 19:29:08.923204 +0000
lastUpdatedstringDate and time that the user profile was last updated. For example:

2020-01-22 19:29:08.923204 +0000

Note that, each time a user logs on, the lastUpdated attribute is updated; that’s because the act of logging on changes the value of the lastLogin attribute, and that counts as an update to the user profile.

If you need to make a change to a user profile but don't want to update the lastUpdated attribute, you can do so by using an API client that has been assigned the metadata feature. This type of client can only be created by ​Akamai​.

Top-level attributes

Top-level attributes are “stand-alone” attributes: attributes that are not part of a plural or object. To refer to one of these attributes, use the attribute name: accountDataRequestTime, accountDeleteRequestTime, birthday, etc.

Attribute NameTypeDescription
accountDataRequestTimedateTimeDate and time that a user requested a copy of their user profile data. For example:

2020-01-22 19:29:08.923204 +0000

This attribute helps organizations comply with article 15 of European Union’s General Data Protection Regulation (GDPR).

By default, accountDataRequestTime is set to a null value. When a user clicks the Send Me My Data button, data is not automatically sent to that user. Instead, the attribute value is updated to the date and time the request was made. Organizations need to periodically search for non-null instances of the accountDataRequestTime attribute and then send the user the requested data.
accountDeleteRequestTimedateTimeDate and time that a user requested that their user account and all its associated data be deleted. For example:

2020-01-22 19:29:08.923204 +0000

This attribute helps organizations comply with article 17 of European Union’s General Data Protection Regulation (GDPR).

By default, accountDeleteRequestTime is set to a null value. When a user clicks the Delete My Data button, the user profile is not automatically deleted. Instead, the attribute value is updated to the date and time the request was made. Organizations need to periodically search for non-null instances of the accountDeleteRequestTime attribute and then delete the account as requested.
birthdaydateUser’s date of birth. For example:

1989-12-19

For OpenID Connect users, this attribute is returned by the birthdate claim.
deactivateAccountdateTimeDate and time when the account was deactivated. For example:

2020-01-22 19:29:08.923204 +0000

Deactivating an account only prevents the user from logging on; it does not delete or otherwise change user data. To reactivate the account, simply set deactivateAccount to a null value.

It's important to note that putting any datetime value in this attribute instantly deactivates the account. Among other things, that means that you can't schedule an account for deactivation. For example, suppose today is November 5, 2020 and you want to deactivate an account on January 1, 2021. Consequently, you enter the following deactivation date:

2021-01-02 00:00:00.000000 +0000

However, as soon as you save the user profile the account will immediately be deactivated. That's because, any time a user tries to authenticate, Hosted Login only checks to see if a value of some kind has been entered for the deactivateAccount attribute. If it has, then the user is denied access regardless of the actual date that was entered. In other words, if you want this user to be able to log on until January 1, 2021 then you must wait until January 1, 2021 to update the deactivateAccount attribute and deactivate the account. Putting in a datetime value of January 1, 2021 will not cause Hosted Login to delay deactivation. It just doesn't work that way.

We should also point out that Hosted Login doesn’t provide a way for a user to deactivate his or her account: accounts can be deleted, but not deactivated. However, Hosted Login does respect the deactivateAccount attribute. If a user tries to log on with a deactivated account their login will be denied with following message:

User account is deactivated.
displayjsonPlaceholder attribute used for data that can be made publicly available; all data stored in this attribute must be formatted using JSON (JavaScript Object Notation). For example:

{"nickname": "K-Man"}
displayNamestringName by which the user wants to be referred to. For example:

Karim Nafir

This attribute is returned by the preferred_username claim.
emailstringUser’s primary mail address. For example:

karim.nafir@mail.com

This attribute is returned by the email claim.
emailVerifieddateTimeDate and time when the user’s primary email address was verified. For example:

2020-01-22 19:29:08.923204 +0000

Any timestamp indicates that the email address has been verified. A null value means that the address has not been verified.

This attribute is returned as a Boolean value (true or false) for the email_verified claim.
externalIdstringPlaceholder attribute for storing an identifier returned from an external source (e.g., a Customer Relationship Management system). For example:

KN-07121967
familyNamestringSurname (last name) of the user. For example:

Nafir

Note that users can have more than one last name:

Williamson Smith

This attribute is returned by the family_name claim.
fullNamestringUser’s full name, including all titles and suffixes, and ordered according to the user’s locale and preferences. For example:

Dr. Karim Nafir, Jr.

This attribute is returned by the name claim.
genderstringUser’s preferred gender. For example:

male

Note that you are not limited to male and female when assigning a value to this attribute: the gender attribute accepts any string value.

This attribute is returned by the gender claim.
givenNamestringGiven name (first name) of the user. For example:

Karim

Note that users can have more than one first name:

Sue Ann

This attribute is returned by the given_name claim.
lastLogindateTimeDate and time that the user was last authenticated. For example:

2020-01-22 19:29:08.923204 +0000
middleNamestringMiddle name of the user. For example:

Alexander

Note that users can have more than one middle name:

Robert Williams

This attribute is returned by the middle_name claim.
mobileNumberstringNumber for the user’s cellphone or other mobile device. For example:

+155509031935
mobileNumberVerifieddateTimeDate and time when the user’s mobile phone number was verified. For example:

2020-01-22 19:29:08.923204 +0000
passwordUser’s password. Note that the password value will be null if the user only authenticates by using third-party identity providers. If you are viewing user information in Console, the user’s password will always be shown as a set of asterisks:

*****

If you use the /entity endpoint to return the user password, you’ll get back a hashed version of that password:

"password": {
"value": "$2a$10$6n9/1ns5RPTA8GZe8bkl0
Onc63dprlhOzdpjk3CERedzA78CNbntW",
"type": "password-bcrypt"
}

The password type will vary depending on the hashing algorithm used to store the password.

Clients plural

The clients plural tracks the different API clients that a user has employed when being authenticated. When referring to an individual attribute, be sure to use the full attribute path: clients.clientId, clients.firstLogin, etc.

Attribute NameTypeDescription
clientIdstringUnique identifier of the Identity Cloud API client used to help authenticate the user. For example:

tebr9hf28fa4grpe3c9qpz4xdaehbjn3
firstLogindateTimeDate and time when the user was first authenticated using this Identity Cloud API client. For example:

2020-01-22 19:29:08 +0000
lastLogindateTimeDate and time when the user was last authenticated using this Identity Cloud API client. For example:

2020-01-22 19:29:08 +0000
namestringName of the Identity Cloud API client used when authenticating the user. For example:

US Logins
idstringUnique identifier of the Identity Cloud API client for this user. For example:

1018

Consents object

Tracks the consent agreements used in your organization, and indicates whether the user agreed to any of those consents. By default the schema includes a single marketing object provisioned as part of the consents object. That means that, to refer to an individual attribute, you’ll need to use syntax like this: consents.marketing.granted. The consents object is required in order to implement the authorization.rules.consents.

Attribute NameTypeDescription
clientIdstringUnique identifier of the API client in use when the consent was last modified. For example:

tebr9hf28fa4grpe3c9qpz4xdaehbjn3
contextstringActivity underway when the consent was changed. For example:

profileUpdate
grantedbooleanBoolean value indicating whether or not the user accepted the consent. For example:

true
typestringType of consent. The Identity Cloud supports two types of consent: explicit and implicit. An explicit consent means that the user was specifically given the option to agree or disagree to having their personal information collected, used, or disclosed.

By comparison, implicit consent is not directly given but is, instead, inferred from your actions. For example, if you give an organization the right to use your personal information for marketing purposes, it is reasonable to assume that you have implicitly given them the right to send you marketing email.

For example:

explicit
updateddateTimeDate and time that the consent was last updated. For example:

2020-01-22 19:29:08 +0000

Legal acceptances plural

Tracks the legal agreements used in your organization as well as whether a user has  accepted any of those agreements. To refer to an individual attribute, use syntax like this: legalAcceptances.dateAccepted. The legalAcceptances plural is required in order to implement the authorization.rules.legal_accepted](doc:hosted-login-authorization-rules).

Attribute NameTypeDescription
clientIdstringUnique identifier of the API client in use when the user accepted a legal document. For example:

tebr9hf28fa4grpe3c9qpz4xdaehbjn3
dateAccepteddateTimeDate and time when a legal document was accepted by the user. For example:

2020-01-22 19:29:08 +000
legalAcceptanceIdstringUnique identifier for a legal document. For example:

termsOfService-v1
idstringUnique identifier for this legal acceptance, for this user. For example:

2948

Photos plural

Maintains information about the photos used in a user profile. To refer to an individual attribute, use syntax like this: photos.value.

Attribute NameTypeDescription
typestringType of photo (large, thumbnail, etc.). For example:

large
valuestringURL of the photo. For example:

https://lh3.googleusercontent.com/a-/123456789012345678901
idstringUnique identifier for this photo, for this user. For example:

0219

Primary address object

Provides information about a user’s preferred address. To refer to an individual attribute, use syntax like this: primaryAddress.country.

Attribute NameTypeDescription
address1stringFirst line of the user’s preferred address. For example:

1233 NW 12th Ave
address2stringSecond line of the user’s preferred address. For example:

Suite 150
citystringName of the city where the user’s preferred address is located. For example:

Portland
companystringName of the organization associated with the user. For example:

​Akamai​
countrystringTwo-letter abbreviation for the country where the user’s preferred address is located. For example:

US
phonestringPhone number associated with the user account. For example:

+155506031989
stateAbbreviationstringTwo-letter abbreviation for the state or region where the user’s preferred address is located. For example:

OR
zipstringPostal code for the user’s preferred address. For example:

97209
zipPlus4string“Zip+4” postal code for the user’s preferred address. For example:

97209-2981

Profiles plural

Represents any third-party identity providers a user has employed to authenticate with your site: if you  haven’t enabled social login (e.g. allowing users to log on with Facebook or Twitter) then none of your users will have entries in the profiles plural.

To refer to an individual attribute, use syntax like this: profiles.domain.

Attribute NameTypeDescription
domainstringDomain of the identity provider (IdP) that authenticated the user. For example:

google.com
identifierstringIdentity provider’s unique identity for the user. For example:

https://www.google.com/profiles/123456789012345678901
photostringURL for the photo associated with the user’s identity provider account. For example:

https://lh3.googleusercontent.com/a-/123456789012345678901
providerSpecifierstringUnique identifier for the IdP that authenticated the user. For example:

google
idstringUnique identifier for this profile, for this user. For example:

0710

Roles plural

Maintains information about roles used by your organization to group and categorize users. Note that roles are arbitrary: you can create any kind and any number of roles you want. In addition, roles are optional: if you don’t want to use roles you don’t have to.

To refer to an individual attribute, you’ll need to use syntax like this: roles.value.

Attribute NameTypeDescription
displaystringHuman-readable name associated with the role and primarily used for display purposes. For example:

Graduate Student
valuestringValue (name) of a user role. For example:

student
idstringUnique identifier for this role, for this user. For example:

0705