Documenting the login functionality (#317)

README.md

@@ -41,13 +41,14 @@ installation. Use `asdf plugin update --all` to update plugins and get access to
 newer versions of tools.
 
 Create your `.env` from the `.env.example` template
-* GOVUK_NOTIFY_API_KEY, using the citest api key
-* GOVUK_NOTIFY_GENERIC_EMAIL_TEMPLATE_ID, template id used by mail-notify
-* AZURE_CLIENT_ID, to access application platform
-* AZURE_CLIENT_SECRET
-* AZURE_TENANT_ID
-* REDIS_URL, redis url for sidekiq
-* LOCAL_USER_EMAIL, your education.gov.uk email address to access the system_admin section
+
+- GOVUK_NOTIFY_API_KEY, using the citest api key
+- GOVUK_NOTIFY_GENERIC_EMAIL_TEMPLATE_ID, template id used by mail-notify
+- AZURE_CLIENT_ID, to access application platform
+- AZURE_CLIENT_SECRET
+- AZURE_TENANT_ID
+- REDIS_URL, redis url for sidekiq
+- LOCAL_USER_EMAIL, your education.gov.uk email address to access the system_admin section
 
 ### Manual development setup
 
@@ -56,15 +57,14 @@ Create your `.env` from the `.env.example` template
 3. Run `bin/rails db:setup` to set up the database development and test schemas
 4. Run `bundle exec foreman start -f Procfile.dev` to launch the app on <http://localhost:3000>
 
-
 ### Docker based development setup
+
 1. Run `tilt up -- --local-app` to launch the app on <http://localhost:3000>
 
 You can also run `tilt up` that way you will be building the image definied by the Dockerfile
 
 This option will start the application and run the `db/seed.rb` file.
 
-
 ## Running specs
 
 Run the full test suite with:
@@ -73,7 +73,6 @@ Run the full test suite with:
 bundle exec rake
 ```
 
-
 ## Platform
 
 You need to request `digitalauth.education.gov.uk` account before being able to access a deployed
@@ -82,25 +81,22 @@ Once your account active you need to request your temporary access token at
 [portal.azure.com](https://portal.azure.com/#view/Microsoft_Azure_PIMCommon/ActivationMenuBlade/~/azurerbac)
 
 The following environment are available on the platform:
-* qa
-* review, deployed on demand by adding the `deploy` label on a PR
-* staging
-* production
 
+- qa
+- review, deployed on demand by adding the `deploy` label on a PR
+- staging
+- production
 
 ### Environment variables
 
 When adding / removing or editing along side the code changes you will need to update the all the
 available environments.
 Run the following command `make <environment> edit-app-secrets`
 
-
 ### SSH access
 
 Access a deploy with the command `make <environment> ssh`.
 
-
-
 ## Architectural Decision Record
 
 See the [docs/adr](docs/adr) directory for a list of the Architectural Decision
@@ -115,6 +111,11 @@ adr new "Title of ADR"
 ```
 
 ### Contingency
+
 This service does not offer any out of hours SLAs and there will be not on call shift.
 
 Any incidents observed should follow [the incident reporting guidance](https://tech-docs.teacherservices.cloud/operating-a-service/incident-playbook.html)
+
+## Azure Login
+
+See [docs/azure-login.md](docs/azure-login.md) for details on how to log in functionality works.

docs/azure-login.md

@@ -0,0 +1,68 @@
+# Understanding Login Functionality
+
+## Introduction:
+
+The login functionality in our application is crucial for securing our platform and ensuring that only authorized individuals have access.
+It is facilitated through the integration of Devise, Omniauth, and Azure AD strategy.
+This document elaborates on the process of configuring and operating the login functionality, especially focusing on its interaction with Azure App Registration.
+
+1. **Key Components**:
+   - **Devise**: A flexible authentication solution for Rails based on Warden.
+   - **Omniauth**: A library that standardizes multi-provider authentication for web applications.
+   - **Azure Strategy**: A strategy employed by Omniauth to authenticate with Azure AD.
+2. **Azure AD and App Registration**:
+   - Our application connects to an Azure App Registration configured on Azure within the DfE tenant.
+   - The specific app registration we use is named `get-a-teacher-relocation-payment`. With suffix of 'local', 'qa', 'staging', 'production' for each environment.
+3. **Configuration for GitHub PR Review Apps**:
+
+   - The `local` app registration is configured to work with GitHub PR review apps when adding the `deploy` label.
+   - To make it work for a new PR review app deployment, update the list of redirect URIs in the Azure app registration configuration. Include the new URI corresponding to the PR number of the deployed GitHub review app.
+
+4. **Login Process**:
+   - Navigate to the login page.
+   - You will be redirected to Azure for authentication. Log in using an `@education.gov.uk` email address.
+   - Upon successful authentication with Azure, you get redirected back, and then the application checks against an internal list of authorized users.
+   - If the email address is on the list, the user is logged in; otherwise, access is denied.
+5. **Rails App Internal User List**:
+
+   - Our Rails application maintains an internal list of users authorized to log in.
+   - This list is crucial for an additional layer of access control beyond Azure authentication.
+
+6. **Code Snippet** (For illustration):
+
+```ruby
+# config/initializers/devise.rb
+Devise.setup do |config|
+  config.omniauth(:azure_activedirectory_v2,
+                  client_id: ENV.fetch("AZURE_CLIENT_ID", nil),
+                  client_secret: ENV.fetch("AZURE_CLIENT_SECRET", nil),
+                  tenant_id: ENV.fetch("AZURE_TENANT_ID", nil))
+end
+
+# app/controllers/users/omniauth_callbacks_controller.rb
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  skip_before_action :check_service_open!
+
+  def azure_activedirectory_v2
+    response_params = request.env["omniauth.auth"]["info"]
+    @user = User.find_by(email: response_params["email"])
+
+    if @user
+      sign_in_and_redirect(@user, event: :authentication)
+    else
+      flash[:alert] = t("omniauth_callbacks.no_account")
+      redirect_to(root_path)
+    end
+  end
+
+  def after_omniauth_failure_path_for(_scope)
+    root_path
+  end
+end
+```
+
+This snippet demonstrates the setup of Devise and Omniauth with the Azure strategy and a simplified user model that finds or creates a user based on the Azure authentication data.
+
+## Conclusion:
+
+Understanding and configuring the login functionality correctly is vital for the security and proper functioning of our application. Following the outlined steps ensures a seamless authentication process, leveraging Azure AD while maintaining an extra layer of access control through an internal user list.