.. _aaa:

Authentication, Authorization and Auditing
=============================================

The PTT API is secured using the `ska-aaa-authhelpers library <https://developer.skao.int/projects/ska-aaa-authhelpers/en/latest/?badge=latest>`_.
This means to use the API, a valid token with the correct role and scopes for the specific API resource must be included in the request.
The PTT UI have login functionality and will include the tokens in the requests by default when logged in.

For more information on the general AAA architecture, see `Solution Intent <https://confluence.skatelescope.org/pages/viewpage.action?pageId=159387107>`_

Test AAA on test deployment using PIPELINE_TESTS_DEPLOYMENT flag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To turn AAA test deployment off / on user need to update environment variable into helm charts.

The purpose of this environment variable, is likely to test AAA on test deployment using fake tokens

Steps to add and change the pipeline_test_deployment environment variable in 'values.yaml' file:

   * Setting the environment variable:

      The PIPELINE_TESTS_DEPLOYMENT variable enable to test AAA on pipelines 
      Meaning of flag ``true`` means you can go with fake token to test your AAA code.
      .. code::

            if getenv("PIPELINE_TESTS_DEPLOYMENT", "false") == "true":
                Permissions = partial(
                    Requires, audience=AUDIENCE, keys=TEST_PUBLIC_KEYS, issuer=TEST_ISSUER
                )

How to Register Your Apps on Entra ID
======================================

Overview
~~~~~~~~~
To register your applications, you need to create separate registrations for:

* API / Backend application
* UI Frontend application

Raising an IT New Request Ticket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Navigate to the IT Service Portal `Portal link <https://jira.skatelescope.org/servicedesk/customer/portal/1/group/5>`_ and select:

   * Category: "Logins and Accounts"
   * Sub-category: "Delegated Security Group Creation"

Guidelines for Request Submission
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Mandatory Fields
~~~~~~~~~~~~~~~~~~~~

1.1. Application Register
~~~~~~~~~~~~~~~~~~~~~~~~~~
* As per depend on your request type if you are registering new app then select
  New application registration otherwise select Modify existing one.

1.2. Name of Application
~~~~~~~~~~~~~~~~~~~~~~~~~~
* Provide name of your application which you want to register.
  e.g. name same like your repository name.

1.3. Platform Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* For UI Applications: Select "Single Page Application".
* For Backend Applications: Select "Web".

1.4. Redirect URIs Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Common Environment URI: ``https://k8s.stfc.skao.int``
  (Applies to dev, integration, and staging environments)
* Local Development URI: Add based on your application
  
  Example: For Python FastAPI running on port 8000
  Use: ``http://localhost:8000``

1.5. Purpose for SSO on Azure?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Add purpose like registration of app to enable AAA.

1.6. Who Requires Access
~~~~~~~~~~~~~~~~~~~~~~~~~~
* Add the list of SKAO user names which you want to provide access to your app.

1.7. Client Secret Needed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Make it as 'Yes'.

1.8. Additional Options
~~~~~~~~~~~~~~~~~~~~~~~~
* Enable special request options if needed.


Raising an IT Ticket to update existing registered app.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow the same Portal link which used while registration app.
Provide NA on fields which you don't want to update e.g. if you don't want to update `Who requires access`
list then provide NA. Remember to add previous ticket number in `Similar Previous Request`

Supported Scopes for PTT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* In ``auth.py`` module ``Scopes`` class defines the available scopes for PTT.