PrivX Login Flow and State Storage

LDAP and Local-User Login

1. User performs an action that triggers the login (e.g. going to PrivX UI when unauthenticated).
2. PrivX UI starts login flow. The following state is created:
   1. The target URL that the user should be redirected to after a successful login.
   2. A random CSRF token is created, which is used with the OAuth state parameter to mitigate CSRF attacks.
   3. A PKCE verifier is generated, and a challenge is generated from it using SHA-256.
   4. The target URL, CSRF token, and PKCE verifier are stored in sessionStorage in the browser as an authorization state.
   5. The user is redirected to the OAuth2 authorization endpoint to start the authorization flow. The authorization endpoint URL that the user is redirected to includes:
      1. The CSRF token (2.2) in the state parameter.
      2. The PKCE challenge (2.3) in the code_challenge parameter.
      3. The PKCE challenge method (2.3) in the code_challenge_method parameter.
      4. An optional oidc_id parameter.
      5. The callback URL in the redirect_uri parameter.
      6. The OAuth2 Client identifier in the client_id parameter.
3. The PrivX Authentication UI is shown to the user and the user enters their username and password.
   1. The username and password is submitted to the PrivX login endpoint, which gives an error if credentials are incorrect, or a redirect URL if they are correct. If the login requires MFA, the flow continues in step 4. Without MFA, it continues in step 5.
4. The user is prompted for a TOTP PIN code, which is entered by the user.
   1. The TOTP PIN is submitted to the PrivX login endpoint, which gives an error if the PIN is incorrect and a redirect URL if the PIN is correct.
5. The user is redirected back to the PrivX UI callback URL, specified with the redirect_url (2.5.5)
   1. The PrivX UI receives the OAuth authorization code in the code parameter, and CSRF token in the state parameter in the callback URL
   2. The authorization state (2.4) is retrieved and the CSRF token (2.2) is verified to be matching.
   3. The PKCE verifier (2.3) is retrieved from the authorization state.
   4. The orignal target URL (2.1) is retrieved from the authorization state.
6. The PrivX UI calls the OAuth2 token endpoint, passing it the authorization code (5.1), the redirect_uri (2.5.5) and the PKCE verifier (5.3), and receives an access token, access token expiration time, and refresh token in return.
7. The access and refresh tokens are stored along with the access token expiration time in localStorage in the browser as an authentication state. The token expiration time can be configured in the PrivX authentication back end (/opt/privx/etc/oauth-shared-config.toml). Once the access token expires, it can be refreshed using the refresh token, as long as the refresh token has not expired. The expiration time for refresh tokens can also be configured. When an access token is refreshed, the UI can also receive a new refresh token at the same time, if the back end provides one. This is all a normal part of the OAuth2 token endpoint functionality. Finally, a maximum session duration can be configured, after which neither the access nor refresh token can be refreshed.
8. The user is redirected to the original target URL (5.4)

OIDC Login

1. User performs an action that triggers the login (e.g. going to PrivX UI when
   unauthenticated)
2. PrivX UI starts login flow
   The following state is created:
   1. The target URL that the user should be redirected to after a successful
      login.
   2. A random CSRF token is created, which is used with the OAuth state
      parameter to mitigate CSRF attacks.
   3. A PKCE verifier is generated, and a challenge is generated from it using
      SHA-256.
   4. The target URL, CSRF token, and PKCE verifier are stored in
      sessionStorage in the browser as an authorization state.
   5. The user is redirected to the OAuth2 authorization endpoint to start the
      authorization flow.
      The authorization endpoint URL that the user is redirected to includes:
      1. The CSRF token (2.2) in the state parameter.
      2. The PKCE challenge (2.3) in the code_challenge parameter.
      3. The PKCE challenge method (2.3) in the code_challenge_method
      parameter.
      4. An optional oidc_id parameter.
      5. The callback URL in the redirect_uri parameter.
      6. The OAuth2 Client identifier in the client_id parameter.
3. The PrivX authentication back end redirects the user directly to an OpenID
   Connect provider if the oidc_id parameter (2.5.4) is supplied. In practice
   this happens using a special "direct login" link, which can be seen in the
   PrivX UI under the Directory administration. If no oidc_id paramter is
   supplied, which is the common case, then the PrivX Authentication UI will
   be shown to the user and the user can press a button to select the OpenID
   Connect provider they want to use.
4. The user is redirected to the OpenID Connect provider and authenticates
   there, and then redirected back to PrivX.
5. The user is redirected back to PrivX UI callback URL, specified with the
   redirect_url (2.5.5).
   1. The PrivX UI receives the OAuth authorization code in the code
      parameter, and CSRF token in the state parameter in the callback URL.
   2. The authorization state (2.4) is retrieved and the CSRF token (2.2) is
      verified to be matching.
   3. The PKCE verifier (2.3) is retrieved from the authorization state
   4. The orignal target URL (2.1) is retrieved from the authorization state
6. The PrivX UI calls the OAuth2 token endpoint, passing it the authorization
   code (5.1), the redirect_uri (2.5.5) and the PKCE verifier (5.3), and
   receives an access token, access token expiration time, and refresh token in
   return.
7. The access and refresh tokens are stored along with the access token
   expiration time in localStorage in the browser as an authentication state.
   The token expiration time can be configured in the PrivX authentication
   back end (/opt/privx/etc/oauth-shared-config.toml). Once the access token
   expires, it can be refreshed using the refresh token, as long as the refresh
   token has not expired. The expiration time for refresh tokens can also be
   configured. When an access token is refreshed, the UI can also receive a new
   refresh token at the same time, if the back end provides one. This is all a
   normal part of the OAuth2 token endpoint functionality. Finally, a maximum
   session duration can be configured, after which neither the access nor
   refresh token can be refreshed.
8. The user is redirected to the original target URL (5.4)