Update docs (#104)

* Update docs
* Use enum for LDAP auth choice

auth/providers/ldap/authchoice.go

@@ -0,0 +1,22 @@
+//go:generate go-enum -f=authchoice.go
+package ldap
+
+// AuthChoice x ENUM(
+// Simple,
+// Kerberos
+// )
+type AuthChoice int32
+
+// https://github.com/spf13/pflag/blob/1ce0cc6db4029d97571db82f85092fccedb572ce/flag.go#L187:6
+func (e *AuthChoice) Set(name string) error {
+	v, err := ParseAuthChoice(name)
+	if err != nil {
+		return err
+	}
+	*e = v
+	return nil
+}
+
+func (AuthChoice) Type() string {
+	return "AuthChoice"
+}

auth/providers/ldap/kubectl.go

@@ -63,6 +63,7 @@ func (t *TokenOptions) IssueToken() error {
 		token = t.getSimpleAuthToken()
 		break
 	case 1:
+		// ref: https://www.youtube.com/watch?v=KD2Q-2ToloE
 		token, err = t.getKerberosToken()
 		if err != nil {
 			return err

auth/providers/ldap/ldap.go

@@ -22,9 +22,6 @@ const (
 	DefaultUserAttribute        = "uid"
 	DefaultGroupMemberAttribute = "member"
 	DefaultGroupNameAttribute   = "cn"
-
-	AuthChoiceSimpleAuthentication = 0
-	AuthChoiceKerberos             = 1
 )
 
 func init() {
@@ -89,7 +86,7 @@ func (s Authenticator) Check(token string) (*authv1.UserInfo, error) {
 		return nil, errors.Wrap(err, "authentication failed")
 	}
 
-	if s.opts.AuthenticationChoice == AuthChoiceSimpleAuthentication {
+	if s.opts.AuthenticationChoice == AuthChoiceSimple {
 		// rebind, as in simple authentication we bind using username, password
 		if s.opts.BindDN != "" && s.opts.BindPassword != "" {
 			err = conn.Bind(s.opts.BindDN, s.opts.BindPassword)
@@ -132,7 +129,7 @@ func (s Authenticator) Check(token string) (*authv1.UserInfo, error) {
 }
 
 func (s Authenticator) authenticateUser(conn *ldap.Conn, token string) (string, error) {
-	if s.opts.AuthenticationChoice == AuthChoiceSimpleAuthentication {
+	if s.opts.AuthenticationChoice == AuthChoiceSimple {
 		//simple authentication
 		username, password, ok := parseEncodedToken(token)
 		if !ok {

auth/providers/ldap/options.go

@@ -72,7 +72,7 @@ type Options struct {
 	// LDAP user authentication mechanism
 	// 0 for simple authentication
 	// 1 for kerberos(via GSSAPI)
-	AuthenticationChoice int
+	AuthenticationChoice AuthChoice
 
 	// path to the keytab file
 	// it's contain LDAP service principal keys
@@ -145,7 +145,7 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) {
 	fs.BoolVar(&o.IsSecureLDAP, "ldap.is-secure-ldap", false, "Secure LDAP (LDAPS)")
 	fs.BoolVar(&o.StartTLS, "ldap.start-tls", false, "Start tls connection")
 	fs.StringVar(&o.CaCertFile, "ldap.ca-cert-file", "", "ca cert file that used for self signed server certificate")
-	fs.IntVar(&o.AuthenticationChoice, "ldap.auth-choice", 0, "LDAP user authentication mechanism, 0 for simple authentication, 1 for kerberos(via GSSAPI)")
+	fs.Var(&o.AuthenticationChoice, "ldap.auth-choice", "LDAP user authentication mechanisms Simple/Kerberos(via GSSAPI)")
 	fs.StringVar(&o.KeytabFile, "ldap.keytab-file", "", "path to the keytab file, it's contain LDAP service principal keys")
 	fs.StringVar(&o.ServiceAccountName, "ldap.service-account", "", "service account name")
 }

auth/types.go

@@ -2,6 +2,7 @@ package auth
 
 import (
 	"path/filepath"
+	"sort"
 	"strings"
 
 	authv1 "k8s.io/api/authentication/v1"
@@ -29,6 +30,7 @@ func (o orgs) String() string {
 	for i, org := range o {
 		names[i] = strings.Title(org)
 	}
+	sort.Strings(names)
 	return strings.Join(names, "/")
 }
 

docs/guides/authenticator/azure.md

@@ -14,22 +14,29 @@ section_menu_id: guides
 
 # Azure Authenticator
 
-TO use Azure,
+Guard installation guide can be found [here](/docs/setup/install.md). To use Azure, create a client cert with `Organization` set to `Azure`.For Azure `CommonName` is optional. To ease this process, use the Guard cli to issue a client cert/key pair.
 
-1.  Create a client cert with `Organization` set to `Azure`.For Azure `CommonName` is optional. To ease this process, use the Guard cli to issue a client cert/key pair.
-
-    ```console
-    $ guard init client {common-name} -o Azure
-    ```
+```console
+$ guard init client [CommonName] -o Azure
+```
 
-2.  Send additional `--azure.client-id`,`--azure.client-secret` and `--azure.tenant-id` flags to guard server. You can use following command to create YAMLs for this setup.
-     ```console
-     # generate Kubernetes YAMLs for deploying guard server
-     $ guard get installer --azure.client-id=[APPLICATION_ID] --azure.client-secret=[APPLICATION_SECRET] --azure.tenant-id=[TENANT_ID] > installer.yaml
-     $ kubectl apply -f installer.yaml
+### Deploy guard server
 
-     ```
-     Procedure to find `APPLICATION_ID`, `APPLICATION_SECRET` are given below. Replace the `TENANT_ID` with your azure tenant id.
+To generate installer YAMLs for guard server you can use the following command.
+
+```console
+# generate Kubernetes YAMLs for deploying guard server
+$ guard get installer \
+    --auth-providers = "azure" \
+    --azure.client-id=<application_id> \
+    --azure.tenant-id=<tenant_id> \
+    > installer.yaml
+
+$ kubectl apply -f installer.yaml
+```
+> **Note:** guard take `<application_secret>` from environment variable **AZURE_CLIENT_SECRET**
+
+Procedure to find `<application_id>`, `<application_secret>` are given below. Replace the `<tenant_id>` with your azure tenant id.
 
 ### Configure Azure Active Directory App
 
@@ -38,67 +45,67 @@ TO use Azure,
 2.  Create an Azure Active Directory Web App / API application
 
     ![create-app-registration](/docs/images/azure/create-app-registration.png)
-    
-3.  Use the **Application ID** as `APPLICATION_ID`
+
+3.  Use the **Application ID** as `<application_id>`
 
     ![application-id](/docs/images/azure/application-id.png)
 
-4.  Click on the **Settings**, click on the **key** , generate a key and use this key as `APPLICATION_SECRET`
+4.  Click on the **Settings**, click on the **key** , generate a key and use this key as `<application_secret>`
 
     ![secret-key](/docs/images/azure/secret-key.png)
-    
+
 5.  Click on the **Manifest** , set `groupMembershipClaims` to `All` and **save** the mainfest
 
     ![update-manifest](/docs/images/azure/update-manifest.png)
-    
+
 6.  Add **Microsoft graph** api with permission `Read directory data` and `Sign in and read user profile`.
-    
+
     ![add-api](/docs/images/azure/add-api.png)
-    
+
 7.  Create a second Azure Active Directory native application
 
     ![create-native-app](/docs/images/azure/create-native-app.png)
-    
-8.  Use the **Application ID** of this native app as `CLIENT_ID`
+
+8.  Use the **Application ID** of this native app as `<client_id>`
 
     ![client-id](/docs/images/azure/client-id.png)
 
-9.  Add application created at step 2 with permission `Access [Application_Name_Created_At_Step_2]`
-    
+9.  Add application created at step 2 with permission `Access <Application_Name_Created_At_Step_2>`
+
     ![add-guard-app](/docs/images/azure/add-guard-api.png)
 
 ## Configure kubectl
 
 ```console
-kubectl config set-credentials "USER_NAME" --auth-provider=azure \
+kubectl config set-credentials <user_name> --auth-provider=azure \
   --auth-provider-arg=environment=AzurePublicCloud \
-  --auth-provider-arg=client-id=CLIENT_ID \
-  --auth-provider-arg=tenant-id=TENANT_ID \
-  --auth-provider-arg=apiserver-id=APPLICATION_ID
+  --auth-provider-arg=client-id=<client_id> \
+  --auth-provider-arg=tenant-id=<tenant_id> \
+  --auth-provider-arg=apiserver-id=<application_id>
 ```
 
-Procedure to find `APPLICATION_ID`, `APPLICATION_SECRET` and `CLIENT_ID` are given above. Replace the USER_NAME and TENANT_ID with your azure username and tenant id.
+Procedure to find `<application_id>`, `<application_secret>` and `<client_id>` are given above. Replace the <user_name> and <tenant_id> with your azure username and tenant id.
 
 Or You can add user in `.kube/config` file
 
 ```yaml
 ...
 users:
-- name: USER_NAME
+- name: <user_name>
   user:
     auth-provider:
       config:
-        apiserver-id: APPLICATION_ID
-        client-id: CLIENT_ID
-        tenant-id: TENANT_ID
+        apiserver-id: <application_id>
+        client-id: <client_id>
+        tenant-id: <tenant_id>
         environment: AzurePublicCloud
       name: azure
 ```
 
 The access token is acquired when first `kubectl` command is executed
 
    ```
-   kubectl get pods
+   $ kubectl get pods --user <user_name>
 
    To sign in, use a web browser to open the page https://aka.ms/devicelogin and enter the code DEC7D48GA to authenticate.
    ```

docs/guides/authenticator/github.md

@@ -14,10 +14,37 @@ section_menu_id: guides
 
 # Github Authenticator
 
-TO use Github, you need a client cert with `CommonName` set to Github organization name and `Organization` set to `Github`. To ease this process, use the Guard cli to issue a client cert/key pair.
+Guard installation guide can be found [here](/docs/setup/install.md). To use Github, you need a client cert with `CommonName` set to Github organization name and `Organization` set to `Github`. To ease this process, use the Guard cli to issue a client cert/key pair.
 
 ```console
-$ guard init client {org-name} -o Github
+$ guard init client {common-name} -o Github
+```
+
+### Deploy Guard Server
+
+To generate installer YAMLs for guard server you can use the following command.
+
+```console
+$ guard get installer \
+    --auth-providers="github" \
+    > installer.yaml
+
+$ kubectl apply -f installer.yaml
+
+```
+
+Additional flags for github:
+
+```console
+# Base url for enterprise, keep empty to use default github base url
+--github.base-url=<base_url>
+```
+
+### Issue Token
+To use Github authentication, you can use your personal access token with permissions to read `public_repo` and `read:org`. You can use the following command to issue a token:
+
+```console
+$ guard get token -o github
 ```
 
 ![github-webhook-flow](/docs/images/github-webhook-flow.png)
@@ -40,10 +67,30 @@ $ guard init client {org-name} -o Github
 }
 ```
 
-To use Github authentication, you can use your personal access token with permissions to read `public_repo` and `read:org`. You can use the following command to issue a token:
+Guard uses the token found in `TokenReview` request object to read user's profile information and list of teams this user is member of. In the `TokenReview` response, `status.user.username` is set to user's Github login, `status.user.groups` is set to teams of the organization in client cert of which this user is a member of.
 
+### Configure Kubectl
 ```console
-$ guard get token -o github
+kubectl config set-credentials <user_name> --token=<token>
 ```
 
-Guard uses the token found in `TokenReview` request object to read user's profile information and list of teams this user is member of. In the `TokenReview` response, `status.user.username` is set to user's Github login, `status.user.groups` is set to teams of the organization in client cert of which this user is a member of.
+Or You can add user in .kube/confg file
+
+```console
+...
+users:
+- name: <user_name>
+  user:
+    token: <token>
+```
+
+```console
+$ kubectl get pods --all-namespaces --user <user_name>
+NAMESPACE     NAME                               READY     STATUS    RESTARTS   AGE
+kube-system   etcd-minikube                      1/1       Running   0          7h
+kube-system   kube-addon-manager-minikube        1/1       Running   0          7h
+kube-system   kube-apiserver-minikube            1/1       Running   1          7h
+kube-system   kube-controller-manager-minikube   1/1       Running   0          7h
+kube-system   kube-dns-6f4fd4bdf-f7csh           3/3       Running   0          7h
+
+```