Date claims transformations
This article provides examples for using the date claims transformations of the Identity Experience Framework schema in Azure Active Directory B2C (Azure AD B2C). For more information, see claims transformations.
AssertDateTimeIsGreaterThan
Asserts that one date is later than a second date. Determines whether the rightOperand is greater than the leftOperand. If yes, throws an exception. Check out the Live demo of this claims transformation.
| Element | TransformationClaimType | Data Type | Notes |
|---|---|---|---|
| InputClaim | leftOperand | string | First claim's type, which should be later than the second claim. |
| InputClaim | rightOperand | string | Second claim's type, which should be earlier than the first claim. |
| InputParameter | AssertIfEqualTo | boolean | Specifies whether this assertion should throw an error if the left operand is equal to the right operand. Possible values: true (default), or false. |
| InputParameter | AssertIfRightOperandIsNotPresent | boolean | Specifies whether this assertion should pass if the right operand is missing. |
| InputParameter | TreatAsEqualIfWithinMillseconds | int | Specifies the number of milliseconds to allow between the two date times to consider the times equal (for example, to account for clock skew). |
The AssertDateTimeIsGreaterThan claims transformation is always executed from a validation technical profile that is called by a self-asserted technical profile. The DateTimeGreaterThan self-asserted technical profile metadata controls the error message that the technical profile presents to the user. The error messages can be localized.
Example of AssertDateTimeIsGreaterThan
The following example compares the currentDateTime claim with the approvedDateTime claim. An error is thrown if currentDateTime is later than approvedDateTime. The transformation treats values as equal if they are within 5 minutes (30000 milliseconds) difference. It won't throw an error if the values are equal because AssertIfEqualTo is set to false.
<ClaimsTransformation Id="AssertApprovedDateTimeLaterThanCurrentDateTime" TransformationMethod="AssertDateTimeIsGreaterThan">
<InputClaims>
<InputClaim ClaimTypeReferenceId="approvedDateTime" TransformationClaimType="leftOperand" />
<InputClaim ClaimTypeReferenceId="currentDateTime" TransformationClaimType="rightOperand" />
</InputClaims>
<InputParameters>
<InputParameter Id="AssertIfEqualTo" DataType="boolean" Value="false" />
<InputParameter Id="AssertIfRightOperandIsNotPresent" DataType="boolean" Value="true" />
<InputParameter Id="TreatAsEqualIfWithinMillseconds" DataType="int" Value="300000" />
</InputParameters>
</ClaimsTransformation>
Note
In the example above, if you remove the AssertIfEqualTo input parameter, and the currentDateTime is equal toapprovedDateTime, an error will be thrown. The AssertIfEqualTo default value is true.
- Input claims:
- leftOperand: 2022-01-01T15:00:00
- rightOperand: 2022-01-22T15:00:00
- Input parameters:
- AssertIfEqualTo: false
- AssertIfRightOperandIsNotPresent: true
- TreatAsEqualIfWithinMillseconds: 300000 (30 seconds)
- Result: Error thrown
Call the claims transformation
The following Example-AssertDates validation technical profile calls the AssertApprovedDateTimeLaterThanCurrentDateTime claims transformation.
<TechnicalProfile Id="Example-AssertDates">
<DisplayName>Unit test</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.ClaimsTransformationProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="ComparisonResult" DefaultValue="false" />
</OutputClaims>
<OutputClaimsTransformations>
<OutputClaimsTransformation ReferenceId="AssertDates" />
</OutputClaimsTransformations>
<UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>
The self-asserted technical profile calls the validation Example-AssertDates technical profile.
<TechnicalProfile Id="SelfAsserted-AssertDateTimeIsGreaterThan">
<DisplayName>User ID signup</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
<Metadata>
<Item Key="ContentDefinitionReferenceId">api.selfasserted</Item>
<Item Key="DateTimeGreaterThan">Custom error message if the provided right operand is greater than the right operand.</Item>
</Metadata>
...
<ValidationTechnicalProfiles>
<ValidationTechnicalProfile ReferenceId="ClaimsTransformation-AssertDateTimeIsGreaterThan" />
</ValidationTechnicalProfiles>
</TechnicalProfile>
ConvertDateTimeToDateClaim
Converts a DateTime claim type to a Date claim type. The claims transformation removes the time format from the date. Check out the Live demo of this claims transformation.
| Element | TransformationClaimType | Data Type | Notes |
|---|---|---|---|
| InputClaim | inputClaim | dateTime | The claim type to be converted. |
| OutputClaim | outputClaim | date | The claim type that is produced after this claims transformation has been invoked. |
Example of ConvertDateTimeToDateClaim
The following example demonstrates the conversion of the claim systemDateTime (dateTime data type) to another claim systemDate (date data type).
<ClaimsTransformation Id="ConvertToDate" TransformationMethod="ConvertDateTimeToDateClaim">
<InputClaims>
<InputClaim ClaimTypeReferenceId="systemDateTime" TransformationClaimType="inputClaim" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="systemDate" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
- Input claims:
- inputClaim: 2022-01-03T11:34:22.0000000Z
- Output claims:
- outputClaim: 2022-01-03
ConvertDateToDateTimeClaim
Converts a Date claim type to a DateTime claim type. The claims transformation converts the time format and adds 12:00:00 AM to the date. Check out the Live demo of this claims transformation.
| Element | TransformationClaimType | Data Type | Notes |
|---|---|---|---|
| InputClaim | inputClaim | date | The claim type to be converted. |
| OutputClaim | outputClaim | dateTime | The claim type that is produced after this claims transformation has been invoked. |
Example of ConvertDateToDateTimeClaim
The following example demonstrates the conversion of the claim dateOfBirth (date data type) to another claim dateOfBirthWithTime (dateTime data type).
<ClaimsTransformation Id="ConvertToDateTime" TransformationMethod="ConvertDateToDateTimeClaim">
<InputClaims>
<InputClaim ClaimTypeReferenceId="dateOfBirth" TransformationClaimType="inputClaim" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="dateOfBirthWithTime" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
- Input claims:
- inputClaim: 2022-01-03
- Output claims:
- outputClaim: 2022-01-03T00:00:00.0000000Z
DateTimeComparison
Compares two dates and determines whether the first date is later, earlier, or equal to another. The result is a new Boolean claim with a value of true or false. Check out the Live demo of this claims transformation.
| Element | TransformationClaimType | Data Type | Notes |
|---|---|---|---|
| InputClaim | firstDateTime | dateTime | The first date to compare whether it's later, earlier, or equal to the second date. Null value throws an exception. |
| InputClaim | secondDateTime | dateTime | The second date to compare. Null value is treated as the current date and time. |
| InputParameter | timeSpanInSeconds | int | Timespan to add to the first date. Possible values: range from negative -2,147,483,648 through positive 2,147,483,647. |
| InputParameter | operator | string | One of following values: same, later than, or earlier than. |
| OutputClaim | result | boolean | The claim that is produced after this claims transformation has been invoked. |
Example of DateTimeComparison
Use this claims transformation to determine if first date plus the timeSpanInSeconds parameter is later, earlier, or equal to another. The following example shows that the first date (2022-01-01T00:00:00) plus 90 days is later than the second date (2022-03-16T00:00:00).
<ClaimsTransformation Id="CompareLastTOSAcceptedWithCurrentDateTime" TransformationMethod="DateTimeComparison">
<InputClaims>
<InputClaim ClaimTypeReferenceId="extension_LastTOSAccepted" TransformationClaimType="secondDateTime" />
<InputClaim ClaimTypeReferenceId="currentDateTime" TransformationClaimType="firstDateTime" />
</InputClaims>
<InputParameters>
<InputParameter Id="operator" DataType="string" Value="later than" />
<InputParameter Id="timeSpanInSeconds" DataType="int" Value="7776000" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="isLastTOSAcceptedGreaterThanNow" TransformationClaimType="result" />
</OutputClaims>
</ClaimsTransformation>
- Input claims:
- firstDateTime: 2022-01-01T00:00:00.100000Z
- secondDateTime: 2022-03-16T00:00:00.100000Z
- Input parameters:
- operator: later than
- timeSpanInSeconds: 7776000 (90 days)
- Output claims:
- result: true
IsTermsOfUseConsentRequired
Determine whether a dateTime claim type is earlier or greater than a specific date. The result is a new Boolean claim with a value of true or false. Check out the Live demo of this claims transformation.
| Item | TransformationClaimType | Data type | Notes |
|---|---|---|---|
| InputClaim | termsOfUseConsentDateTime | dateTime | The dateTime claim type to check whether it's earlier or later than the termsOfUseTextUpdateDateTime input parameter. Undefined value returns true result. |
| InputParameter | termsOfUseTextUpdateDateTime | dateTime | The dateTime claim type to check whether it's earlier or later than the termsOfUseConsentDateTime input claim. The time part of the date is optional. |
| OutputClaim | result | boolean | The claim type that's produced after this claims transformation has been invoked. |
Use this claims transformation to determine whether a dateTime claim type is earlier or greater than a specific date. For example, check whether a user has consented to the latest version of your terms of use (TOU) or terms of service. To check the last time a user consented, store the last time the user accepted the TOU in an extension attribute. When your TOU wording changes, update the termsOfUseTextUpdateDateTime input parameter with the time of the change. Then, call this claims transformation to compare the dates. If the claims transformation returns true, the termsOfUseConsentDateTime value is earlier than the termsOfUseTextUpdateDateTime value, and you can ask the user to accept the updated TOU.
<ClaimsTransformation Id="IsTermsOfUseConsentRequired" TransformationMethod="IsTermsOfUseConsentRequired">
<InputClaims>
<InputClaim ClaimTypeReferenceId="extension_termsOfUseConsentDateTime" TransformationClaimType="termsOfUseConsentDateTime" />
</InputClaims>
<InputParameters>
<InputParameter Id="termsOfUseTextUpdateDateTime" DataType="dateTime" Value="2021-11-15T00:00:00" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="termsOfUseConsentRequired" TransformationClaimType="result" />
</OutputClaims>
</ClaimsTransformation>
IsTermsOfUseConsentRequired example
- Input claims:
- termsOfUseConsentDateTime: 2020-03-09T09:15:00
- Input parameters:
- termsOfUseTextUpdateDateTime: 2021-11-15
- Output claims:
- result: true
GetCurrentDateTime
Get the current UTC date and time and add the value to a claim type. Check out the Live demo of this claims transformation.
| Element | TransformationClaimType | Data Type | Notes |
|---|---|---|---|
| OutputClaim | currentDateTime | dateTime | The claim type that is produced after this claims transformation has been invoked. |
Example of GetCurrentDateTime
The following example shows how to get the current data and time:
<ClaimsTransformation Id="GetSystemDateTime" TransformationMethod="GetCurrentDateTime">
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="systemDateTime" TransformationClaimType="currentDateTime" />
</OutputClaims>
</ClaimsTransformation>
- Output claims:
- currentDateTime: 2022-01-14T11:40:35.0000000Z
Next steps
- Find more claims transformation samples on the Azure AD B2C community GitHub repo