--- title: Login action description: Login action authentication flows start with a call to the /{{envID}}/as/authorize endpoint. The response to an authorize request returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the authentication workflow. For a new session, the user's browser is redirected to the sign-on screen that prompts for a PingOne username and password (or, based on the sign-on policy configuration, provides access to an external identity provider's sign-on URL). component: pingone-api page_id: pingone-api:foundations:authentication-concepts/pingone-authentication-flow-states/login-action canonical_url: https://developer.pingidentity.com/pingone-api/foundations/authentication-concepts/pingone-authentication-flow-states/login-action.html section_ids: sign-on-with-username-and-password: Sign on with username and password forgot-password: Forgot password register-user: Register user sign-on-with-identity-provider: Sign on with identity provider --- # Login action Login action authentication flows start with a call to the `/{{envID}}/as/authorize` endpoint. The response to an authorize request returns a `Location` HTTP header that specifies the URL for the sign-on screen and the flow ID for the authentication workflow. For a new session, the user's browser is redirected to the sign-on screen that prompts for a PingOne username and password (or, based on the sign-on policy configuration, provides access to an external identity provider's sign-on URL). For an existing session, the user's browser is redirected to a sign-on screen that prompts for a password only. The following diagram shows the flow options for the `USERNAME_PASSWORD_REQUIRED` and `PASSWORD_REQUIRED` flow states: ![Flow overview](../../../_images/p1_FlowMaster.svg) The login flow consists of the following four branches, which can be chosen to submit the username and password, recover a forgotten password, or create account credentials to complete the sign-on flow: * **Sign on with username/password** This flow verifies the username and password submitted by the user through the sign-on screen. * **Forgot password** If enabled, the recover password flow initiates actions to recover the account and set a new password. * **Register user** If enabled, the register user flow initiates actions to create an account for a user. The flow calls the `user.register` action to create the new user. * **Sign on with identity provider** If enabled, the social sign-on flow initiates actions to authenticate the user through an external identity provider. ## Sign on with username and password The username/password branch of the login flow uses the `usernamePassword.check` action to verify the user's password. If the user's password status is `OK`, the flow transitions to the next action required by the sign-on policy. If the user's password has expired, the flow transitions to the `PASSWORD_EXPIRED` flow state. The response from the `usernamePassword.check` action includes a link to initiate the `password.reset` action to update the password. If the user is using a temporary password, the flow transitions to the `MUST_CHANGE_PASSWORD` flow state. The user can initiate the `password.reset` action to change the temporary password. ![Check password flow](../../../_images/p1_CheckPasswordStates.svg) ## Forgot password The recover password branch of the login flow uses the `user.lookup` action to verify the user. After user look-up, the flow transitions to the `RECOVERY_CODE_REQUIRED` flow state. The flow uses the `password.recover` action to issue a recovery code to the user. After the recovery code is issued and the user submits the correct code, the flow transitions to the `MUST_CHANGE_PASSWORD` flow state and uses the `password.reset` action to update the user's password. ![Recover password flow](../../../_images/p1_RecoverPasswordStates.svg) ## Register user The register user branch of the login flow initiates the `user.register` action to create a new user account and set a password. The sign-on screen prompts the user to submit a username, an email address, and a password. If this action executes successfully, the flow transitions to the next action required by the sign-on policy. ![Register user flow](../../../_images/p1_RegisterUser.svg) ## Sign on with identity provider The external identity provider (social sign-on) branch of the login flow initiates actions to authenticate the user through an external identity provider. It also links the external identity provider to the PingOne user account. The flow diagram shows a flow path to update a user who already has an existing link to an external identity provider account, bypassing the `ACCOUNT_LINKING_REQUIRED` flow state. It also shows a flow path if the external identity provider account is not linked to an existing PingOne user. In this case, the flow transitions to the `ACCOUNT_LINKING_REQUIRED` flow state and calls the `user.register` action to find a matching user and initiate account linking to the external provider. ![External identity provider flow](../../../_images/p1_SocialLoginStates.svg) From the `ACCOUNT_LINKING_REQUIRED` flow state, a user can either register as a new user or link to an existing PingOne user. In cases where the user does not exist in PingOne, the external identity provider login flow calls the `user.register` action to register the external identity account user as a new PingOne user. Consequently, when the social sign-on branch is implemented as a sign-on option, the sign-on policy should also include the register user sign-on branch with the `registration.enabled` policy action attribute set to `true`. If registration is enabled and the user exists in PingOne but no external account link is defined, PingOne tries to find a matching user (usually by email address). If PingOne does not find a matching user, then registration is required. If PingOne finds one or more matching users (more than one user in the system with a matching email address), then the flow prompts for a username and password to verify the user's identity and complete the account link. If the registration login flow branch is disabled in the sign-on policy, then the user who tries to log in with external identity provider credentials can only link to an already existing user in PingOne.