Complete Sign-in flow (user is found)

Complete user sign-in in your application and request user profile and session tokens from AuthN

The authentication flow below describes an example sign-in process for users who selected the password option as their primary authentication method and had already verified their email during their sign-up enrollment.

Diagram

Example authentication flow with password as the primary authentication method and email OTP as the secondary

Annotations

1. AuthN responds with the pre-configured Log in/Sign up flow primary authentication choice selected by the user during their sign-up.

   Return password and password reset choices (1)

   /v2/flow/update response

   json

   Code Snippet Language

   {
       "status": "Success",
       "summary": "Flow updated",
       "result": {
           "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi",
           "flow_type": [
               "signin"
           ],
           "username_format": "string",
           "username": "example",
           "flow_phase": "phase_primary",
           "flow_choices": [
               {
                   "choice": "password",
                   "data": {
                       "enrollment": false,
                       "password_policy": {
                           "chars_min": 8,
                           "chars_max": 64,
                           "lower_min": 1,
                           "upper_min": 1,
                           "punct_min": 1,
                           "number_min": 1
                       }
                   }
               },
               {
                   "choice": "reset_password",
                   "data": {
                       "sent": false,
                       "resend_time": "0001-01-01T00:00:00Z",
                       "state": "pcb_qxswu7wuc7q2cvr5ftb4mtpe2rplxrez"
                   }
               }
           ]
       }
   },
   ...
   

   Note that the result.flow_type is "signin"; so, no additional data, such as email or phone, is required for the password authenticator.

2. Your application prompts the user to make a selection and provide any necessary input, such as the user's credentials or email.

3. The user chooses an authentication method and provides any necessary input.

4. Your application submits the user's password to AuthN.

   Submit user's password (4)

   Parameters:

   • "flow_id" - The result.flow_id value returned in the initial and previous AuthN responses

   • "choice" - The authenticator choice out of the result.flow_choices returned in the previous AuthN response

   • "data" - The user input required for the selected authenticator

   POST/v2/flow/update

   cURL

   Code Snippet Language

   curl --location "https://authn.$PANGEA_DOMAIN/v2/flow/update" \
   --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \
   --header 'Content-Type: application/json' \
   --data '{
       "flow_id": "'"$FLOW_ID"'",
       "choice": "password",
       "data": {
           "password": "AzdJ5#3p"
       }
   }'
   

5. AuthN validates user input and responds with the MFA choice the user made during their sign-up.

   Return MFA choice selected during sign-up (5)

   /v2/flow/update response

   json

   Code Snippet Language

   {
       "status": "Success",
       "summary": "Flow updated",
       "result": {
           "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi",
           "flow_type": [
               "signin"
           ],
           "username_format": "string",
           "username": "example",
           "flow_phase": "phase_secondary",
           "flow_choices": [
               {
                   "choice": "email_otp",
                   "data": {
                       "sent": false,
                       "enrollment": false,
                       "resend_time": "2024-06-16T23:50:18.306288Z"
                   }
               }
           ]
       }
   },
   ...
   

6. Your application submits to AuthN a request to execute the user's MFA method.

   Request to execute the MFA method (6)

   Parameters:

   • "flow_id" - The result.flow_id value returned in the initial and previous AuthN responses

   • "choice" - The MFA authenticator choice returned in the previous AuthN response

   • "data" - An empty object required for a flow restart

   POST/v2/flow/restart

   cURL

   Code Snippet Language

    curl --location "https://authn.$PANGEA_DOMAIN/v2/flow/restart" \
   --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \
   --header 'Content-Type: application/json' \
   --data '{
       "flow_id": "'"$FLOW_ID"'",
       "choice": "email_otp",
       "data": {}
   }'
   

7. AuthN sends the user an OTP and responds with the confirmation of which MFA method is being used.

   Confirm MFA executed (7)

   /v2/flow/restart response

   json

   Code Snippet Language

   {
       "status": "Success",
       "summary": "Flow updated",
       "result": {
           "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi",
           "flow_type": [
               "signin"
           ],
           "username_format": "string",
           "username": "example",
           "flow_phase": "phase_secondary",
           "flow_choices": [
               {
                   "choice": "email_otp",
                   "data": {
                       "sent": true,
                       "enrollment": true,
                       "resend_time": "2024-06-12T20:15:03.426995471Z",
                       "can_update_email": true
                   }
               },
               ...
           ]
       }
   },
   ...
   

8. Your application prompts the user for the temporary credential.

9. The user provides the temporary credential.

10. Your application submits the user's input to AuthN.

    Submit OTP (10)

    Parameters:

    • "flow_id" - The result.flow_id value returned in the initial and previous AuthN responses

    • "choice" - The executed (sent) MFA authenticator choice returned in the previous AuthN response

    • "data" - The user input required for the selected authenticator

    POST/v2/flow/update

    cURL

    Code Snippet Language

    curl --location "https://authn.$PANGEA_DOMAIN/v2/flow/update" \
    --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{
        "flow_id": "'"$FLOW_ID"'",
        "choice": "email_otp",
        "data": {
            "code": "995545"
        }
    }'
    

11. AuthN responds with a phase completed message and includes possible additional MFA choices that your application can optionally perform.

    Return Phase completed and remaining MFA choices (11)

    /v2/flow/update response

    json

    Code Snippet Language

    {
        "status": "Success",
        "summary": "Flow updated",
        "result": {
            "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi",
            "flow_type": [
                "signin"
            ],
            "username_format": "string",
            "username": "example",
            "flow_phase": "phase_completed",
            "flow_choices": [
                {
                    "choice": "sms_otp",
                    "data": {
                        "sent": false,
                        "enrollment": true,
                        "resend_time": "0001-01-01T00:00:00Z",
                        "need_phone": true
                    }
                },
                {
                    "choice": "totp",
                    "data": {
                        "enrollment": true,
                        "totp_secret": {
                            "qr_image": "data:image/png;base64,iVBORw...SuQmCC",
                            "secret": "ZHXHMV...OGMODS"
                        }
                    }
                }
            ]
        },
        ...
    }
    

12. Your application makes a final call to the AuthN APIs and completes the sign-in process.

    Complete the flow (12)

    Parameters:

    • "flow_id" - The result.flow_id value returned in the initial and previous AuthN responses
    POST/v2/flow/complete

    cURL

    Code Snippet Language

    curl --location "https://authn.$PANGEA_DOMAIN/v2/flow/complete" \
    --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{
        "flow_id": "'"$FLOW_ID"'"
    }'
    

13. AuthN responds with the user profile information, an active user token for session validation, and a refresh token for renewing the expired active token.

    Return user profile and session tokens (13)

    In the authentication response, you will receive the user profile information and the session tokens. The format of the user active token will depend on the AuthN Session Configuration settings in the Pangea User Console:

    • Opaque Session Tokens - The active token value is a unique identifier that references a session managed by Pangea. Your application uses the /v2/client/token/check endpoint to verify the user's session and get their profile.

    • JSON Web Tokens (JWT) - The active token is a standard, optionally signed JWT with encoded user and claims information. The validated and decoded token can serve as the session confirmation and the source of user profile data.

    authentication response

    opaque session tokens response

    Code Snippet Language

    {
      "status": "Success",
      "result": {
        "active_token": {
          "token": "ptu_kuoqvvxk4yhirapuhw6bs7nunp",
          "id": "pmt_e3nqvvxk4yhirapuhw6bs7n7sk",
          "type": "user",
          "life": 172799,
          "expire": "2024-05-12T21:16:19.029336Z",
          "enabled": true,
          "identity": "pui_cgwqvvxk4yhirapuhw6bs7nbxr",
          "email": "example.user@example.com",
          "owner": "example.user@example.com",
          "profile": {
            "email": "example.user@example.com",
            "first_name": "Example",
            "last_name": "User",
            "phone": "907...",
            ...
          },
          "created_at": "2024-05-10T21:16:19.037372Z",
          "intelligence": {
            "embargo": false,
            "ip_intel": {
              "is_bad": false,
              "reputation": {
                ...
              },
              "geolocation": {
                ...
              },
              "is_vpn": false,
              "is_proxy": true
            },
            "domain_intel": {
              "is_bad": false,
              "reputation": {
                ...
              }
            },
            "user_intel": false
          }
        },
        "refresh_token": {
          "token": "ptr_tukqvvxk4yhirapuhw6bs7nj3k",
          "id": "pmt_7agqvvxk4yhirapuhw6bs7npay",
          "type": "session",
          "life": 172799,
          "expire": "2024-05-12T21:16:19.029336Z",
          "enabled": true,
          "identity": "pui_cgwqvvxk4yhirapuhw6bs7nbxr",
          "email": "example.user@example.com",
          "owner": "example.user@example.com",
          "profile": {
            "email": "example.user@example.com",
            "first_name": "Example",
            "last_name": "User",
            "phone": "907...",
            ...
          },
          "created_at": "2024-05-10T21:16:19.030784Z",
          "intelligence": {
            "embargo": false,
            "ip_intel": {
              "is_bad": false,
              "reputation": {
                ...
              },
              "geolocation": {
                ...
              },
              "is_vpn": false,
              "is_proxy": true
            },
            "domain_intel": {
              "is_bad": false,
              "reputation": {
                ...
              }
            },
            "user_intel": false
          }
        }
      },
      ...
    }

Was this article helpful?

Contact us