Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history 
Co-authored-by: Kory <[email protected]>
  • Loading branch information
@MagdaDziadosz @KoryKessel-Mirantis
MagdaDziadosz and KoryKessel-Mirantis authored Jun 11, 2024
1 parent 66cc24b commit d99665f
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 72 deletions.
40 changes: 20 additions & 20 deletions content/docs/reference/authentication/LDAP.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,26 +14,26 @@ The following table details the fields that you can configure in the

| Field | Description |
|------------------------------------|----------------------------------------------------------------------------|
| `host` | Host and optional port of the LDAP server in the `host:port` format. |
| `host` | Host and optional port of the LDAP server, in the `host:port` format. |
| `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. |
| `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` | Maps to display name of a user. |
| `userSearch.preferredUsernameAttr` | Maps to preferred usernames of users. |
| `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 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` | A group name. |
| `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. |

An example configuration for LDAP:
LDAP example configuration:

```yaml
authentication:
Expand All @@ -54,10 +54,10 @@ authentication:
nameAttr: cn
```
## Authentication flow
**To test the Authentication flow:**
---
***Testing tip***
***Note***
Ports `5556` (dex) and `5555` (example-app) need to be available externally
to test the authentication flow.
Expand All @@ -67,8 +67,8 @@ to test the authentication flow.
In the browser, perform the following steps to test the authentication flow:

1. Navigate to `http://{MKE hostname}:5555/login`.
2. Click **Login**.
3. On the login page, select **Log in with LDAP**.
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**.
5. Click **Login**. If authentication is successful, you will be redirected to the client applications home page.
6. Successful authentication will redirect you back to the client applications home page.
37 changes: 19 additions & 18 deletions content/docs/reference/authentication/OIDC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ The following table details the fields that you can configure in the

| Field | Description |
|----------------|----------------------------------------------------------------------------|
| `issuer` | The root URL of the OIDC provider. |
| `clientID` | The ID from the IdP's application configuration. |
| `clientSecret` | The secret from the IdP's application configuration. |
| `redirect URI` | The URI that the provider will be returning successful authentications to. |
| `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. |

An example configuration for OIDC:
OIDC example configuration:

```yaml
authentication:
Expand All @@ -31,38 +31,39 @@ authentication:
redirectURI: http://dex.example.com:32000/callback
```
## Configure Okta
**To create a new application in Okta:**
Create a new application in Okta and use the following settings:
1. Select **OIDC - OpenID Connect** as the sign-in method.
2. Select **Web Application** as the application type.
3. Choose an app integration name that you can easily remember.
4. The host for your redirect URLs:
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**.
5. Click **Save** to generates the `clientSecret` and `clientID` in the `General` table of
the application.
6. Add the generated `clientSecret` and `clientID` values to your MKE configuration file.

Okta will generate the `clientSecret` and `clientID` on the `General` table of
the application. Add the generated values to your MKE 4 config.

Once the configuration is set, run the `mkectl apply` command with your config
file and wait for the cluster to be ready.

## Authentication flow
**To test the Authentication flow:**

---
***Testing tip***
***Note***

Ports `5556` (dex) and `5555` (example-app) 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.
---
In the browser, perform the following steps to test the authentication flow:
1. Navigate to `http://{MKE hostname}:5555/login`
2. Click **Login**.
3. On the login page, select **Log in with OIDC**.
4. You will be redirected to the IdP's login page. Enter your credentials and click **Sign In**.
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.
5. Successful authentication will redirect you back to the client applications home page.
50 changes: 25 additions & 25 deletions content/docs/reference/authentication/SAML.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,20 @@ The following table details the fields that you can configure in the
| Field | Description |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `enabled` | Enable authentication through dex. |
| `ssoMetadataURL` | The metadata URL provided by some IdPs. MKE can use this to retrieve information for all other SAML configuration automatically. |
| `ca` | Alternative to `caData` and `localCa`. CA to use when validating the signature of the SAML response. This must be manually mounted in a local accessible by dex. |
| `caData` | Alternative to `ca` and `localCa`. Place the cert data directly in the config file. |
| `localCa` | Alternative to `ca` and `caData`. A path to a CA file in the local system. MKE will mount and create a secret for the cert. |
| `ssoURL` | The URL to send users to when signing in with SAML. Provided by the IdP. |
| `redirectURI` | Dex callback URL. Where users will be returned to after successful authentication with the IdP. |
| `insecureSkipSignatureValidation` | Optional. Skip the signature validation. To be used for testing purposes only. |
| `usernameAttr` | A username attribute in the returned assertions to map to ID token claims. |
| `emailAttr` | An email attribute in the returned assertions to map to ID token claims. |
| `groupsAttr` | Optional. A groups attribute in the returned assertions to map to ID token claims. |
| `entityIssuer` | Optional. Include this as the Issuer value during authentication request. |
| `ssoIssuer` | Optional. Issuer value expected in the SAML response. |
| `groupsDelim` | Optional. If groups are assumed to be represented as a single attribute, this delimiter is used to split the attribute's value into multiple groups. |
| `nameIDPolicyFormat` | Requested format of the name ID. |
| `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:

Expand All @@ -45,13 +45,13 @@ authentication:
emailAttr: email
```
## Configure Okta
**To configure and create a new application in Okta:
Create a new application in Okta and use the following settings:
1. Select **SAML 2.0** as the **Sign-in method**.
2. Choose an app integration name that you can easily remember.
3. The host for your redirect URLs:
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:
Expand All @@ -65,22 +65,22 @@ Create a new application in Okta and use the following settings:

a. Click **Assign** -> **Assign to people**.

b. Find the account you would like to use for authentication and click the blue **Assign** button on the right.
b. Click the blue **Assign** button that corresponds to the account you want to use for authentication.

Okta will generate the `ssoURL` and cert under the `Sign On` tab.
The `ssoURL` will be the MetadataURL with the final metadata removed from the path.
The cert can be downloaded from the SAML **Signing Certificates** section.
Click **Actions** on the active cert and download the cert.
Configure the `localCa` to point to this file on your system that you will run `mkectl` from.
8. Configure the `localCa` to point to the downloaded certificate file.
The cert in the example above is stored in `/etc/ssl/okta.cert`.

Once the configuration is set, run the `mkectl apply` command with your
configuration file and wait for the cluster to be ready.

## Authentication flow
**To test the Authentication flow:**

---
***Testing tip***
***Note***

Ports `5556` (dex) and `5555` (example-app) need to be available externally
to test the authentication flow.
Expand All @@ -90,7 +90,7 @@ to test the authentication flow.
In the browser, perform the following steps to test the authentication flow:

1. Navigate to `http://{MKE hostname}:5555/login`.
2. Click **Login**.
3. On the login page, select **Log in with SAML**.
4. You will be redirected to the IdP's login page. Enter your credentials and click **Sign In**.
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.
5. Successful authentication will redirect you back to the client applications home page.
18 changes: 9 additions & 9 deletions content/docs/reference/authentication/authentication.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
# Authentication

Mirantis Kubernetes Engine (MKE) 4 uses Dex for authentication.
If you choose to use a different authentication method, you can disable
the authentication in the MKE 4 configuration file and add your own method.
If you want to use a different authentication method, disable
the authentication in the MKE configuration file and add your preferred method.

---
***Caution: Changing authentication method***
***CAUTION***

Changing the authentication method will require you to configure
authentication completely by yourself.

---

For more information on authentication feature status in the release, go to
For more information on authentication feature status per release, go to
[MKE 4 releases](https://github.com/Mirantis/mke-docs/blob/main/content/releases/README.md).

## Prerequisites

- Identity Provider (IdP) - To set OIDC or SAML you need to configure an IdP with an application.
Refer to [Add a SAML Identity Provider](https://help.okta.com/en-us/content/topics/security/idp-add-saml.htm)
Refer to the official Okta documentation tutorial [Add a SAML Identity Provider](https://help.okta.com/en-us/content/topics/security/idp-add-saml.htm).
tutorial from the official Okta documentation.
- LDAP Server - To set LDAP you need to configure an LDAP server with a user.

Expand All @@ -37,8 +37,8 @@ authentication:
## Authentication methods
To learn more, refer to the documentation on specific authentication methods:
Documentation for specific authentication methods as they apply to MKE 4 is available:
- [OpenID Connect (OIDC)](OIDC.md)
- [Security Assertion Markup Language (SAML)](SAML.md)
- [Lightweight Directory Access Protocol (LDAP)](LDAP.md)
- [OIDC (OpenID Connect)](OIDC.md)
- [SAML (Security Assertion Markup Language)](SAML.md)
- [LDAP (Lightweight Directory Access Protocol)](LDAP.md)

0 comments on commit d99665f

Please sign in to comment.