User identity and verification

A key part of making authentication secure, is through verification of user identities. Verification usually happens at sign up, to ensure the person signing up exists and is the intended person gaining access to your app or project.

This topic is a conceptual overview of how identity works in Kinde. There are two parts to a user’s identity in Kinde:

• Kinde profile - first name, last name, and picture
• Identity details - information a user can sign in with: Email, phone, social, enterprise. This is explained in more detail below.

Identity

Link to this section

When we use the term ‘identity’, we’re referring to a unique identifier that allows a user to sign in and be verified. An email, phone number, SSO provider, etc.

When a user tries to access a system or service, they provide their identity along with additional credentials (e.g. password, one-time password OTP) to verify their identity and gain access.

Types of identities

Link to this section

Identity credentials

Link to this section

This refers to an email, phone number, or username. Identity credentials are created for a user when they first sign up with an email address, phone number, or username. If it’s the first identity to be added, it will be marked as primary.

You can manually add these user identities.

Social

Link to this section

A social identity is created when a user signs up with a social account, or when they sign in with a social connection that supplies an email matching an existing email identity in Kinde and the connection’s email address trust setting allows the identities to be linked, either straight away (Trust) or after the user enters a one-time code (Verify, then trust).

If a user signs up with a social connection set to Trust or Verify, then trust that provides an email address, and that email does not already belong to a user in Kinde, Kinde creates both a social identity and an email identity with that email. They can use this email to sign in with (if an email authentication method is enabled for your application). If the connection is set to Don’t trust, Kinde creates only a social identity.

Enterprise

Link to this section

An enterprise identity is created when a user signs up via an enterprise connection, or when they sign in via an enterprise connection that supplies an email matching an existing email identity and the connection’s email address trust setting allows the identities to be linked, either straight away (Trust) or after the user enters a one-time code (Verify, then trust).

Users with enterprise identities in Kinde can’t also have other identity types in Kinde. E.g. a user can have an email identity and a social identity. But if a user has an enterprise identity, they cannot have other identities. In this case, identity information is sourced with the identity provider and is managed via the identity provider, not in Kinde.

Trusting emails from providers

Link to this section

When a user signs in through a social or enterprise connection, the identity provider returns an email address. If that email address already belongs to a user in Kinde, the connection’s Email address trust setting decides what happens next. You choose the setting per connection, and it applies to every application in the environment.

Set Email address trust to Trust only when you know the third-party provider verifies email addresses and does not allow users to change their primary email address. For a safer middle ground, select Verify, then trust. Google social connections are set to Trust by default.

Trusted emails

Link to this section

A trusted email provider is one that guarantees the email they issue is verified and also does not allow the user to change their primary email address.

Currently Google is the only provider we treat as trusted by default. When you add a Google social connection in Kinde (or create one through the Kinde Management API without a trust setting), Email address trust is set to Trust by default. You can choose how much to trust emails from any provider when you configure the connection in Kinde (see below), including choosing not to trust Google emails.

Google example (Trust)

1. When a user signs up, the Kinde profile first name, last name and picture are populated from Google.
2. If the Google connection is set to Trust (or Verify, then trust for a brand-new email address), we create a social identity and an email identity.
3. The user can sign in with either Google or their email (if this auth method is allowed).

Untrusted emails

Link to this section

This isn’t to say that other email providers are not trustworthy, this purely relates to email addresses and the guarantee that it will not change.

LinkedIn example (Don’t trust)

1. When a user signs up, the Kinde profile first name, last name and picture are populated from LinkedIn.
2. If the LinkedIn connection is set to Don’t trust, we only create a social identity.
3. At this stage the user can only sign in with their LinkedIn account.

Verify, then trust

Link to this section

Verify, then trust is the recommended middle ground. Kinde does not take the provider’s word for the email address, but it doesn’t keep the accounts apart either. Instead, the user proves they own the email address before the identities are linked.

When a user signs in through the connection and the email address returned by the provider already belongs to someone in Kinde:

1. Kinde sends a one-time code to that email address and shows the standard email verification page.
2. Once the user enters the code, the new social or enterprise identity is linked to the existing user.
3. If the user abandons or fails verification, nothing is created or linked. The next attempt asks for the code again.

The code is only required when the email address already belongs to someone. A brand-new email address skips the code and behaves like Trust. An identity that is already linked to this provider signs in as normal. “Belongs to someone” includes subscribers and access-request records, not only users who can sign in.

Choose an email address trust option

Link to this section

You choose the trust level per connection, for both social connections (such as Google, Apple, Microsoft, GitHub and custom OAuth 2.0) and enterprise connections (such as Microsoft Entra ID, custom SAML, Okta, Cloudflare, Google Workspace and LastPass).

1. Go to Settings > Environment > Authentication and scroll to Social connections (or Enterprise connections).

2. Select Configure on the connection.

3. Under Provisioning, choose an option in Email address trust:

   

   • Don’t trust - Keep them as separate users. Never merges on email alone. A separate user and identity are created, or the user is treated as not found if sign-up is disabled. No code is sent. Safest if the identity provider doesn’t verify email addresses.
   • Verify, then trust (recommended) - Send a one-time code to the email address and merge with the existing user once it’s entered.
   • Trust - Merge with the existing user straight away, with no code. Only use this if the identity provider verifies email addresses and prevents users from changing them.

4. Select Save.

Email address trust is an environment-level decision. Organization-level connections, such as self-serve SSO and connections created for a single organization, do not show this control. They show Auto-add users in its place.

Choose Verify, then trust unless you are certain the identity provider verifies email addresses and prevents users from changing them, in which case Trust is acceptable. Choose Don’t trust when you never want accounts combined on email address. With Trust, you are taking the provider’s word that the email address is correct, valid and belongs to the person signing in.

Existing connections keep their current behavior. A connection that previously had trust switched on is now set to Trust, and one that had it switched off is now set to Don’t trust. No connection is moved to Verify, then trust automatically.

Email sign up flow example

Link to this section

1. When a user signs up with email, the Kinde profile first name, last name are populated by the user (if you ask for it as part of the sign up flow). Their picture will be populated from Gravatar if it exists.
2. Kinde creates a primary contact email using the address they signed up with. They can only sign in with this email address.
3. If the same user returns and signs in with a connection set to Trust, e.g. Google, Kinde recognises that a user exists and the email address is from a trusted provider, so we add a Google identity to their profile. If the connection is set to Verify, then trust, the user first enters a one-time code sent to that email address, and then the Google identity is added.
4. The Kinde profile first name, last name and picture are updated by Google (if profile syncing is also turned on).
5. The user can sign in using either email or Google.

Keeping identities in sync

Link to this section

Social provider syncing

Link to this section

If a social provider gives us a new first name, last name or picture for a user, Kinde updates these fields in the user profile to match those supplied to us.

This is on by default, but you can turn it off if you wish to keep a static profile. About profile sync.

If you have syncing off at an environment level but turned on at a social connection level we will honor the request for the social connection to sync.

Enterprise connection syncing

Link to this section

If an enterprise provider gives us a new first name, last name, or picture for a user, Kinde updates these fields in the user profile to match those supplied to us.

This is on by default, but you can turn it off if you wish to keep a static profile. About profile sync.

If you have syncing off at an environment level but turned on at an enterprise connection level we will honor the request for the enterprise connection to sync.

Identity verification

Link to this section

Verification is an authentication security measure that checks the person seeking system access is who they say they are. In addition, an up to date identity provides a secure method to contact a user. Email identity details are required, for example, to reset a user’s password (requested or forced), and are needed to reliably send OTPs and trigger other auth mechanisms, like auth apps.

Username identities must have an email

Link to this section

At Kinde, we don’t treat username identities the same as phone and email identities. If you want users to sign in and authenticate with usernames, they still need to verify themselves (if only once) via email.

Cases in usernames

Link to this section

Kinde treats usernames as case-insensitive. In other words, we ignore case. We do this because it eliminates the possibility of auth issues and fraud when two usernames are identical in every aspect except the case of one of their letters.

We are happy to support users choosing an aesthetically pleasing username combination, like RosyRose or BuilderBob. We just don’t also support separate identities for rosYrosE and BUilderbob.

When an identity changes

Link to this section

For security reasons, you can’t edit a user’s verified identity. But we know it still needs to be possible. People change emails, change names, get new phone numbers, etc.

You can update identities by adding a new identity and deleting the old one. See Add and manage user identities, or via the Kinde API.