Sourcing Claims

Claims can be automatically sourced from factors using sources. If the source is configured to also operate bidirectional than it can also source enrollments (factors) from attributes. Sources can be configured on all attributes but only on the following factors:

• Username - You can capture the username during signup.

• One-Time Password (OTP) - You can capture the channel (email, phone number, etc.) during signup.

• OAuth 2.0 / OpenID Connect (OIDC) - You can capture the claims in the identity token returned from the identity provider during signup and login.

You can configure as many sources you like on a factor or attribute. If worried about duplication issue please see Sourcing Logic below.

Please note that for a source to be able to capture claims the factor must have following enabled:

• Username - input capture must be enabled

• One-Time Password (OTP) - input capture must be enabled

• OAuth 2.0 / OpenID Connect (OIDC) - claims capture must be enabled

But bidirectional sourcing will always work regardless. Hence if you only want a source to operate in reserve order you can disable input/claims capture.

Configuration

For each source you can specify the following:

• Attribute - The attribute to source, i.e. collect claims for.

• Factor - The factor to source claims from, i.e. collect claims from.

• Claim - The key of the claim obtained by the factor to use. This depends on the factor type:

  • Username - The key is input and refers to the provided user input (username).

  • One-Time Password (OTP) - The key is input and refers to the provided user input (channel).

  • OAuth 2.0 / OpenID Connect (OIDC) - The key refers to the claim in the obtained identity token.

• Bidirectional - This indicates whether the source must also operate bidirectional, i.e. whether it must also automatically create enrollments for new claims.

Sourcing Logic

Each source follows the below logic; as for the input / claim event the claim will be considered verified if:

• Username - The input will be considered verified if the factor requires validation for enablement and the resulting enrollment is in an ENABLED status. But generally speaking a username factor will not require validation and hence input will not be considered verified.

• One-Time Password (OTP) - The input will be considered verified if the factor requires validation for enablement and the resulting enrollment is in an ENABLED status. Generally speaking a OTP factor will require validation but the resulting enrollment will be in a PENDING status, and hence input will not be considered verified.

• OAuth 2.0 / OpenID Connect (OIDC) - Any claim is considered verified if a claim_verified claim is also present in the identity token and set to true. Generally speaking most claims will not have this explicit verified flag and hence not considered verified - only the email and phone_number claims generally have email_verified and phone_number_verified flag and hence if set to true they would be considered verified.

Once a claim has been created by a source it's now considered linked to the enrollment from which it originated. In case a pending enrollment gets enabled the source will trace back any linked PENDING claims and enable them as well.

As for bidirectional sourcing the logic is as below.

Once an enrollment has been created by a (bidirectional) source it's now considered linked to the claim from which it originated. In case a pending claim gets enabled the (bidirectional) source will trace back any linked PENDING enrollments and enable them as well.

As the bidirectional process first checks for any existing link for the (new) claim it short-circuits a recursive loop if the claim resulted from the source itself.

Example: Verified Email

In many setups customers want to obtain a verified email for their users as well as use this email for any backup login. Let's first describe all the resources in this example setup:

• One or more OAuth 2.0 / OIDC factors that request the email claim from the identity providers to be returned in the identity token. Make sure that the capture claims feature is enabled and that scopes requested include the email claim.

• One Email One-Time Password (OTP) factor that requires email as input (regex). Make sure that the capture input feature is enabled and this factor is configured to require validation for enablement.

• One Email Username factor that requires email as input (regex). Make sure this factor is configured as restricted because we don't want users to sign up to this factor by themselves.

• One Email attribute; you can use the standard OIDC one. Make sure this attribute is configured as unique and require validation for enablement, as we don't want users with the same email and will always enforce email validation.

• One or more sources between the OAuth 2.0 / OIDC factors and the Email attribute. Make sure to set the source claim to email. This source will capture the email claim in the returned identity token and create a new claim for the user with the returned value.

• One source between the Email OTP factor and the Email attribute. Make sure to configure this source as bidirectional as we want the OTP factor to serve as a backup login method for our users.

• One source between the Email Username factor and Email attribute. Make sure to configure this source as bidirectional as we want the Email Username factor to serve as useful login method (for an ID-first flow with no or limited security value).

Now we can zoom in on a couple scenarios:

Sign up with OAuth 2.0 / OIDC

1. The user signs up with an OAuth 2.0 / OIDC factor and allows the email to be shared. Hence the first source will kick into action and create a new claim for the email. If the returned email is verified than the claim will be enabled; else the claim will be pending. If the email is already taken than the source will fail but the OAuth 2.0 / OIDC factor will still succeed.

2. Because a new claim was created the second (bidirectional) source kick into action and creates new OTP enrollment for the email. If the claim is enabled than the OTP enrollment is immediately enabled and the user does not receive an OTP. If the claim is pending than the OTP enrollment is pending and the user will receive an OTP for validation.

3. Because a new claim was created the third (bidirectional) source kicks into action and creates a new Email username factor. If the claim is enabled than the username enrollment is immediately enabled else it will be pending.

4. If the returned email is verified everything is now enabled; if the email was not verified all is pending except the OAuth 2.0 / OIDC factor. If the user now successfully provides the OTP for the Email OTP factor then it will cause the email claim to become enabled. This in turn enables the Email Username factor resulting in everything now being enabled.

Sign up with Email OTP

1. The user signs up with the Email OTP factor and as such provides their email for the OTP. Hence the second source will kick into action and create a new claim for the email. As the provided email is still unverified the claim will be pending. It's unlikely that the email is already taken, as we create an OTP factor for each new email claim; hence the OTP factor itself would object if an existing email is used.

2. Because a new claim was created the third (bidirectional) source kicks into action and creates a new Email Username factor. As is the claim is pending the username enrollment is pending.

3. When the user provides the OTP for the Email OTP factor it will cause the email claim to be enabled. This in turn enables the Email Username factor resulting in everything now being enabled. Note that no OAuth 2.0 / OIDC factors are created as the rely on unique IDs that the identity providers return - and not the email.

User adds Email

1. The user creates a new email claim. Hence the second and third (bidirectional) sources will kick into action and create a Email OTP and username enrollment. As the email attributes requires validation the new claim will be pending as well as both new enrollments. Because the Email OTP enrollment is pending an OTP will be send out to the user.

2. If the user now successfully provides the OTP for the Email OTP factor then this will cause the email claim to become enabled. This in turn enables the Email username factor hence everything will now be enabled. Note that again no OAuth 2.0 / OIDC factors are created, as the rely on unique IDs that the identity providers return - and not the email.

Admin adds Email

1. An admin creates a new email claim. Hence the second and third (bidirectional) sources will kick into action and create a Email OTP and username enrollment. If the admin requested for a pending claim than both new enrollments will be pending. But if the admin requested for an enabled claim than this will result in both new enrollments being immediately enabled. In the former an OTP will be send out to the user and the flow is identical to User adds Email.

It is possible for enterprise customers to ask use to change the subject claim for OAuth 2.0 / OIDC factors to the email claim though this is not recommended as generally considered bad practice, and often in violation of the Terms & Conditions (T&C's) of identity providers. Also keep in mind that identity providers often return an email claim but that its often not sufficiently verified. Hence this could result in allowing attackers access to an account if the OAuth 2.0 / OIDC factor are pre-enrolled based on email.