Token Conditions and Prechecks
Besides performing a successful authentication, cidaas provides features to apply further conditions that must be fulfilled before issuing a token to the caller.
These conditions might occur when user profile information is missing, when the password needs to be changed after successful authentication, or when the authentication strength is insufficient to access a particular portal.
To give a great introduction to these features (so called prechecks) and how you can enable them and make use of them, this section will:
- Provide an overview about the possible conditions
- Explain how you can continue the token generation after completion of the precheck
- For each condition explain when this will occur and how you can enable it
Overview of Conditions
| Type | Key | Description |
|---|---|---|
| Request for User Consent or User Information | ||
| Consent | common_consent | This ensures that a user will accept e.g. Terms and Conditions, Data Privacy Agreements etc. during login, also in case of version updates |
| Scope Consent | scope_consent | To forward particular user information you can define if the user needs to give consent to access the requested data e.g. in the id token or via userinfo endpoint |
| Claim Consent | claim consent | To be even more granular, it is possible to request consent for particular user fields (claims) that will be provided in the id_token or in the userinfo endpoint |
| Progressive Profiling | missing_required_fields | After an initial registration you might want to collect step by step information of the user, this can be achieved using Progressive Profiling and defining which user information (fields) are required to provide depending on the portal or app used. |
| Insufficient Authentication Strength or Account Verification | ||
| Multi Factor Authentication | mfa_required | If you want to increase the authentication strength, cidaas allows you to request a second factor, or to request to re-authenticate after particular timeframes just by configuration for a particular client (application). In case of Smart Multi Factor Authentication cidaas decides if the user needs to provide another authentication factor due to suspicious activities. |
| Communication Medium Verification | communication_medium_verification | If you require an email verification or mobile_number verification to have a proper account validation upfront the login to this app, the communication medium verification requirement can be defined in appsettings |
| Communication Change | communication_change | If a user needs to change their email or mobile number during the verification process (e.g., due to a typo), this precheck allows them to update their communication medium and continue with verification |
| Success information | ||
| Login Success Page | login_success_page | If you would like to show the user a success page after Login, you can enable it per app |
| Login SPI | login_spi_required | After a successful login a service provider interface can be called. This allows e.g. to enable the user for product specific settings. (not recommended in high load instances) |
| Additional Context Information Collection | ||
| Group Selection | group_selection_required | If you only want the user to act in the context of a group, you can activate the group selection. The user will be prompted to select one of their existing groups if those are part of the configured list, and this will provide the selected group as part of the access token |
| Authentication Enrollment | ||
| Suggest Verification Methods | suggest_verification_methods | To allow a smooth enrollment on the fly for further authentication methods, you can provide which authentication methods should be proposed after a successful login. The user will be prompted to the enrollment page and can configure, postpone, or decline the request. |
| Password Change | password_change | If e.g. the Customer service or cidaas admin resets a password, or creates a user with password, you might want to ask the user to change their password after a successful next login. |
Fulfillment of Conditions
Depending on the condition that is unmet, your frontend app needs to react. For example, in case of missing required fields, your UI needs to ask the user to fill out the required fields and provide them to cidaas.
To know which condition is failing and how to continue the flow, here are the important APIs that help you to succeed prechecks:
| API | Description | Link |
|---|---|---|
| GET Pre-Login Metadata | This API will provide you the information which user interaction is required to complete, e.g. which consent is missing. It is mostly required for Request for User Consent or User Information and no other conditions | Link to the API |
| POST Continue Login | To continue the Login or Register Process and finally complete it so that a code or token is issued, the continue API call will proceed | Link to the API |
Request for User Consent or User Information
| Type | Key | Fulfillment | API |
|---|---|---|---|
| Consent | common_consent | To fulfill this requirement the user needs to accept a consent. This is done by providing the user a button or checkboxes to accept the consent and call an API of the consent-management service | Link to API |
| Scope Consent | scope_consent | A scope consent is addressed if 1. the scope tagged as required for user consent, 2. the prompt type was consent in the authz URL or 3. the app type is a Third Party Client | Link to API |
| Claim Consent | claim consent | A claim consent is requested in the authz URL. To request a claim you need to provide id_token or userinfo as query param like claims={"userinfo":{"address":{"essential":true}}} | Link to API |
| Progressive Profiling | missing_required_fields | To fulfill this requirement you need to present the user the fields and allow them to enter a valid value for it. After submitting, a particular API call for progressive updates is triggered from the User Interface | Link to API |
Insufficient Authentication Strength or Account Verification
| Type | Key | Fulfillment | API |
|---|---|---|---|
| Multi Factor Authentication | mfa_required | To request a further authentication factor the User Interface needs to show the options from which the user can select, therefore the User Interface needs to call the Verification API. After successful verification, continue with the login process. | Link to Documentation |
| Communication Medium Verification | communication_medium_verification | The Account Verification has potentially two APIs: either you will do an OTP login using SMS or E-Mail using the Authentication Methods, or the second option, presented here, is to use the account verification API | Link to API: Init Account Verification & Link to API: Verify Account |
| Communication Change | communication_change | If a user needs to change their email or mobile number during verification, they can initiate a communication change. This will cancel the current verification and start a new one with the updated medium. | Link to API: Init Communication Change & Link to API: Validate Communication Change |
Success information
| Type | Key | Fulfillment | API |
|---|---|---|---|
| Login Success Page | login_success_page | Nothing to do | Use directly the continue API |
| Login SPI | login_spi_required | Nothing to do in cidaas | Fulfill your customized action and then continue with the continue API |
Additional Context Information Collection
| Type | Key | Fulfillment | API |
|---|---|---|---|
| Group Selection | group_selection_required | Here the precheck continue call needs a body parameter called selectedGroupId | Link to API |
Authentication Enrollment
| Type | Key | Fulfillment | API |
|---|---|---|---|
| Suggest Verification Methods | suggest_verification_methods | In this case, multi-factor authentication is not required, but setting up further authentication methods is possible. Therefore, you can initiate the enrollment using the track ID API. | Link to API |
| Password Change | password_change | In this case the UI should display a password and a password_echo field to allow the user to set a new password. This can be submitted using the API call provided here | Link to API |
Order of the Token Conditions
The user flow can be designed very individually. However, in the case of token conditions it is important to have a proper order defined for two reasons:
- Security: E.g. multi-factor-authentication is required to be performed before any required fields can be asked from an end user.
- Dependency: E.g. first mfa will be asked and when using an Email OTP the email address will be automatically verified, so communication_medium_verification might evaluate to be already completed.
| Token Condition | Description |
|---|---|
| group_validation | This evaluates the group/roles-restriction and will return an unauthorized if the respective permissions are not provided. See Groups Role Restriction for detailed documentation. |
| password_change | When a user is created or a password reset was initiated by an administrator, it is possible to enforce the user to change their password after login. |
| mfa_required | If you want to increase the authentication strength, cidaas allows you to request a second factor, or to request to re-authenticate after particular timeframes just by configuration for a particular client (application) |
| missing_required_fields | After an initial registration you might want to collect step by step information of the user, this can be achieved using Progressive Profiling and defining which user information (fields) are required to provide depending on the portal or app used. |
| communication_medium_verification | If you require an email verification or mobile_number verification to have a proper account validation upfront the login to this app, the communication medium verification requirement can be defined in appsettings |
| common_consent | This ensures that a user will accept e.g. Terms and Conditions, Data Privacy Agreements etc. during login, also in case of version updates |
| scope_consent | To forward particular user information you can define if the user needs to give consent to access the requested data e.g. in the id token or via userinfo endpoint based on scopes |
| claim_consent | To forward particular user information you can define if the user needs to give consent to access the requested data e.g. in the id token or via userinfo endpoint based on claims |
| group_selection_required | If you only want the user to act in the context of a group, you can activate the group selection. The user will be prompted to select one of their existing groups if those are part of the configured list, and this will provide the selected group as part of the access token |
| suggest_verification_methods | To allow a smooth enrollment on the fly for further authentication methods, you can provide which authentication methods should be proposed after a successful login. The user will be prompted to the enrollment page and can configure, postpone, or decline the request. |
| login_success_page | If you would like to show the user a success page after Login, you can enable it per app |
| login_spi_required | After a successful login a service provider interface can be called. This allows e.g. to enable the user for product specific settings. (not recommended in high load instances) |