## Guide: Using Zitadel SAML as Rancher IdP via Keycloak SAML Auth Provider

As an admin I want to allow users to SSO to Rancher via [Zitadel](https://github.com/zitadel/zitadel) as the central identity auth provider.

Since Rancher has no Zitadel or generic OIDC or SAML auth provider, our trick is to use Keycloak SAML, but connect it to Zitadel.

---

### Create SAML App in Zitadel

1. Download Rancher's SAML Metadata XML from `https://RANCHERHOST/v1-saml/keycloak/saml/metadata`
2. Load it into the Zitadel SAML App as XML file. (may need to add .xml to file)


---

### Configuring Keycloak SAML Auth Provider in Rancher

1. Create Keycloak SAML auth provider in Rancher and enter Zitadel's field names as in the screenshot below.

2. Download Zitadel SAML Metadata from `https://ZITADELHOST/saml/v2/metadata`
3. Load that into Rancher Metadata XML field

4. Download the Certificate from Zitadel from `http://ZITADELHOST/saml/v2/certificate`
5. Load that into the Rancher Certificate field

6. For the Private Key, follow the [Rancher Docs](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml), you can simply generate a key by running:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert


7. Load the `myservice.key` into the Rancher's Private Key field.

It should look like this in the end:

- Note that UID Field I wanted to use Zitadel's `UserID`, but it could be `Email` as well.
- Note there is no Groups field in Zitadel's SAMLResponse but it works nevertheless. If you need to add the user to Rancher groups see notes below.


8. Click enable in Rancher, and we are done. We see the auth provider is active:


9. Logout, and we should see that we can now also login via our Keycloak provider, which is actually redirecting to our Zitadel SAML app:


10. We see our Zitadel user now in the top right corner of our Rancher profile:


11. Rancher logs will update the rancher user resource's `principalIds` to include `keycloak_user://265306122980819188`, where the id is the same as the Zitadel user id:




---

# Notes about SAML Groups

> Waring: In my testing it didn't work yet, I need to dig deeper into how Rancher groups work in their docs.

There is no Groups field in Zitadel's SAMLResponse but it works nevertheless. If you need to add the user to Rancher groups you can create an action to add it.

function setCustomAttribute(ctx, api){
    api.v1.attributes.setCustomAttribute('Groups', '', 'settings-manage')
}


## Creating a New User

Any user that can register and login via Zitadel is able to login
to Rancher by default. I'm sure Zitadel Rancher SAML App can be restricted to only certain Zitadel Users that have project/app access(?)

Rancher log when signin into as a new Zitadel user first time:

2024/05/02 10:26:23 [INFO] Creating user for principal keycloak_user://265329911630135303
2024/05/02 10:26:23 [INFO] Creating globalRoleBindings for u-r3tnxufjdy
2024/05/02 10:26:23 [INFO] Creating new GlobalRoleBinding for GlobalRoleBinding grb-qfhdn
2024/05/02 10:26:23 [INFO] [mgmt-auth-grb-controller] Creating clusterRoleBinding for globalRoleBinding grb-qfhdn for user u-r3tnxufjdy with role cattle-globalrole-user

---

### Community links:

- [Me in Zitadel Discord](https://discord.com/channels/927474939156643850/927866013545025566/1235495550464430091)
- [Me in Rancher Slack](https://rancher-users.slack.com/archives/C3ASABBD1/p1714637758597989)

### Resources:

- [GitHub Gist](https://gist.github.com/PhilipSchmid/506b33cd74ddef4064d30fba50635c5b)
- [Rancher Dashboard Auth Providers Guide](https://rancher.github.io/dashboard/guide/auth-providers#developer-set-up-saml)
- [Rancher Docs - Configure Keycloak SAML](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml)