[DOC] Authentication section update

content/docs/reference/authentication/LDAP.md

@@ -1,31 +1,39 @@
 # LDAP
 
-LDAP can be configured by setting up the `ldap` section in the `authentication` section of the MKE4 config. This also has its own `enabled` field which is disabled by default and much be switched to 'true' to enable LDAP.
-
-The remaining fields are used to configure the interactions with your LDAP server. Full details of these fields can be found in the (https://dexidp.io/docs/connectors/ldap/#configuration)[dex documentation] .
-
-| Field                            | Description                                                               |
-| -------------------------------- | ------------------------------------------------------------------------- |
-| host                             | Host and optional port of the LDAP server in the form "host:port"         |
-| rootCA                           | Path to a trusted root certificate file                                   |
-| bindDN                           | The DN for an application service account                                 |
-| bindPW                           | The password for an application service account                           |
-| usernamePrompt                   | The attribute to display in the provided password prompt                  |
-| userSearch                       | Settings to map a username and password entered by a user to a LDAP entry |
-| userSearch.baseDN                | BaseDN to start the search from                                           |
-| userSearch.filter                | Optional filter to apply when searching the directory                     |
-| userSearch.username              | username attribute used for comparing user entries                        |
-| userSearch.idAttr                | String representation of the user                                         |
-| userSearch.emailAttr             | Attribute to map to Email.                                                |
-| userSearch.nameAttr              | Maps to display name of user                                              |
-| userSearch.preferredUsernameAttr | Maps to preferred username of users                                       |
-| groupSearch                      | Group search queries for groups given a user entry                        |
-| groupSearch.baseDN               | BaseDN to start the search from                                           |
-| groupSearch.filter               | Optional filter to apply when searching the directory                     |
-| groupSearch.userMatchers         | A list of field pairs that are used to match a user to a group            |
-| groupSearch.nameAttr             | Represents group name                                                     |
-
-An example configuration for LDAP is shown below.
+You can configure LDAP (Lightweight Directory Access Protocol) for MKE 4 
+through the `authentication` section of the MKE configuration file.
+To enable the service, set `enabled` to `true`.
+The remaining fields in the `authentication.ldap` section are used to configure
+the interactions with your LDAP server.
+For more information, refer to the official DEX documentation
+[LDAP configuration](https://dexidp.io/docs/connectors/ldap/#configuration).
+
+## Configure MKE
+
+The MKE configuration file `authentication.ldap` fields are detailed below:
+
+| Field                              | Description                                                           |
+|------------------------------------|-----------------------------------------------------------------------|
+| `host`                             | Host and optional port of the LDAP server, in the `host:port` format. |
+| `rootCA`                           | Path to a trusted root certificate file.                              |
+| `bindDN`                           | Distinguished Name (DN) for an application service account.           |
+| `bindPW`                           | Password for an application service account.                          |
+| `usernamePrompt`                   | Attribute to display in the password prompt.                          |
+| `userSearch`                       | Settings to map user-entered username and password to an LDAP entry.  |
+| `userSearch.baseDN`                | BaseDN from which to start the search.                                |
+| `userSearch.filter`                | Optional filter to apply for a user search of the directory.          |
+| `userSearch.username`              | Username attribute to use for user entry comparison.                  |
+| `userSearch.idAttr`                | String representation of the user.                                    |
+| `userSearch.emailAttr`             | Attribute to map to email.                                            |
+| `userSearch.nameAttr`              | Attribute to map to display name of a user.                           |
+| `userSearch.preferredUsernameAttr` | Attribute to map to preferred usernames.                              |
+| `groupSearch`                      | Group search queries for groups given a user entry.                   |
+| `groupSearch.baseDN`               | BaseDN from which to start the search.                                |
+| `groupSearch.filter`               | Optional filter to apply for a group search of the directory.         |
+| `groupSearch.userMatchers`         | Field pairs list to use to match a user to a group.                   |
+| `groupSearch.nameAttr`             | Group name.                                                           |
+
+LDAP example configuration:
 
 ```yaml
 authentication:
@@ -46,15 +54,17 @@ authentication:
       nameAttr: cn
 ```
 
-## Authentication Flow
+## Test authentication flow
+
+---
+***Note***
 
-> Ports `5556` (dex) and `5555` (example-app) will need to be available externally to test the authentication flow.
+To test authentication flow, ports `5556` (dex) and `5555` (example-app) must be externally available.
 
-Do the following in the browser to test the authentication flow:
+---
 
-1. Navigate to `http://{MKE hostname}:5555/login`
-2. Click the `Login` button
-3. On the login page, select "Log in with LDAP"
-4. Enter the username and password for the LDAP server
-5. Click the `Login` button
-6. You should now be logged in and see application's home page
+1. Navigate to `http://{MKE hostname}:5555/login`.
+2. Click **Login** to display the login page.
+3. Select **Log in with LDAP**.
+4. Enter the username and password for the LDAP server.
+5. Click **Login**. If authentication is successful, you will be redirected to the client applications home page.

content/docs/reference/authentication/OIDC-providers/OIDC-OKTA-configuration.md

@@ -0,0 +1,13 @@
+# Create OIDC application in Okta
+
+1. Select **OIDC - OpenID Connect** for **Sign-in method**.
+2. Select **Web Application** for **Application Type**.
+3. For **App integration name**, choose a name that you can easily remember.
+4. Configure the host for your redirect URLs:
+   - Sign-in redirect URIs: `http://{MKE hostname}/login`
+   - Sign-out redirect URIs: `http://{MKE hostname}`
+5. Click **Save** to generate the `clientSecret` and `clientID` in the `General` table of
+the application.
+6. Add the generated `clientSecret` and `clientID` values to your MKE configuration file.
+7. Run the `mkectl apply` command with your MKE configuration file.
+

content/docs/reference/authentication/OIDC-providers/OIDC.md

@@ -0,0 +1,48 @@
+# OIDC
+
+You can configure OIDC (OpenID Connect) for MKE 4 through the `authentication`
+section of the MKE configuration file. To enable the service, set `enabled` to `true`.
+The remaining fields in the `authentication.oidc` section are used to configure
+the OIDC provider.
+For information on how to obtain the field values, refer to your chosen provider:
+
+- [Okta](OIDC-OKTA-configuration.md)
+
+## Configure MKE
+
+The MKE configuration file `authentication.oidc` fields are detailed below:
+
+| Field          | Description                                                       |
+|----------------|-------------------------------------------------------------------|
+| `issuer`       | OIDC provider root URL.                                           |
+| `clientID`     | ID from the IdP application configuration.                        |
+| `clientSecret` | Secret from the IdP application configuration.                    |
+| `redirect URI` | URI to which the provider will return successful authentications. |
+
+OIDC example configuration:
+
+```yaml
+authentication:
+  enabled: true
+  oidc:
+    enabled: true
+    issuer: https://dev-94406016.okta.com
+    clientID: 0oedtjcjrjWab3zlD5d4
+    clientSecret: DFA9NYLfE1QxwCSFkZunssh2HCx16kDl41k9tIBtFZaNcqyEGle8yZPtMBesyomD
+    redirectURI: http://dex.example.com:32000/callback
+```
+
+## Test authentication flow
+
+---
+***Note***
+
+To test authentication flow, ports `5556` (dex) and `5555` (example-app) must be externally available. 
+
+---
+
+1. Navigate to `http://{MKE hostname}:5555/login`
+2. Click **Login** to display the login page.
+3. Select **Log in with OIDC**.
+4. Enter your credentials and click **Sign In**. If authentication is successful,
+you will be redirected to the client applications home page.

content/docs/reference/authentication/SAML-providers/SAML-OKTA-configuration.md

@@ -0,0 +1,31 @@
+# Create SAML application in Okta
+
+1. Select **SAML 2.0** for **Sign-in method**.
+2. For **App name**, choose a name that you can easily remember.
+3. Configure the host for your redirect URLs:
+   - Single sign-on URL: `http://{MKE hostname}/callback`
+   - Audience URI (SP Entity ID): `http://{MKE hostname}/callback`
+   - Attribute statements:
+     - Name: email
+       <br>Value: user.email
+     - Name: name
+       <br>Value: user.login
+4. Click **Save**.
+5. Click **Finish**.
+6. Navigate to the **Assignments** tab:
+
+   a. Click **Assign** -> **Assign to people**.
+
+   b. Click the blue **Assign** button that corresponds to the account you want to use for authentication.
+
+    Okta generates the `ssoURL` and certificate under the `Sign On` tab.
+    The `ssoURL` is the MetadataURL with the final metadata removed from the path.
+
+7. Download the certificate to the system from which you will run mkectl:
+
+    a. Navigate to the SAML **Signing Certificates** section.
+
+    b. Click **Actions** for the active certificate and initiate the download.
+
+8. Configure the `localCa` to point to the downloaded certificate file.
+9. Run the `mkectl apply` command with your MKE configuration file.

content/docs/reference/authentication/SAML-providers/SAML.md

@@ -0,0 +1,64 @@
+# SAML
+
+You can configure SAML (Security Assertion Markup Language) for MKE 4 through
+the `authentication` section of the MKE configuration file.
+To enable the service, set `enabled` to `true`.
+The remaining fields in the `authentication.saml` section are used to configure
+the SAML provider. 
+For information on how to obtain the field values, refer to your chosen provider:
+
+- [Okta](SAML-OKTA-configuration.md)
+
+For more information, refer to the official DEX documentation
+[Authentication through SAML 2.0](https://dexidp.io/docs/connectors/saml/).
+
+## Configure MKE
+
+The MKE configuration file `authentication.smal` fields are detailed below:
+
+| Field                             | Description                                                                                                                                                                         |
+|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`                         | Enable authentication through dex.                                                                                                                                                  |
+| `ssoMetadataURL`                  | Metadata URL provided by some IdPs, with which MKE can retrieve information for all other SAML configurations.                                                                      |
+| `ca`                              | Certificate Authority (CA) alternative to `caData` and `localCa`, to use when validating the signature of the SAML response. Must be manually mounted in a local accessible by dex. |
+| `caData`                          | CA alternative to `ca` and `localCa`, which you can use to place the certificate data directly into the config file.                                                                |
+| `localCa`                         | Alternative to `ca` and `caData`. A path to a CA file in the local system, with which MKE mounts and creates a secret for the certificate.                                          |
+| `ssoURL`                          | URL to provide to users to sign into MKE 4 with SAML. Provided by the IdP.                                                                                                          |
+| `redirectURI`                     | Callback URL for dex to which users are returned to following successful IdP authentication.                                                                                        |
+| `insecureSkipSignatureValidation` | Optional. Use to skip the signature validation. For testing purposes only.                                                                                                          |
+| `usernameAttr`                    | Username attribute in the returned assertions, to map to ID token claims.                                                                                                           |
+| `emailAttr`                       | Email attribute in the returned assertions, to map to ID token claims.                                                                                                              |
+| `groupsAttr`                      | Optional. Groups attribute in the returned assertions, to map to ID token claims.                                                                                                   |
+| `entityIssuer`                    | Optional. Include as the Issuer value during authentication requests.                                                                                                               |
+| `ssoIssuer`                       | Optional. Issuer value that is expected in the SAML response.                                                                                                                       |
+| `groupsDelim`                     | Optional. If groups are assumed to be represented as a single attribute, this delimiter splits the attribute value into multiple groups.                                            |
+| `nameIDPolicyFormat`              | Requested name ID format.                                                                                                                                                           |
+
+An example configuration for SAML:
+
+```yaml
+authentication:
+  enabled: true
+  saml:
+    enabled: true
+    ssoURL: https://dev64105006.okta.com/app/dev64105006_mke4saml_1/epkdtszgindywD6mF5s7/sso/saml
+    redirectURI: http://{MKE host}:5556/callback
+    localCa: /etc/ssl/okta.cert
+    usernameAttr: name
+    emailAttr: email
+```
+
+## Test authentication flow
+
+---
+***Note***
+
+To test authentication flow, ports `5556` (dex) and `5555` (example-app) must be externally available.
+
+---
+
+1. Navigate to `http://{MKE hostname}:5555/login`.
+2. Click **Login** to display the login page.
+3. Select **Log in with SAML**.
+4. Enter your credentials and click **Sign In**. If authentication is successful,
+you will be redirected to the client applications home page.