diff --git a/content/docs/reference/authentication/LDAP.md b/content/docs/reference/authentication/LDAP.md index c459c277..51e0d540 100644 --- a/content/docs/reference/authentication/LDAP.md +++ b/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. diff --git a/content/docs/reference/authentication/OIDC-providers/OIDC-OKTA-configuration.md b/content/docs/reference/authentication/OIDC-providers/OIDC-OKTA-configuration.md new file mode 100644 index 00000000..95802dc2 --- /dev/null +++ b/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. + diff --git a/content/docs/reference/authentication/OIDC-providers/OIDC.md b/content/docs/reference/authentication/OIDC-providers/OIDC.md new file mode 100644 index 00000000..dabfe6ac --- /dev/null +++ b/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. \ No newline at end of file diff --git a/content/docs/reference/authentication/OIDC.md b/content/docs/reference/authentication/OIDC.md deleted file mode 100644 index 04d7d9a9..00000000 --- a/content/docs/reference/authentication/OIDC.md +++ /dev/null @@ -1,53 +0,0 @@ -# OIDC - -OIDC can be configured by setting up the `oidc` section in the `authentication` section of the MKE4 config. This also has its own `enabled` field which is disabled by default and must be switched to 'true' to enable OIDC. - -The remaining fields are used to configure the OIDC provider. - -| Field | Description | -| ------------ | ------------------------------------------------------------------------- | -| issuer | The root URL of the OIDC provider | -| clientID | The id from the IdP's application configuration | -| clientID | The secret from the IdP's application configuration | -| redirect URI | The URI that the provider will be returning successful authentications to | - -An example configuration for OIDC is shown below: - -```yaml -authentication: - enabled: true - oidc: - enabled: true - issuer: https://dev-94406016.okta.com - clientID: 0oedtjcjrjWab3zlD5d4 - clientSecret: DFA9NYLfE1QxwCSFkZunssh2HCx16kDl41k9tIBtFZaNcqyEGle8yZPtMBesyomD - redirectURI: http://dex.example.com:32000/callback -``` - -Use the next section to understand how to configure Okta. Once the configuration is set, run the standard `mkectl apply` command with your config file and wait for the cluster to be ready. - -## Configuring Okta - -Create a new application in Okta and use the following settings: - -1. Sign-in method: OIDC - OpenID Connect -2. Application Type: Web Application -3. App integration name: Any name you can remember -4. The host for your redirect URLs - - Sign-in redirect URIs: `http://{MKE hostname}/login` - - Sign-out redirect URIs: `http://{MKE hostname}` -5. Save - -Okta will generate the secret and clientID on the `General` table of the application. Use these in your MKE4 config. - -## Authentication Flow - -> Ports `5556` (dex) and `5555` (example-app) will need to be available externally to test the authentication flow. - -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 OIDC" -4. You will be redirected to the IdP's login page. Enter your credentials and click `Sign In` -5. Successful authentication will redirect you back to client applications home page diff --git a/content/docs/reference/authentication/README.md b/content/docs/reference/authentication/README.md deleted file mode 100644 index 0edd302e..00000000 --- a/content/docs/reference/authentication/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Authentication - -Mirantis Kubernetes Engine 4 (MKE4) uses [dex](https://github.com/dexidp/dex) for its authentication. If you would like to use a different authentication method, you can simply disable authentication in the MKE4 config and add your own authentication method. Be aware, this will require you to configure authentication completely yourself. - -## Pre-requisites - -- IdP - If you are setting up OIDC or SAML then you will need an IdP with an application configured. This example setup uses [okta](https://www.okta.com/) -- LDAP Server - If you are setting up LDAP then you will need an LDAP server with a user configured. - -## Configuration - -Authentication can be configured in the `authentication` section of the MKE4 config. By default, authentication is enabled but each of the individual authentication methods are 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. - -```yaml -authentication: - enabled: true -``` - -## Authentication Methods - -From here, check out the individual files for the different authentication methods: - -- [OIDC](./OIDC.md) -- [SAML](./SAML.md) -- [LDAP](./LDAP.md) diff --git a/content/docs/reference/authentication/SAML-providers/SAML-OKTA-configuration.md b/content/docs/reference/authentication/SAML-providers/SAML-OKTA-configuration.md new file mode 100644 index 00000000..d13b9e36 --- /dev/null +++ b/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 +
Value: user.email + - Name: name +
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. diff --git a/content/docs/reference/authentication/SAML-providers/SAML.md b/content/docs/reference/authentication/SAML-providers/SAML.md new file mode 100644 index 00000000..706f784b --- /dev/null +++ b/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. diff --git a/content/docs/reference/authentication/SAML.md b/content/docs/reference/authentication/SAML.md deleted file mode 100644 index c9aa0d04..00000000 --- a/content/docs/reference/authentication/SAML.md +++ /dev/null @@ -1,76 +0,0 @@ -# SAML - -SAML can be configured by setting up the `saml` section in the `authentication` section of the MKE4 config. This also has its own `enabled` field which is disabled by default and must be switched to 'true' to enable SAML. - -The remaining fields are used to configure the SAML provider. Many of these fields can be found as part of the [Dex SAML documentation](https://dexidp.io/docs/connectors/saml/). - -| 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 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's callback URL. Where users will be returned to after successful authentication with the IdP | -| insecureSkipSignatureValidation | Skip the signature validation. This should only be used for testing purposes (optional) | -| 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 | A groups attribute in the returned assertions to map to ID token claims (optional) | -| entityIssuer | Include this as the Issuer value during AuthnRequest (optional) | -| ssoIssuer | Issuer value expected in the SAML response (optional) | -| groupsDelim | If groups are assumed to be represented as a single attribute, this delimiter is used to split the attribute's value into multiple groups (optional) | -| nameIDPolicyFormat | Requested format of the NameID | - -An example configuration for SAML is shown below: - -```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 -``` - -Use the next section to understand how to configure Okta and find the values for the example config above. Once the configuration is set, run the standard `mkectl apply` command with your config file and wait for the cluster to be ready. - -## Configuring Okta - -Create a new application in Okta and use the following settings: - -1. Sign-in method: SAML 2.0 -2. App name: Any name you can remember -3. 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 -
Value: user.email - - Name: name -
Value: user.login -4. Save -5. Finish -6. Navigate to the `Assignments` tab -
a. Click on `Assign` -> `Assign to people` -
b. Find the account you would like to use for authentication and click the blue `Assign` button on the right - -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. The cert in the example above is stored in `/etc/ssl/okta.cert`. - -## Authentication Flow - -> Ports `5556` (dex) and `5555` (example-app) will need to be available externally to test the authentication flow. - -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 SAML" -4. You will be redirected to the IdP's login page. Enter your credentials and click `Sign In` -5. Successful authentication will redirect you back to the client applications home page diff --git a/content/docs/reference/authentication/authentication.md b/content/docs/reference/authentication/authentication.md new file mode 100644 index 00000000..5025f3aa --- /dev/null +++ b/content/docs/reference/authentication/authentication.md @@ -0,0 +1,50 @@ +# Authentication + +Mirantis Kubernetes Engine (MKE) 4 uses Dex for authentication. +If you want to use a different authentication component, disable +the authentication in the MKE configuration file and add your preferred method. + +--- +***CAUTION*** + +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. + +--- + +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 [OIDC](OIDC-providers/OIDC.md), or [SAML](SAML-providers/SAML.md) + for detailed procedures. + +- **LDAP Server** + + To set LDAP you need to [configure an LDAP server](LDAP.md) with the users. + +## Configuration + +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 install the authentication method of your choice on your cluster. + +```yaml +authentication: + enabled: true +``` + +## Authentication methods + +Documentation for specific authentication methods as they apply to MKE 4 is available: + +- [OIDC (OpenID Connect)](OIDC-providers/OIDC.md) +- [SAML (Security Assertion Markup Language)](SAML-providers/SAML.md) +- [LDAP (Lightweight Directory Access Protocol)](LDAP.md)