public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-23 21:28:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1069 from MBishop17/klainte-improve-keycloak-doc

Browse Source 
Klainte improve keycloak doc
This commit is contained in:
Denise
2019-01-04 16:08:27 +08:00
committed by GitHub
parent 7d355dde70 f184c20f83
commit f27eca4ab2
1 changed files with 51 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/admin-settings/authentication/keycloak/_index.md
+51 -4
View File
@@ -6,10 +6,27 @@ _Available as of v2.1.0_
If your organization uses Keycloak Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
>**Prerequisites:**
>
>- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/3.2/server_installation/index.html) configured.
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Keycloak documentation](https://www.keycloak.org/docs/3.2/server_admin/topics/clients/client-saml.html) to create a SAML Client, under Installation tab, you can find your metadata.
## Prerequisites
- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/latest/server_installation/) configured.
- In Keycloak, create a [new SAML client](https://www.keycloak.org/docs/latest/server_admin/#saml-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#saml-clients) for help.
Setting | Value
------------|------------
`Sign Documents` | `ON` <sup>1</sup>
`Sign Assertions` | `ON` <sup>1</sup>
All other `ON/OFF` Settings | `OFF`
`Client ID` | `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata`
`Client Name` | <CLIENT_NAME> (e.g. `rancher`)
`Client Protocol` | `SAML`
`Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs`
><sup>1</sup>: Optionally, you can enable either one or both of these settings.
- Export a `metadata.xml` file from your Keycloak client. From the `Installation` tab, choose the `SAML Metadata IDPSSODescriptor` format option and download your file.
## Configuring Keycloak in Rancher
1. From the **Global** view, select **Security > Authentication** from the main menu.
@@ -46,4 +63,34 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati
>- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
>- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
>- When adding groups, you *must* select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
>
> - The group drop-down shows *only* the groups that you are a member of. You will not be able to add groups that you are not a member of.
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the confiuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
### You are not redirected to Keycloak
When you click on **Authenticate with Keycloak**, your are not redirected to your IdP.
* Verify your Keycloak client configuration.
* Make sure `Force Post Binding` set to `OFF`.
### Forbidden message displayed after IdP login
You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a `Forbidden` message afterwards.
* Check the Rancher debug log.
* If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client.
### Keycloak Error: "We're sorry, failed to process response"
* Check your Keycloak log.
* If the log displays `failed: org.keycloak.common.VerificationException: Client does not have a public key`, set `Encrypt Assertions` to `OFF` in your Keycloak client.
### Keycloak Error: "We're sorry, invalid requester"
* Check your Keycloak log.
* If the log displays `request validation failed: org.keycloak.common.VerificationException: SigAlg was null`, set `Client Signature Required` to `OFF` in your Keycloak client.