starlingx/docs
Code Issues Proposed changes

Updated OIDC app docs

Browse Source 
This commit does 2 changes in the OIDC app docs:

1) The docs were updated to be explicit about the OIDC app being
   compatible with LDAP servers and not only with the Windows Active
   Directory;
2) The page "Centralized OIDC Authentication Setup for Distributed
   Cloud" was renamed to "Centralized vs Distributed OIDC Authentication
   Setup" and was moved in the index of pages to be right below the
   first page "Overview of LDAP Servers". The idea is to use this page
   as a entry point for someone learning about the OIDC app, because
   every user must decide between a centralized and a distributed setup
   and because this page has links to all other pages except
   "Deprovision LDAP Server Authentication".

Story: 2010738
Task: 49455

Change-Id: I61c5b7f322ac8159b649c70eeaa0195d97ab12c7
Signed-off-by: Joao Victor Portal <Joao.VictorPortal@windriver.com>
This commit is contained in:
Joao Victor Portal 2024-01-23 20:23:44 -03:00
parent 49b0e62c09
commit daa431e385
16 changed files with 110 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/archive/configuration/k8s_auth_winactivedir.rst
View File

@ -5,7 +5,7 @@ Authenticate Kubernetes Users with Windows Active Directory Server
.. note::
This guide was replaced by:
:ref:`Overview of Windows Active Directory <overview-of-windows-active-directory>`
:ref:`Overview of LDAP Servers <overview-of-ldap-servers>`
This guide describes how to authenticate users of the Kubernetes API via a
remote Windows Active Directory server, using the oidc-auth-apps application.

43
doc/source/security/kubernetes/centralized-oidc-authentication-setup-for-distributed-cloud.rst → doc/source/security/kubernetes/centralized-vs-distributed-oidc-auth-setup.rst
View File

@ -1,27 +1,31 @@
.. afi1590692698424
.. _centralized-oidc-authentication-setup-for-distributed-cloud:
.. _centralized-vs-distributed-oidc-auth-setup:
===========================================================
Centralized OIDC Authentication Setup for Distributed Cloud
===========================================================
====================================================
Centralized vs Distributed OIDC Authentication Setup
====================================================
In a |prod-dc| configuration, you can configure |OIDC| authentication
in a distributed or centralized setup.
In a |prod-dc| configuration, you can configure |OIDC| authentication in a
distributed or centralized setup. For other configurations, like |AIO-SX|,
|AIO-DX| or Standard Cloud, follow the instructions in the distributed setup
documented below.
.. _centralized-oidc-authentication-setup-for-distributed-cloud-section-ugc-xr5-wlb:
.. _centralized-vs-distributed-oidc-auth-setup-section-ugc-xr5-wlb:
-----------------
Distributed Setup
-----------------
For a distributed setup, configure the **kube-apiserver**, and
For a distributed setup, configure the **kube-apiserver** and the
**oidc-auth-apps** independently for each cloud, System Controller, and all
subclouds. For more information, see:
subclouds. The **oidc-auth-apps** runs on each active controller of the setup
and the **kube-apiserver** is configured to point to the local instance of
**oidc-auth-apps**. For more information, see:
.. _centralized-oidc-authentication-setup-for-distributed-cloud-ul-gjs-ds5-wlb:
.. _centralized-vs-distributed-oidc-auth-setup-ul-gjs-ds5-wlb:
- Configure Kubernetes for |OIDC| Token Validation
@ -41,12 +45,12 @@ subclouds. For more information, see:
All clouds **oidc-auth-apps** can be configured to communicate to the same
or different remote Windows Active Directory servers, however, each cloud
manages |OIDC| tokens individually. A user must login, authenticate, and get
an |OIDC| token for each cloud independently.
or different authentication servers (Windows Active Directory and/or |LDAP|).
However, each cloud manages |OIDC| tokens individually. A user must login,
authenticate, and get an |OIDC| token for each cloud independently.
.. _centralized-oidc-authentication-setup-for-distributed-cloud-section-yqz-yr5-wlb:
.. _centralized-vs-distributed-oidc-auth-setup-section-yqz-yr5-wlb:
-----------------
Centralized Setup
@ -65,7 +69,7 @@ For a centralized |OIDC| authentication setup, use the following procedure:
.. rubric:: |proc|
#. Configure the **kube-apiserver** parameters on the System Controller and
each subcloud during bootstrapping, or by using the **system
each subcloud either during bootstrapping or by using the **system
service-parameter-add kubernetes kube_apiserver** command after
bootstrapping the system, using the System Controller's floating OAM IP
address as the oidc-issuer-url for all clouds.
@ -87,8 +91,9 @@ For a centralized |OIDC| authentication setup, use the following procedure:
<configure-kubernetes-for-oidc-token-validation-after-bootstrapping-the-system>`
#. On the System Controller only configure the **oidc-auth-apps**. For more
information, see :ref:`Configure OIDC Auth Applications <configure-oidc-auth-applications>`.
#. Configure the **oidc-auth-apps** only on the System Controller. For more
information, see :ref:`Configure OIDC Auth Applications
<configure-oidc-auth-applications>`
.. note::
For IPv6 deployments, ensure that the IPv6 OAM floating address is,
@ -102,7 +107,7 @@ For more information on configuring Users, Groups, Authorization, and
**kubectl** for the user and retrieving the token on subclouds, see:
.. _centralized-oidc-authentication-setup-for-distributed-cloud-ul-vf3-jnl-vlb:
.. _centralized-vs-distributed-oidc-auth-setup-ul-vf3-jnl-vlb:
- :ref:`Configure Users, Groups, and Authorization <configure-users-groups-and-authorization>`
@ -112,7 +117,7 @@ For more information on configuring Users, Groups, Authorization, and
For more information on Obtaining the Authentication Token, see:
.. _centralized-oidc-authentication-setup-for-distributed-cloud-ul-wf3-jnl-vlb:
.. _centralized-vs-distributed-oidc-auth-setup-ul-wf3-jnl-vlb:
- :ref:`Obtain the Authentication Token Using the oidc-auth Shell Script
<obtain-the-authentication-token-using-the-oidc-auth-shell-script>`

6
doc/source/security/kubernetes/configure-kubectl-with-a-context-for-the-user.rst
View File

@ -6,9 +6,9 @@
Configure Kubectl with a Context for the User
=============================================
You can set up the kubectl context for the Windows Active Directory
**testuser** to authenticate through the **oidc-auth-apps** |OIDC| Identity
Provider (dex).
You can set up the kubectl context for the Windows Active Directory or |LDAP|
server **testuser** to authenticate through the **oidc-auth-apps** |OIDC|
Identity Provider (dex).
.. rubric:: |context|

8
doc/source/security/kubernetes/configure-kubernetes-for-oidc-token-validation-after-bootstrapping-the-system.rst
View File

@ -36,7 +36,7 @@ you can do so at any time using service parameters.
- oidc-client-id=<client>
The value of this parameter may vary for different group
configurations in your Windows Active Directory server.
configurations in your Windows Active Directory or |LDAP| server.
- oidc-groups-claim=<groups>
@ -50,7 +50,7 @@ you can do so at any time using service parameters.
- oidc-username-claim=<email>
The values of this parameter may vary for different user
configurations in your Windows Active Directory server.
configurations in your Windows Active Directory or |LDAP| server.
The valid combinations of these service parameters are:
@ -75,7 +75,7 @@ you can do so at any time using service parameters.
~(keystone_admin)]$ system service-parameter-apply kubernetes
For more information on |OIDC| Authentication for subclouds, see
:ref:`Centralized OIDC Authentication Setup for Distributed Cloud
<centralized-oidc-authentication-setup-for-distributed-cloud>`.
:ref:`Centralized vs Distributed OIDC Authentication Setup
<centralized-vs-distributed-oidc-auth-setup>`.

6
doc/source/security/kubernetes/configure-kubernetes-for-oidc-token-validation-while-bootstrapping-the-system.rst
View File

@ -45,7 +45,7 @@ Validation after Bootstrapping the System
The values of the **username_claim**, and **groups_claim** parameters
could vary for different user and groups configurations in your Windows
Active Directory server.
Active Directory or |LDAP| server.
.. note::
For IPv6 deployments, ensure that the IPv6 OAM floating address in
@ -56,6 +56,6 @@ Validation after Bootstrapping the System
.. rubric:: |result|
For more information on |OIDC| Authentication for subclouds, see
:ref:`Centralized OIDC Authentication Setup for Distributed Cloud
<centralized-oidc-authentication-setup-for-distributed-cloud>`.
:ref:`Centralized vs Distributed OIDC Authentication Setup
<centralized-vs-distributed-oidc-auth-setup>`.

8
doc/source/security/kubernetes/configure-oidc-auth-applications.rst
View File

@ -7,13 +7,13 @@ Set up OIDC Auth Applications
=============================
The **oidc-auth-apps** application is a system application that enables the use
of a remote Windows Active Directory server or a |LDAP| server to authenticate
of a remote Windows Active Directory server or an |LDAP| server to authenticate
users of the Kubernetes API.
In this document, the |LDAP| server presented is the one present in the |prod|
deploy and will be called Local |LDAP| server. This |LDAP| server runs in the
controllers except for DC environments, where it runs only in the
SystemController's controllers.
deploy, called Local |LDAP| server. This |LDAP| server runs in the controllers
except for DC environments, where it runs only in the SystemController's
controllers.
The ``oidc-auth-apps`` is packaged in the ISO and uploaded by default.

2
doc/source/security/kubernetes/configure-users-groups-and-authorization.rst
View File

@ -7,7 +7,7 @@ Configure Users, Groups, and Authorization
==========================================
You can create a **user**, and optionally one or more **groups** that the
**user** is a member of, in your Windows Active Directory server.
**user** is a member of, in your Windows Active Directory or |LDAP| server.
.. rubric:: |context|

22
doc/source/security/kubernetes/deprovision-windows-active-directory-authentication.rst → doc/source/security/kubernetes/deprovision-ldap-server-authentication.rst
View File

@ -1,12 +1,13 @@
.. luo1591184217439
.. _deprovision-windows-active-directory-authentication:
.. _deprovision-ldap-server-authentication:
===================================================
Deprovision Windows Active Directory Authentication
===================================================
======================================
Deprovision LDAP Server Authentication
======================================
You can remove Windows Active Directory authentication from |prod-long|.
You can remove Windows Active Directory or |LDAP| authentication from
|prod-long|.
.. rubric:: |proc|
@ -52,13 +53,20 @@ You can remove Windows Active Directory authentication from |prod-long|.
~(keystone_admin)]$ system helm-override-update oidc-auth-apps oidc-client kube-system --reset-values
~(keystone_admin)]$ system helm-override-show oidc-auth-apps oidc-client kube-system
#. Remove secrets that contain certificate data.
~(keystone_admin)]$ system helm-override-update oidc-auth-apps secret-observer kube-system --reset
~(keystone_admin)]$ system helm-override-show oidc-auth-apps secret-observer kube-system
#. Remove secrets that contain certificate data. Depending on your
configuration, some secrets listed below may not exist.
.. code-block:: none
~(keystone_admin)]$ kubectl delete secret dex-ca-cert -n kube-system
~(keystone_admin)]$ kubectl delete secret oidc-auth-apps-certificate -n kube-system
~(keystone_admin)]$ kubectl delete secret wad-ca-cert -n kube-system
~(keystone_admin)]$ kubectl delete secret local-ldap-ca-cert -n kube-system
~(keystone_admin)]$ kubectl delete secret local-dex.tls -n kube-system
~(keystone_admin)]$ kubectl delete secret dex-client-secret -n kube-system
~(keystone_admin)]$ kubectl delete secret wadcert -n kube-system
#. Remove any |RBAC| RoleBindings added for |OIDC| users and/or groups.

16
doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst
View File

@ -64,18 +64,18 @@ SSH User Authentication Using Windows Active Directory
sssd-support-5fb6c4b0320b
**********************************************************
K8S API User Authentication Using Windows Active Directory
**********************************************************
*********************************************
K8S API User Authentication Using LDAP Server
*********************************************
.. toctree::
:maxdepth: 1
overview-of-windows-active-directory
overview-of-ldap-servers
centralized-vs-distributed-oidc-auth-setup
configure-kubernetes-for-oidc-token-validation-while-bootstrapping-the-system
configure-kubernetes-for-oidc-token-validation-after-bootstrapping-the-system
configure-oidc-auth-applications
centralized-oidc-authentication-setup-for-distributed-cloud
configure-users-groups-and-authorization
configure-kubectl-with-a-context-for-the-user
@ -88,13 +88,13 @@ Obtain the Authentication Token
obtain-the-authentication-token-using-the-oidc-auth-shell-script
obtain-the-authentication-token-using-the-browser
Deprovision Windows Active Directory
************************************
Deprovision LDAP Server
***********************
.. toctree::
:maxdepth: 1
deprovision-windows-active-directory-authentication
deprovision-ldap-server-authentication
****************
Firewall Options

4
doc/source/security/kubernetes/obtain-the-authentication-token-using-the-browser.rst
View File

@ -21,8 +21,8 @@ refresh-token using the **oidc-auth-apps** |OIDC| client web interface.
``https://<oam-floating-ip-address>:30555``
#. If the |prod| **oidc-auth-apps** has been configured for multiple
'**ldap**' connectors, select the Windows Active Directory server for
authentication.
'**ldap**' connectors, select the Windows Active Directory or the |LDAP|
server for authentication.
#. Enter your Username and Password.

12
doc/source/security/kubernetes/obtain-the-authentication-token-using-the-oidc-auth-shell-script.rst
View File

@ -15,8 +15,8 @@ as well as on a remote workstation where you are running **kubectl** and
**helm** commands.
The **oidc-auth** script retrieves the ID token from Windows Active
Directory using the |OIDC| client, and **dex**, and updates the Kubernetes
credential for the user in the **kubectl** config file.
Directory or |LDAP| server using the |OIDC| client, and **dex**, and updates the
Kubernetes credential for the user in the **kubectl** config file.
.. _obtain-the-authentication-token-using-the-oidc-auth-shell-script-ul-kxm-qnf-ykb:
@ -84,4 +84,12 @@ credential for the user in the **kubectl** config file.
CLI, you must use the ``-p <password>`` option to run the command
non-interactively.
When the parameter ``-c <ip>`` is ommitted, the hostname
**oamcontroller** is used. This parameter can be ommitted when
**oidc-auth** is executed inside a |prod| active controller and the
**oidc-auth-apps** is running in this controller.
When the parameter ``-u <username>`` is ommitted, the Linux username of
the current logged in user is used.

31
doc/source/security/kubernetes/overview-of-ldap-servers.rst Normal file
View File

@ -0,0 +1,31 @@
.. tvb1581377605743
.. _overview-of-ldap-servers:
========================
Overview of LDAP Servers
========================
|prod-long| can be configured to use an |LDAP| compatible server, like a remote
Windows Active Directory server or the Local |LDAP| server, to authenticate
users of the Kubernetes API, using the **oidc-auth-apps** application.
The Local |LDAP| server is present in |prod| deploys. This server runs on the
controllers. The only exception is the |DC| environments, where this |LDAP|
server runs only on the SystemController's controllers, it is not present in
the subcloud's controllers.
The **oidc-auth-apps** application installs a proxy |OIDC| identity provider
that can be configured to proxy authentication requests to an |LDAP|'s identity
provider, such as Windows Active Directory or Local |LDAP|. For more
information, see `https://github.com/dexidp/dex
<https://github.com/dexidp/dex>`__. The **oidc-auth-apps** application also
provides an |OIDC| client for accessing the username and password |OIDC| login
page for user authentication and retrieval of tokens. An **oidc-auth** CLI
script can also be used for |OIDC| user authentication and retrieval of tokens.
In addition to installing and configuring the **oidc-auth-apps**
application, the admin must also configure Kubernetes cluster's
**kube-apiserver** to use the **oidc-auth-apps** |OIDC| identity provider for
validation of tokens in Kubernetes API requests.

26
doc/source/security/kubernetes/overview-of-windows-active-directory.rst
View File

@ -1,26 +0,0 @@
.. tvb1581377605743
.. _overview-of-windows-active-directory:
====================================
Overview of Windows Active Directory
====================================
|prod-long| can be configured to use a remote Windows Active Directory server
to authenticate users of the Kubernetes API, using the **oidc-auth-apps**
application.
The **oidc-auth-apps** application installs a proxy |OIDC| identity provider
that can be configured to proxy authentication requests to an |LDAP| (s)
identity provider, such as Windows Active Directory. For more information, see,
`https://github.com/dexidp/dex <https://github.com/dexidp/dex>`__. The
**oidc-auth-apps** application also provides an |OIDC| client for accessing the
username and password |OIDC| login page for user authentication and retrieval
of tokens. An **oidc-auth** CLI script can also be used for |OIDC| user
authentication and retrieval of tokens.
In addition to installing and configuring the **oidc-auth-apps**
application, the admin must also configure Kubernetes cluster's
**kube-apiserver** to use the **oidc-auth-apps** |OIDC| identity provider for
validation of tokens in Kubernetes API requests.

3
doc/source/security/kubernetes/remote-windows-active-directory-accounts.rst
View File

@ -10,6 +10,5 @@ Remote Windows Active Directory Accounts
Accounts and native Kubernetes |RBAC| policies for authentication and
authorization of users of the Kubernetes API, |CLI|, and Dashboard.
See :ref:`Overview of Windows Active Directory
<overview-of-windows-active-directory>` for more details.
See :ref:`Overview of LDAP Servers <overview-of-ldap-servers>` for more details.

3
doc/source/usertasks/kubernetes/kubernetes-user-tutorials-installing-kubectl-and-helm-clients-directly-on-a-host.rst
View File

@ -35,8 +35,7 @@ You will need the following information from your |prod| administrator:
local Kubernetes ServiceAccount.
.. xreflink For a Windows Active Directory user, see,
|sec-doc|: :ref:`Overview of Windows Active Directory
<overview-of-windows-active-directory>`.
|sec-doc|: :ref:`Overview of LDAP Servers <overview-of-ldap-servers>`.
- your kubernetes namespace

4
doc/source/usertasks/kubernetes/remote-cli-access.rst
View File

@ -11,8 +11,8 @@ methods.
.. xreflink .. note::
To use the remote Windows Active Directory server for authentication of
local :command:`kubectl` commands, see, |sec-doc|: :ref:`Overview of
Windows Active Directory <overview-of-windows-active-directory>`.
local :command:`kubectl` commands, see, |sec-doc|: :ref:`Overview of LDAP
Servers <overview-of-ldap-servers>`.
.. _remote-cli-access-ul-jt2-lcy-ljb: