diff --git a/content/docs/reference/authentication/LDAP.md b/content/docs/reference/authentication/LDAP.md index d330c414..0c703548 100644 --- a/content/docs/reference/authentication/LDAP.md +++ b/content/docs/reference/authentication/LDAP.md @@ -1,37 +1,35 @@ # LDAP -LDAP (Lightweight Directory Access Protocol) can be configured in -the `authentication` section of the Mirantis Kubernetes Engine (MKE) 4 config. -LDAP is disabled by default, to enable it set `enabled` to `true`. - +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 details, refer to -[LDAP configuration](https://dexidp.io/docs/connectors/ldap/#configuration) -in the official Dex documentation. +the interactions with your LDAP server. +For more information, refer to the official DEX documentation +[LDAP configuration](https://dexidp.io/docs/connectors/ldap/#configuration). -The following table details the fields that you can configure in the -`authentication.ldap` section of the MKE 4 config: +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. | +| 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: @@ -59,16 +57,12 @@ authentication: --- ***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** 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. -6. Successful authentication will redirect you back to the client applications home page. diff --git a/content/docs/reference/authentication/OIDC.md b/content/docs/reference/authentication/OIDC.md index cf602072..c448247a 100644 --- a/content/docs/reference/authentication/OIDC.md +++ b/content/docs/reference/authentication/OIDC.md @@ -1,21 +1,18 @@ # OIDC -OpenID Connect (OIDC) can be configured in the `authentication` section of -the Mirantis Kubernetes Engine (MKE) 4 config. -OIDC is disabled by default, to enable it set `enabled` to `true`. - +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. Refer to [Configure Okta](#configure-okta) for -instructions on how to obtain the field values. +the OIDC provider. +For information on how to obtain the field values, refer to +**Create a new application in Okta** section of this document. -The following table details the fields that you can configure in the -`authentication.oidc` section of the MKE 4 config: +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. | +| 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: @@ -33,8 +30,6 @@ authentication: **To create a new application in Okta:** -Create a new application in Okta and use the following settings: - 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. @@ -44,26 +39,19 @@ Create a new application in Okta and use the following settings: 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. +7. Run the `mkectl apply` command with your MKE configuration file. **To test the Authentication flow:** --- ***Note*** -"To test authentication flow, ports `5556` (dex) and `5555` (example-app) must be externally available. +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** 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. +4. Enter your credentials and click **Sign In**. If authentication is successful, +you will be redirected to the client applications home page. diff --git a/content/docs/reference/authentication/SAML.md b/content/docs/reference/authentication/SAML.md index a8d5d96f..32799a43 100644 --- a/content/docs/reference/authentication/SAML.md +++ b/content/docs/reference/authentication/SAML.md @@ -1,35 +1,34 @@ # SAML -Security Assertion Markup Language (SAML) can be configured in -the `authentication` section of the Mirantis Kubernetes Engine (MKE) 4 config. -SAML is disabled by default, to enable it set `enabled` to `true`. - +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. Refer to [Configure Okta](#configure-okta) for -instructions on how to obtain the field values. For more details, see -[Authentication through SAML 2.0](https://dexidp.io/docs/connectors/saml/) -in the official Dex documentation. - -The following table details the fields that you can configure in the -`authentication.saml` section of the MKE 4 config: - -| 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. | +the SAML provider. +Refer to **Configure and create a new application in Okta** section of this document +for instructions on how to obtain the field values. +For more information, refer to the official DEX documentation +[Authentication through SAML 2.0](https://dexidp.io/docs/connectors/saml/). + +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. | +| `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: @@ -47,8 +46,6 @@ authentication: **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** for **Sign-in method**. 2. For **App name**, choose a name that you can easily remember. 3. Configure the host for your redirect URLs: @@ -67,30 +64,29 @@ Create a new application in Okta and use the following settings: 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. -8. Configure the `localCa` to point to the downloaded certificate file. -The cert in the example above is stored in `/etc/ssl/okta.cert`. + 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: -Once the configuration is set, run the `mkectl apply` command with your -configuration file and wait for the cluster to be ready. + 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. **To test the Authentication flow:** --- ***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** 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. +4. Enter your credentials and click **Sign In**. If authentication is successful, +you will be redirected to the client applications home page. diff --git a/content/docs/reference/authentication/authentication.md b/content/docs/reference/authentication/authentication.md index a4dd5914..57066c6d 100644 --- a/content/docs/reference/authentication/authentication.md +++ b/content/docs/reference/authentication/authentication.md @@ -7,8 +7,9 @@ the authentication in the MKE configuration file and add your preferred method. --- ***CAUTION*** -Changing the authentication method will require you to configure -authentication completely by yourself. +Be aware that if you opt to use an authentication method other than Dex, +you will need to undertake all tasks and responsibilities associated with +configuring and maintaining that method. --- @@ -17,18 +18,23 @@ For more information on authentication feature status per release, go to ## Prerequisites -- Identity Provider (IdP) - To set OIDC or SAML you need to configure an IdP with an application. -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. +- **Identity Provider (IdP)** + + To set OIDC or SAML you need to configure an IdP with an application. + 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). + +- **LDAP Server** + + To set LDAP you need to configure an LDAP server with a user. ## Configuration -Authentication can be configured in the `authentication` section of the MKE 4 config. -By default, authentication is enabled, but each of the individual authentication -methods is disabled. It can be disabled by setting the root `enabled` to `false`. -This will completely remove any authentication-related components from being -installed on the cluster. +You can configure authentication for MKE 4 through the `authentication` section +of the MKE configuration file. `authentication` is enabled by default, however +the settings for each of the individual authentication methods are disabled. +To enable a service, set its `enabled` configuration option to `true`. +Doing so will completely remove any authentication-related components from +being installed on your cluster. ```yaml authentication: