Knowledge Base

Appearance

Invitation flow ​

TIP

This document describe the technical specification for users management invite user flow. For more information concerning the invitation please refer to User management

There is two possibles action, user invitation and resend invitation for user.

DTO ​

List of DTO used below

PlAccountDTO ​

typescript
interface PlAccountDTO {
    emails: string[];
    role: MemberRole;
}

KeycloakUser ​

Keycloak UserRepresentation

typescript
interface KeycloakUser extends UserRepresentation {
    attributes: {
        terms_and_condition?: boolean,
        locale?: string
    };
}

User invitation ​

User invitation concerns only the PUT http://haku/account/:accountId/inviteMembers endpoint.

User invitation sequence diagram ​

mermaid
sequenceDiagram
    participant settings
    participant haku
    participant keycloak
    participant tombo
    settings-->>haku: PUT /account/:accountId/inviteMembers PlAccountDTO
    loop For each email of PlAccountDTO.emails
        haku-->>haku: Validate email(1)
        alt User already exists
            haku->>tombo: Send USER_ADDED_TO_ACCOUNT mail
        else New user
            Note right of haku: Create user on haku with PENDING status
            haku->>keycloak: POST users/create
            keycloak->>haku: HTTP 200 {id: keycloakUser.id}
            haku->>keycloak: POST users/executeActionsEmail {id: keycloakUser.id, actions: ['INVITE_USER']} (2)
            keycloak->>haku: HTTP 200
        end
    end
    alt An error happenned
        haku-->>settings: HTTP XXX (Highest error code in list) UserInvitationError with a list of errors
    else All went fine
        haku-->>settings: HTTP 200
    end
  1. Email validation flow
  2. Action INVITE_USER is a specific action created to manage the invitation flow inside keycloak

Keycloak INVITE_USER ​

When haku asks keycloak to execute the INVITE_USER action keycloak will send an invitation email to the user's email with a link to fill in the user's information (name, cgv, ...). The invitation link will only be valid for a limited time.

TIP

If the email corresponds to a domain managed by an external IDP, the user will not have to fill a password.

Once the information is completed the user will be redirected to app.product-live.com.

Email validation ​

For each email of PlAccountDTO.emails we will check if the email is valid. Each error will be store in a list and returned to the user afterward if any.

mermaid
flowchart TD
    transformEmail(Transform email to lowercase)
    transformEmail-->validEmail{"Check email validity"}
    validEmail-- No -->badRequestEmail("Add Email invalid to errors list")
    validEmail-- Yes -->emailAlreadyExists{"Does email already exists in this account"}
    emailAlreadyExists-- Yes -->badRequestEmailAlreadyExists("Add 'Email already exists' to errors list")
    emailAlreadyExists-- No -->quotaReached{"Does the quota is reached? [1]"}
    quotaReached -- Yes -->badRequestQuotaReached("Add 'You have reached the user limit with role X on your account'")
    quotaReached -- No -->allGood("Email is valid \o/ [2]")
  1. The quota is defined by user role (example: 5 users with the role SITE_ADMIN and 10 users with the role EDITOR). Only users in "Active" and "Pending" status are counted in the calculation of the number of users within the current account. The user with the status "Suspended", "Archived" or "Removed" are not counted in the calculation of the number of users within the current account.
  2. If the email is valid, user will be created on keycloak if needed and added to the account

First login ​

On user first login, the user is in a PENDING status. The front send an HTTP request PUT http://haku/account/activateMember with a valid access token and haku will change user status from PENDING to ACTIVE and will fill user's information with the one in access token infos (firstname, lastname, phone, language).

WARNING

As long as the user does not connect to app, even if he has filled in his information in keycloak, he will always be considered as PENDING on the haku side

Resend user invitation ​

WARNING

Only users with PENDING status and with terms_on_condition = false on keycloak should have the possibility to resend invitation

mermaid
sequenceDiagram
    participant settings
    participant haku
    participant keycloak
    settings-->>haku: POST /account/:accountId/resendUserInvitation {email: user.email}
    haku->>keycloak: POST users/find {email: user.email}
    keycloak->>haku: HTTP 200 [keycloakUser]
    alt keycloakUser.attributes.terms_and_condition = true
        haku-->>settings: HTTP 429 Bad request user already completed his invitation flow
    else keycloakUser.attributes.terms_and_condition = false
        haku->>keycloak: POST users/executeActionsEmail {id: keycloakUser.id, actions: ['INVITE_USER']}
        keycloak->>haku: HTTP 200
        haku-->>settings: HTTP 200 Invitation sent again
    end

The choice of the attribute terms_on_condition should be temporary and replaced as soon as possible by a better flow. Eg, make keycloak send events through RabbitMQ and listen in yuba for event INVITE_USER flow done for email.