new base npis-docs

This commit is contained in:
2025-10-16 09:01:38 +03:00
parent 6a64eac91c
commit d2961071d9
62 changed files with 14836 additions and 0 deletions

View File

@@ -0,0 +1,31 @@
---
sidebar_position: 1
sidebar_label: 'admin console login'
---
# Admin Console
Its users granted with the superuser admin role(those within the admin user group) who interact with the NPIS-IAM's backend configuration interface called the **admin console**. It is preconfigured with an admin account out of the box. This account will allow you to create an admin that can log into the master realms administration console so that admin can start creating realms, users and register applications to be secured by NPIS-IAM.
## Video Tutorial
import videojs from 'video.js';
<video id="my-video" class="vjs-fill vjs-default-skin" controls preload="auto" width="100%" height="100%" poster="/img/user-guide/login.png" >
<source src="/videos/user-guide/admin/admin-login.webm" type="video/webm"/>
</video>
## Reference instructions
Please follow the instructions below:
### login
The NPIS server is accessible at **npis.go.ug**, and the admin user accesses the admin console at the http://npis.go.ug:8080/auth/ URL or directly to the login http://npis.go.ug:8080/auth/admin URL.
![NPIS Admin console login](/img/user-guide/admin-console-login.png)
Click the **administration console** link on the Welcome Page and enter the **username** and **password**.
![NPIS Admin console login](/img/user-guide/login.png)
The left drop down menu allows the admin to pick a realm they would want to manage or to create a new one. The right drop down menu allows the admin to view admin user account or logout. Simply hovering the mouse over any question mark ? icon reveals about a certain feature, button, or field within the Admin Console, This will pop up tooltip text to describe the area of the console interested in. The image below shows the tooltip in action
![NPIS Admin console login](/img/user-guide/admin-console.png)

View File

@@ -0,0 +1,38 @@
---
sidebar_position: 1
sidebar_label: 'create realm'
---
# Realms
The core concept in NPIS-IAM is a Realm. A realm secures and manages security metadata for a set of users and registered clients. Users can be created within a specific realm within the Administration console. Roles (permission types) can be defined at the realm level and the admin can also set up user role mappings to assign these permissions to specific users.
## Video Tutorial
import videojs from 'video.js';
<video id="my-video" class="vjs-fill vjs-default-skin" controls preload="auto" width="100%" height="100%" poster="/img/user-guide/create-realm.png" >
<source src="/videos/user-guide/admin/admin-login.webm" type="video/webm"/>
</video>
## Reference instructions
Please follow the instructions below:
### The Master Realm
NPIS_IAM is preconfigured with a pre-defined realm. This initial realm is the **master realm**. It is the highest level in the hierarchy of realms. Admin accounts in this realm have permissions to view and manage any other realm created. The initial admin account, is created in the master realm. Also, the initial login to the admin console will also be via the master realm.
The master realm isn't to be used to manage the users and applications in NPIS. It is reserved to be used for super admins to create and manage the realms in NPIS. Following this security model helps prevent accidental changes and follows the tradition of permitting user accounts access to only those privileges and powers necessary for the successful completion of their current task.
<!-- It is possible to disable the master realm and define admin accounts within each individual new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts. -->
![NPIS Admin console login](/img/user-guide/create-realm.png)
The left drop down menu allows the admin to pick a realm they would want to manage or to create a new one.
Creating a new realm is very simple. Mouse over the top left corner drop down menu that is titled with Master. If you are logged in the master realm this drop down menu lists all the realms created. The last entry of this drop down menu is always Add Realm. Click this to add a realm.
![NPIS Admin console login](/img/user-guide/new-realm.png)
This menu option will bring you to the `Add Realm` page. Adding a new NPIS realm requires the admin to fill a mandatory name field, checking an option enable button which straight away enables the realm, click the `Create` button. Alternatively you can import a JSON document that defines your new realm. This will be provided later in more detail in the **Export and Import** subsection.
After creating the realm you are brought back to the main Admin Console page. The current realm will now be set to the realm you just created. You can switch between managing different realms by doing a mouse over on the top left corner drop down menu.

View File

@@ -0,0 +1,52 @@
---
sidebar_position: 1
sidebar_label: 'email settings'
---
# Email Settings
NPIS-IAM sends emails to users to verify their email address, when they forget their passwords, or when an admin needs to receive notifications about a server event. To enable NPIS_IAM to send emails the admin needs to configure SMTP server settings. This is configured per realm.
## Video Tutorial
import videojs from 'video.js';
<video id="my-video" class="vjs-fill vjs-default-skin" controls preload="auto" width="100%" height="100%" poster="/img/user-guide/email-settings.png" >
<source src="/videos/user-guide/admin/admin-login.webm" type="video/webm"/>
</video>
## Reference instructions
Please follow the instructions below:
### Email Tab
As emails are used for recovering usernames and passwords its recommended to use SSL or TLS, especially if the SMTP server is on an external network. To enable SSL click on Enable SSL or to enable TLS click on Enable TLS. You will most likely also need to change the Port (the default port for SSL/TLS is 465).
If your SMTP server requires authentication click on Enable Authentication and insert the Username and Password.
![NPIS Admin console login](/img/user-guide/email-settings.png)
* Host
- Host denotes the SMTP server hostname used for sending emails.
* Port
- Port denotes the SMTP server port.
* From
- From denotes the address used for the From SMTP-Header for the emails sent.
* From Display Name
- From Display Name allows to configure a user friendly email address aliases (optional). If not set the plain From email address will be displayed in email clients.
* Reply To
- Reply To denotes the address used for the Reply-To SMTP-Header for the mails sent (optional). If not set the plain From email address will be used.
* Reply To Display Name
- Reply To Display Name allows to configure a user friendly email address aliases (optional). If not set the plain Reply To email address will be displayed.
* Envelope From
- Envelope From denotes the Bounce Address used for the Return-Path SMTP-Header for the mails sent (optional).

View File

@@ -0,0 +1,41 @@
---
sidebar_position: 1
sidebar_label: 'ssl'
---
# Secure Socket Layer/Transport Layer Security
Each realm has an SSL Mode associated with it. The SSL Mode defines the SSL/HTTPS requirements for interacting with the realm. Browsers and applications that interact with the realm must honor the SSL/HTTPS requirements defined by the SSL Mode or they will not be allowed to interact with the server.
## Video Tutorial
import videojs from 'video.js';
<video id="my-video" class="vjs-fill vjs-default-skin" controls preload="auto" width="100%" height="100%" poster="/img/user-guide/ssl-mode.png" >
<source src="/videos/user-guide/admin/admin-login.webm" type="video/webm"/>
</video>
## Reference instructions
Please follow the instructions below:
### SSL Mode
NPIS-IAM generates a self-signed certificate which unfortunately isn't secure, and shouldonly be used for testing purposes installing a CA-signed certificate in NPIS-IAM itself or on areverse proxy in front of the NPIS-IAM. The NPIS admin is advised to procure a **wildcard** for the domain npis.go.ug from a credible certificate authority.
![NPIS Admin console login](/img/user-guide/ssl-mode.png)
To configure the SSL Mode of a created or existing realm, the admin needs to click on the Realm Settings left menu item and go to the Login tab.
The **Require SSL** option allows you to pick the SSL Mode you want. Here is an explanation of each mode:
* external requests
- Users can interact with NPIS-IAM without SSL so long as they stick to private IP addresses like localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x, and 172.16.x.x. Any attempt to access NPIS-IAM without SSL from a non-private IP address you will get an error.
* none
- NPIS-IAM does not require SSL. This should really only be used in testing
* all requests
- NPIS-IAM requires SSL for all IP addresses.

View File

@@ -0,0 +1,110 @@
---
sidebar_position: 2
sidebar_label: 'core terms and concepts'
---
# System Administration Guide
NPIS-IAM (Identity Access Management) as an Identity Management (IDM) provider, is a single sign on microservice for for all other microservices that consititute NPIS and all RESTful web services that external stakeholders use to interface with NPIS. The goal of NPIS-IAM is to make security simple so that they are easily tailorable to the specific requirements of the petroleum supply department and the ministry in general. NPIS-IAM provides customizable features (user interfaces) for the admin to configure all units of functionality regarding login, registration, administration, and account management. As was requested in [section 3.0 of the ToR](../../project-requirements/ToR#row-one) and [section 10.0 of the ToR](../../project-requirements/ToR#10.0), the NPIS-IAM as an integration platform to hook it into existing LDAP and Active Directory servers of the petroleum supply department or ministry in general as well as delegate authentication to third party identity providers like NITA-U's unified ID system for all government MDA systems.
## How NPIS-IAM Works?
Decades long past experience with GoU entreprise clientele who demanded integration of user Federation, Identity and Service Provider capabilities, as part of Identity Management solutions required the consultant to join the [2011 PicketLink project's global call](https://www.picketlink.org/) for Java EE (Entreprise Edition) applications engineering teams to collaborate to what was a central hub for all security related efforts required for **Red Hat** Middleware integration. PicketLink was and still is a security framework providing a rich set of capabilities for Java EE applications including Authentication, Authorization or Permissions APIs and flexible IDM solution.
![picketlink](/img/user-guide/PicketLink.png)
The consultant has since extended features on top of PicketLink that make up a toolbox of different useful APIs and helper classes in identity and security areas for GoU entreprise clientele before and after the [merge of all key features of PicketLink into **Keycloak** in 2015](https://www.picketlink.org/news/2015/03/10/PicketLink-and-Keycloak-project-merge/) which was done to combine the strengths of both projects and providing their communities a single polished and unified security solution. However, the custom features, like inclusion of NITA-U's UGPass and My-UG implementations of identity that have been developed and maintained upstream via the original picketlink codebase through the decades, do make the current NPIS-IAM microservice functions similars but also differently from the now widely known Keycloak.
<!-- [ToR](../../project-requirements/ToR#compliance-matrix-to-the-system-specifications) SAML (Security Assertion Markup Language) -->
## Core concepts and terms
Consider these core concepts and terms before attempting to use NPIS-IAM (Identity Access Management) to secure your web applications and REST services.
### users
Users are entities that are able to log into the system. They can have attributes associated with themselves like email, username, address, phone number, and birthday. They can be assigned group membership and have specific roles assigned to them.
### authentication
The process of identifying and validating a user.
### authorization
The process of granting access to a user.
### credentials
Credentials are pieces of data that NPIS-IAM uses to verify the identity of a user. Some examples are passwords, one-time-passwords, digital certificates, or even fingerprints.
### roles
Roles identify a type or category of user. Admin, Workflow Modeller, form designer, and client users are all typical roles that may exist in an organization. NPIS-IAM assigns access and permissions to specific roles rather than individual users as dealing with users can be too fine-grained and hard to manage.
### user role mapping
A user role mapping defines a mapping between a role and a user. A user can be associated with zero or more roles. This role mapping information can be encapsulated into tokens and assertions so that applications can decide access permissions on various resources they manage.
### composite roles
A composite role is a role that can be associated with other roles. For example a superuser composite role could be associated with the npis-admin and npis-designer roles. If a user is mapped to the superuser role they also inherit the admin and form-designer roles.
### groups
Groups manage groups of users. Attributes can be defined for a group. The admin can map roles to a group as well. Users that become members of a group inherit the attributes and role mappings that group defines.
### realms
A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control. For example, internal PSD users can isolated from external client (OMC) users for a difference in their user profile attributes.
### clients
Clients are entities that can request NPIS-IAM to authenticate a user. Most often, clients are applications and services that want to use NPIS-IAM to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request identity information or an access token so that they can securely invoke other services on the network that are secured by NPIS-IAM. For example, NPIS microservices like the form-management engine or BPM workflow engine or the NPIS-Web user interface do use the NPIS-IAM to authenticate users.
<!-- ### client adapters
Client adapters are plugins that you install into your application environment to be able to communicate and be secured by NPIS-IAM (Identity Access Management). NPIS-IAM (Identity Access Management) has a number of adapters for different platforms that you can download. There are also third-party adapters you can get for environments that we dont cover. -->
### consent
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process. After a user provides their credentials, NPIS-IAM will pop up a screen identifying the client requesting a login and what identity information is requested of the user. User can decide whether or not to grant the request.
### client scopes
When a client is registered, the admin must define protocol mappers and role scope mappings for that client. It is often useful to store a client scope, to make creating new clients easier by sharing some common settings. This is also useful for requesting some claims or roles to be conditionally based on the value of scope parameter. NPIS-IAM provides the concept of a client scope for this.
### client role
Clients can define roles that are specific to them. This is basically a role namespace dedicated to the client.
### identity token
A token that provides identity information about the user. Part of the OpenID Connect specification. For example, external system interface requirements from other stakeholders like URA do impose a conditional regular polling of API transactional data, they can only be identified with an indetity token.
### access token
A token that can be provided as part of an HTTP request that grants access to the service being invoked on. This is part of the OpenID Connect and OAuth 2.0 specification. like identity token above, external system interface requirements from other stakeholders like URA do impose a conditional regular polling of API transactional data, can use access tokens.
### assertion
Information about a user. This usually pertains to an XML blob data that is included in a SAML authentication response that provided identity metadata about an authenticated user.
### service account
Each client has a built-in service account which allows it to obtain an access token.
### direct grant
A way for a client to obtain an access token on behalf of a user via a REST invocation.
### protocol mappers
For each client you can tailor what claims and assertions are stored in the OIDC token or SAML assertion. The admin does this per client by creating and configuring protocol mappers.
### session
When a user logs in, a session is created to manage the login session. A session contains information like when the user logged in and what applications have participated within single-sign on during that session. Both admins and users can view session information.
### user federation provider
NPIS-IAM can store and manage users. Often, organizations like the PSD already have LDAP or Active Directory services that store user and credential information. The NPIS admin can point NPIS-IAM to validate credentials from those external stores and pull in identity information. However, since NPIS also has external OMC users who are not part of the PSD (with LDAP), this requires the admin to create another realm for either group of users.
### identity provider
An identity provider (IDP) is a service that can authenticate a user. NPIS-IAM is an IDP.
### identity provider federation
NPIS-IAM (Identity Access Management) can be configured to delegate authentication to one or more IDPs. Social login via Facebook or Google+ is an example of identity provider federation. The admin can also hook NPIS-IAM to delegate authentication to any other OpenID Connect or SAML 2.0 IDP.
### identity provider mappers
When doing IDP federation the admin can map incoming tokens and assertions to user and session attributes. This helps the admin propagate identity information from the external IDP to the client requesting authentication.
### required actions
Required actions are actions a user must perform during the authentication process. A user will not be able to complete the authentication process until these actions are complete. For example, an admin may schedule users to reset their passwords every month. An update password required action would be set for all these users.
### authentication flows
Authentication flows are work flows a user must perform when interacting with certain aspects of the system. A login flow can define what credential types are required. A registration flow defines what profile information a user must enter and whether something like reCAPTCHA must be used to filter out bots. Credential reset flow defines what actions a user must do before they can reset their password.
### events
Events are audit streams that admins can view and hook into.
<!-- ### themes
Every screen provided by NPIS-IAM is backed by a theme. Themes define HTML templates and stylesheets which you can override as needed.
import Stress from '@site/src/components/Stress.js';
<Stress color="#25c2a0">NPIS green</Stress>
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`);
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
-->

View File

@@ -0,0 +1,75 @@
---
sidebar_position: 1
sidebar_label: 'Video Course'
---
# Steps
This guides walks through the user the step by step instructions on how the NPIS sysyem administratos logs into the system.
import videojs from 'video.js';
<!--
import videojsPlaylistPlugin from 'videojs-playlist';
width="640" height="360"
width="100%" height="100%"
src="/videos/user-guide/admin/admin-login.webm" type="video/webm"
src="//vjs.zencdn.net/v/oceans.mp4 type="video/mp4"
src="/videos/oceans.mp4 type="video/mp4"
src="/videos/Big_Buck_Bunny_360_10s_1MB.mp4" type="video/mp4"
src="/videos/Big_Buck_Bunny_360_10s_1MB.webm" type="video/webm"
<p class="vjs-no-js">
To view this video please enable JavaScript, and consider upgrading to a web browser that
<a href="https://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a>
</p>
class="video-js vjs-default-skin"
-->
<video id="my-video" class="vjs-fill vjs-default-skin" controls preload="auto" width="100%" height="100%" poster="/videos/user-guide/admin/admin-login.png" >
<source src="/videos/user-guide/admin/admin-login.webm" type="video/webm"/>
</video>
User guides provided in this section are proxied to serve as both training and **User Acceptance Tests (UATs)** for all NPIS users as detailed in the [Software Requirements Specification (SRS) Document](../project-requirements/SRS#system-users-and-characteristics) to execute their respective [system roles in the same SRS Document](../project-requirements/SRS#user-roles).
## Getting Started
Users reading this guide are to select their respective user group/roles in the sidebar on the left under User Guides to complete these UATs and training by expanding the menu to further reveal a breakdown of all the usecases for the system tasks executable by their user role/group.
:::tip[Specialized Users]
Executing certain system task roles does require the user to have the neccesary knowledge underlying the technical standards used to
implement the features and functionality pertaining to those tasks. For example:
The Admin User Guides do require the admin user to have the technical know how on technical standard (IETF RFC 6749 and 6750) known as **OpenID Connect (OIDC)**, an interoperable authentication protocol based on the OAuth 2.0 framework of specifications.
:::
:::danger[Missconfigured System]
The failure for a certain user to configure the system right, most certainly causes the system to be unusable.
:::
:::info[Learning Resources]
The user guide therefore provides such an introduction to the user in form of a prime, or brief introductory notes on the subject matter. An in the case the where is the is more ground to cover beyond the scope of the project, the guide refers the users to curated resources online like links to learning material, standards, or vendor documentation.
:::
## username
This is the identifier that the user was given, or this case, the admin being the system first user, its the superuser id that system assigns
the first user.
## password
This is the

View File

@@ -0,0 +1,24 @@
---
sidebar_position: 1
sidebar_label: 'goals and objectives'
---
# Goals and Objectives
Purposefully, this is to guide the system administrator to configure NPIS' access, identity and security requirements using the NPIS-IAM (Identity Access Management) microservice for NPIS' users, other microservices and external exterfaces by following the step by step guide.
:::danger[Misconfigurations]
Any misconfiguration on any of NPIS' access and identity requirements listed, will result in NPIS improper setup or unusability.
That is, access, identity and security settings and configurations of the system's production environment, are functional requirements, without which the system cannot function. These aren't casual on and off switches but rather, the administrator alone is solely liable for the loss and damage that result from misconfigured settings.
:::
| # | Objective | Goal |
|:----------|:-----------|:-----------|
| 1 | core terms and concepts | a quick prime to help users with the admin role to aquiate themselves with the terminologies and conceptul understanding of technical reasoning behind Authorization and Authentication with regard to OAuth2.0 and openIDConnect standards as single-sign-on protocols |
| 2 | admin console login | learn to access the admin console's admin account |
| 3 | create realms | learn to isolate users, their credentials, roles, groups and clients, role mappings into a logical container called a realm in the openIDConnect world |
| 4 | email settings | learn to configure the NPIS-IAM microservice's email as part of the admin account's form of communication to users and other systems |
| 5 | ssl | guide the admin on how to configure ssl for NPIS-IAM microservice
| 6 | | |

View File

@@ -0,0 +1,20 @@
---
sidebar_position: 1
---
import ReactPlayer from "react-player"
# Admin Login
Documents are **groups of pages** connected through:
- a **sidebar**
- **previous/next navigation**
- **versioning**
## Create your first Doc
<div className="video__wrapper">
<ReactPlayer className="video__player" controls height="100%" src="/videos/user-guide/admin/admin-login.webm" width="100%" />
</div>