111 lines
11 KiB
Plaintext
111 lines
11 KiB
Plaintext
|
---
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
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 don’t 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_!
|
|||
|
|
|
|||
|
|
-->
|