Skip to content

Commit 0ace0e7

Browse files
DarthBenro008DarthBenro008
authored
add: dex installation documentation for litmusportal (#134)
* feat: add dex installation documentation * add: dex-integration concepts Signed-off-by: DarthBenro008 <hkpdev008@gmail.com>
1 parent e006c37 commit 0ace0e7

File tree

4 files changed

+187
-1
lines changed

4 files changed

+187
-1
lines changed

‎website/docs/assets/concepts/authentication/architecture.png‎

57.3 KB
Loading

‎website/docs/concepts/oauth-dex-concept.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
id: oauth-dex-concept
3+
title: Authentication process in ChaosCenter
4+
sidebar_label: Authentication in ChoasCenter
5+
---
6+
7+
---
8+
9+
## Prerequisites
10+
11+
- [OAuth](https://oauth.net/specs/)
12+
13+
ChaosCenter allows OAuth as well as local authentication using Dex and the authentication server.
14+
15+
16+
## Authentication Architecture
17+
18+
<img src={require('../assets/concepts/authentication/architecture.png').default} width="800" /><br/><br/>
19+
20+
21+
Litmus portal uses two components for authentication of users:
22+
23+
- Authentication Server
24+
- Dex OIDC Server (Optional)
25+
26+
By default litmus-portal comes with then authentication server as part of the `litmusportal-server` deployment and it allows local authentication that is based of mongo database. Client services such as `litmus-ctl` and `litmusportal-frontend` make use of this server.
27+
28+
In order to provide enhanced and seamless login features, we wanted to integrate OAuth and other authentication mechanisms such as OpenID connect. To have flexibility, litmus-portal makes use of an additional component, [Dex OIDC server](https://dexidp.io/).
29+
30+
Dex is a highly extensible cloud-native OIDC provider that is able to take care of various authentication mechanisms. With Dex being deployed, the authentication-server can communicate with the dex-server, enabling integration of various OAuth providers. GitHub and Google auth has been tested at present.
31+
32+
33+
## Resources
34+
35+
- [Deploying OAuth in ChaosCenter](../user-guides/chaoscenter-oauth-dex-installation.md)
36+
37+
38+
39+
40+
41+
42+
43+
44+

‎website/docs/user-guides/chaoscenter-oauth-dex-installation.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
id: chaoscenter-oauth-dex-installation
3+
title: ChaosCenter with OAuth2 Login Support
4+
sidebar_label: OAuth2 Support using Dex
5+
---
6+
7+
---
8+
9+
# Prerequisites
10+
11+
Before deploying LitmusChaos, make sure the following items are there
12+
13+
- Kubernetes 1.17 or later
14+
15+
- A Persistent volume of 20GB
16+
17+
:::note
18+
Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus install would use the default storage class to allocate the PV. Provide this value
19+
:::
20+
21+
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
22+
23+
- [Deployed ChaosCenter](../getting-started/installation.md)
24+
25+
- Atleast one of the following
26+
- Google Oauth credentials
27+
- GitHub Oauth credentials
28+
29+
## Deploy Dex OIDC provider
30+
31+
In order to enable OAuth2 and to be able to login via Google and GitHub, litmus uses [Dex OIDC](https://dexidp.io/)
32+
33+
Make sure you have your Google and GitHub Client credentials ready, if you do not have them, you can generate one yourself
34+
35+
- [Guide to generating Google Oauth Client Credentials](https://support.google.com/cloud/answer/6158849?hl=en#zippy=)
36+
- [Guide to generating GitHub OAuth Client Credentials](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)
37+
38+
39+
### Configuring Dex OIDC provider
40+
41+
42+
```bash
43+
curl https://raw.githubusercontent.com/litmuschaos/litmus/8d025a2f3101990a1acc002612fbe7281dcbfb4d/litmus-portal/dex-server/dex-deployment.yaml --output dex-deployment.yaml
44+
```
45+
46+
1. Open the file with your favorite text-editor
47+
2. You will find the following `config-map` with some data, replace your data as the comments suggests
48+
```yaml
49+
issuer: http://<NODE_IP>:32000 # Replace your NODE_IP here
50+
storage:
51+
type: kubernetes
52+
config:
53+
inCluster: true
54+
web:
55+
http: 0.0.0.0:5556
56+
staticClients:
57+
- id: LitmusPortalAuthBackend
58+
redirectURIs:
59+
- '/auth/dex/callback'
60+
- 'http://localhost:8080/auth/dex/callback' # Included for local testing purposes
61+
name: 'LitmusPortalAuthBackend'
62+
secret: ZXhhbXBsZS1hcHAtc2VjcmV0
63+
oauth2:
64+
skipApprovalScreen: true
65+
connectors:
66+
- type: google
67+
id: google
68+
name: Google
69+
config:
70+
clientID: # Add your Google Client ID here
71+
clientSecret: # Add your Google Client Secret here
72+
redirectURI: http://<NODE_IP>:32000 # Replace your NODE_IP here
73+
- type: github
74+
id: github
75+
name: GitHub
76+
config:
77+
clientID: # Add your GitHub Client ID here
78+
clientSecret: # Add your GitHub Client Secret here
79+
redirectURI: http://<NODE_IP>:32000/callback # Replace your NODE_IP here
80+
```
81+
82+
**Note: The Dex OIDC provider runs at `NODE_IP:32000` by default**
83+
84+
After the configuration, deploy the Dex deployment using the following command:
85+
86+
```bash
87+
kubectl apply -f dex-deployment.yaml
88+
```
89+
90+
You should now see the dex-server deployed in the litmus namespace!
91+
92+
```bash
93+
kubectl get pods -n litmus
94+
```
95+
96+
<span style={{color: 'green'}}><b>Expected Output</b></span>
97+
98+
```bash
99+
NAME READY STATUS RESTARTS AGE
100+
litmusportal-dex-server-7f7658b57-lbbxc 1/1 Running 0 107s
101+
litmusportal-frontend-74d456746f-56v9x 1/1 Running 0 5m57s
102+
litmusportal-server-9c4d85f57-5r6km 2/2 Running 0 5m57s
103+
mongo-0 1/1 Running 0 5m57s
104+
```
105+
106+
107+
### Configuring `litmusportal-server` to enable Dex features
108+
109+
To set up Dex, we would require to modify our litmusportal-server a bit in order to communicate with Dex. This will be achieved by adding some environment variables
110+
111+
- `OIDC_ISSUER`: The place where the Dex OIDC lives, i.e `NODE_IP:32000`
112+
- `DEX_ENABLED`: This variable enables dex features in the litmusportal-server
113+
- `CALLBACK_URL`: This is the url that will be called back after user completes thier OAuth, this will be the litmusportal-frontend service
114+
115+
Set your variables using
116+
117+
```bash
118+
kubectl set env deployment/litmusportal-server -n litmus --containers="auth-server" DEX_SERVER="true", OIDC_ISSUER=<REPLACE_NODE_IP>:32000, CALLBACK_URL=<REPLACE_litmusportal_frontend_Service>
119+
```
120+
Your litmusportal-server pod will be restarted and Dex features will be enabled!
121+
122+
### Verifying if OAuth2 is enabled
123+
124+
Go to http://litmusportal-frontend-service/auth/dex/login, you should be prompted with Google or GitHub login
125+
126+
![litmus-oauth-image](https://user-images.githubusercontent.com/31009634/135559389-c8cdf53c-76cf-4f9d-acaa-99014540f9cf.png)
127+
128+
129+
130+
## Resources
131+
132+
- [Dex OIDC Provider configurations](https://dexidp.io/docs/)
133+
134+
## Learn more
135+
136+
- [Install ChaosCenter in Namespace Scope](../user-guides/chaoscenter-namespace-scope-installation.md)
137+
- [Connect External ChaosAgents to ChaosCenter](../user-guides/chaosagents-installation.md)
138+
- [Setup Endpoints and Access ChaosCenter without Ingress](../user-guides/setup-without-ingress.md)
139+
- [Setup Endpoints and Access ChaosCenter with Ingress](../user-guides/setup-with-ingress.md)
140+

‎website/sidebars.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ module.exports = {
6565
'concepts/user-management',
6666
'concepts/projects',
6767
'concepts/teaming',
68-
'concepts/gitops'
68+
'concepts/gitops',
69+
'concepts/oauth-dex-concept'
6970
]
7071
},
7172

@@ -77,6 +78,7 @@ module.exports = {
7778
'Advanced Installation': [
7879
{
7980
ChaosCenter: [
81+
'user-guides/chaoscenter-oauth-dex-installation',
8082
'user-guides/chaoscenter-cluster-scope-installation',
8183
'user-guides/chaoscenter-namespace-scope-installation',
8284
'user-guides/setup-without-ingress',

0 commit comments

Comments
 (0)