##################
frontend-app-authn
##################

|Build Status| |ci-badge| |Codecov| |semantic-release|

********
Purpose
********

This is a micro-frontend application responsible for the login, registration and password reset functionality.

**What is the domain of this MFE?**

- Register page

- Login page

- Forgot password page

- Reset password page

- Progressive profiling page

***************
Getting Started
***************

Installation
============

This MFE is bundled with `Devstack <https://github.com/openedx/devstack>`_, see the `Getting Started <https://github.com/openedx/devstack#getting-started>`_ section for setup instructions.

1. Install Devstack using the `Getting Started <https://github.com/openedx/devstack#getting-started>`_ instructions.

2. Start up LMS, if it's not already started.

4. Within this project (frontend-app-authn), install requirements and start the development server:

   .. code-block::

      npm install
      npm start # The server will run on port 1999

5. Once the dev server is up, visit http://localhost:1999 to access the MFE

   .. image:: ./docs/images/frontend-app-authn-localhost-preview.png

   **Note:** Follow `Enable social auth locally <docs/how_tos/enable_social_auth.rst>`_ for enabling Social Sign-on Buttons (SSO) locally

Environment Variables/Setup Notes
=================================

This MFE is configured via environment variables supplied at build time.  All micro-frontends have a shared set of required environment variables, as documented in the Open edX Developer Guide under `Required Environment Variables <https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/developers_guide/micro_frontends_in_open_edx.html#required-environment-variables>`__.

The authentication micro-frontend also requires the following additional variable:

.. list-table:: Environment Variables
   :widths: 30 50 20
   :header-rows: 1

   * - Name
     - Description / Usage
     - Example

   * - ``LOGIN_ISSUE_SUPPORT_LINK``
     - The fully-qualified URL to the login issue support page in the target environment.
     - ``https://support.example.com``

   * - ``ACTIVATION_EMAIL_SUPPORT_LINK``
     - The fully-qualified URL to the activation email support page in the target environment.
     - ``https://support.example.com``

   * - ``PASSWORD_RESET_SUPPORT_LINK``
     - The fully-qualified URL to the password reset support page in the target environment.
     - ``https://support.example.com``

   * - ``AUTHN_PROGRESSIVE_PROFILING_SUPPORT_LINK``
     - The fully-qualified URL to the progressive profiling support page in the target environment.
     - ``https://support.example.com``

   * - ``TOS_AND_HONOR_CODE``
     - The fully-qualified URL to the Honor code page in the target environment.
     - ``https://example.com/honor``

   * - ``TOS_LINK``
     - The fully-qualified URL to the Terms of service page in the target environment.
     - ``https://example.com/tos``

   * - ``PRIVACY_POLICY``
     - The fully-qualified URL to the Privacy policy page in the target environment.
     - ``https://example.com/privacy``

   * - ``INFO_EMAIL``
     - The valid email address for information query regarding the target environment.
     - ``info@example.com``

   * - ``ENABLE_DYNAMIC_REGISTRATION_FIELDS``
     - Enables support for configurable registration fields on the MFE. This flag must be enabled to show any required registration field besides the default fields (name, email, username, password).
     - ``true`` | ``''`` (empty strings are falsy)

   * - ``ENABLE_PROGRESSIVE_PROFILING_ON_AUTHN``
     - Enables support for progressive profiling. If enabled, users are redirected to a second page where data for optional registration fields can be collected.
     - ``true`` | ``''`` (empty strings are falsy)

   * - ``DISABLE_ENTERPRISE_LOGIN``
     - Disables the enterprise login from Authn MFE.
     - ``true`` | ``''`` (empty strings are falsy)

   * - ``MFE_CONFIG_API_URL``
     - Link of the API to get runtime mfe configuration variables from the site configuration or django settings.
     - ``/api/v1/mfe_config`` | ``''`` (empty strings are falsy)  

   * - ``APP_ID``
     - Name of MFE, this will be used by the API to get runtime configurations for the specific micro frontend. For a frontend repo `frontend-app-appName`, use `appName` as APP_ID.
     - ``authn`` | ``''``


edX-specific Environment Variables
==================================

Furthermore, there are several edX-specific environment variables that enable integrations with closed-source services private to the edX organization, and might be unsupported in Open edX.

.. list-table:: edX-specific Environment Variables
   :widths: 30 50 20
   :header-rows: 1

   * - Name
     - Description / Usage
     - Example

   * - ``MARKETING_EMAILS_OPT_IN``
     - Enables support for opting in marketing emails that helps us getting user consent for sending marketing emails.
     - ``true`` | ``''`` (empty strings are falsy)

   * - ``SHOW_CONFIGURABLE_EDX_FIELDS``
     - For edX, country and honor code fields are required by default. This flag enables edX specific required fields.
     - ``true`` | ``''`` (empty strings are falsy)    

For more information see the document: `Micro-frontend applications in Open
edX <https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/developers_guide/micro_frontends_in_open_edx.html#required-environment-variables>`__.

How To Contribute
=================

Contributions are very welcome, and strongly encouraged! We've
put together `some documentation that describes our contribution process <https://edx.readthedocs.org/projects/edx-developer-guide/en/latest/process/index.html>`_.

Even though they were written with edx-platform in mind, the guidelines should be followed for Open edX code in general.

PR description template should be automatically applied if you are sending PR from github interface; otherwise you
can find it it at `PULL_REQUEST_TEMPLATE.md <https://github.com/openedx/frontend-app-authn/blob/master/.github/pull_request_template.md>`_

This project is currently accepting all types of contributions, bug fixes and security fixes.

Getting Help
============

If you're having trouble, we have discussion forums at
https://discuss.openedx.org where you can connect with others in the community.

Our real-time conversations are on Slack. You can request a `Slack
invitation`_, then join our `community Slack workspace`_.  Because this is a
frontend repository, the best place to discuss it would be in the `#wg-frontend
channel`_.

For anything non-trivial, the best path is to open an issue in this repository
with as many details about the issue you are facing as you can provide.

https://github.com/openedx/frontend-app-authn/issues

For more information about these options, see the `Getting Help`_ page.

.. _Slack invitation: https://openedx.org/slack
.. _community Slack workspace: https://openedx.slack.com/
.. _#wg-frontend channel: https://openedx.slack.com/archives/C04BM6YC7A6
.. _Getting Help: https://openedx.org/community/connect

The Open edX Code of Conduct
============================
All community members are expected to follow the `Open edX Code of Conduct <https://openedx.org/code-of-conduct/>`_.

People
======
The assigned maintainers for this component and other project details may be
found in `Backstage <https://backstage.openedx.org/catalog/default/group/vanguards>`_. Backstage pulls this data from the ``catalog-info.yaml``
file in this repo.

Reporting Security Issues
=========================

Please do not report security issues in public. Please email security@openedx.org.

Known Issues
============

None

License
=======

The code in this repository is licensed under the GNU Affero General Public License v3.0, unless
otherwise noted.

Please see `LICENSE <https://github.com/openedx/frontend-app-authn/blob/master/LICENSE>`_ for details.


==============================

.. |Build Status| image:: https://api.travis-ci.com/edx/frontend-app-authn.svg?branch=master
   :target: https://travis-ci.com/edx/frontend-app-authn
.. |Codecov| image:: https://img.shields.io/codecov/c/github/edx/frontend-app-authn
   :target: https://codecov.io/gh/edx/frontend-app-authn
.. |ci-badge| image:: https://github.com/openedx/edx-developer-docs/actions/workflows/ci.yml/badge.svg
   :target: https://github.com/openedx/edx-developer-docs/actions/workflows/ci.yml
   :alt: Continuous Integration
.. |semantic-release| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
   :target: https://github.com/semantic-release/semantic-release