Red Hat SummitBlog da Red Hat
I have been asked, tasked, and dropped in by parachute on an extraordinary number of occasions recently to answer questions about, and implement solution for, Single Sign On (SSO) to OpenShift Container Platform. These conversations can start in multiple ways:
- How do I do SSO to OpenShift?
- How do I integrate OpenShift with my existing SAML identity provider?
- How do I log into OpenShift with my PIV and PIN?
A Red Hat foi reconhecida como líder no relatório Magic Quadrant™ do Gartner® de 2023
A capacidade de execução e a visão abrangente da Red Hat garantiram à empresa o primeiro lugar na categoria Gestão de Containers do relatório Magic Quadrant™ 2023, do Gartner.
The goal of all of these questions is typically the same and all have the same answer. Organizations typically have an existing SAML based identity provider they use for single sign on, and in the case of many, especially government, organizations the identity is provided by the user via a PIV and PIN.
Request Header Identity Provider
If you were to search the OpenShift documentation for single sign on you will find one hit in the OpenID section of the Configuring Authentication documentation. Though from experience the majority of the organizations do not have an existing identity provider (IdP) that exposes an OpenID endpoint. If you then move onto searching for SAML, the much more prevelevent pre-existing identity protocol in organization's IT infrastructure, you will again find one hit, this time Request header identity provider documentation.
If you read the documentation and then parse it for it’s meaning you will arrive at the conclusion that the Request header authentication mechanism is what will allow you to use any IdP you want with OpenShift that isn’t already natively supported some other way. The way this is done is by putting a proxy, more on that later, between the OpenShift request header authentication and your IdP to translate from your IdP to request headers which the OpenShift request header authentication understands.
Single Sign On Authorization Example
Combine the OpenShift Web Console, OpenShift OAuth Request Header identity provider, SAML Proxy, your IdP, and OpenShift RBAC and you are done. Confused? So was I, so here is a picture.
- User browses to OpenShift Web Console
- OpenShift Web Console redirects the User to the SAML Proxy
- SAML Proxy redirects the user to the IdP
- User provides their identity credentials to the IdP
- IdP sends a SAML authn response to the SAML Proxy containing the user identity and attributes
- SAML Proxy transforms the IdP SAML authn response attributes to request headers and forwards to OpenShift OAuth Request Header identity provider
- OpenShift OAuth Request Header identity provider redirects the User back to the OpenShift Web Console as an authenticated user
- OpenShift Web Console uses User’s authenticated user identity to determine authorization via OpenShift RBAC
- User is logged into OpenShift Web Console as their authenticated SAML IdP identity and their mapped RBAC authorization
This process only outlines the initial successful login, the process if a login fails, or if a user already has a valid IdP SAML session is slightly different but there is no need to dive into those details here.
Authentication and Authorization
One interesting feature of this process to call attention to is that the OpenShift authentication and authorization systems are decoupled which also mean that your authentication and authorization IdPs can be decoupled. The two requirements are:
- The user's identity, aka: their username, be identical in both the authentication IdP and the authorization IdP
- The only supported mechanism for externally syncing user and group mappings is via Syncing groups with LDAP
This means you have two options. If you have an IdP that exposes both SAML and LDAP end points then you can use that singular IdP for both your authentication and authorization. If your SAML IdP is different then your LDAP IdP then, assuming you are syncing your user group membership from LDAP, the requirement is to be sure that the user identities in your LDAP IdP match those in your SAML IdP.
LDAP Authorization Example
While not strictly in the purview of SSO authentication to OpenShift for context here is an example of how the user identity to group mappings via LDAP group sync works. If you have been using OpenShift for any amount of time you likely already have LDAP group sync set up in which case, this is helpful but redundant information.
- Administrator configures LDAP Group Sync to synchronize the specified groups and their users to OpenShift and configures sync to run on a schedule
- On each LDAP Group Sync the specified groups and their associated users pulled from LDAP
- On each LDAP Group Sync the specified groups and their associated users are updated in OpenShift RBAC groups
- Administrator applies OpenShift Role(s) to the OpenShift groups to define the authorization matrix
As noted in the Authentication and Authorization section, the key requirement you need to keep in mind is that the user identities being put in OpenShift groups by the LDAP Group Sync need to match the identities coming back from the SAML authorization.
Where is the PIV and PIN or User Id and Token?
Since OpenShift is redirecting to the SAML Proxy and the SAML Proxy is redirecting to your SAML IdP, it is up to your SAML IdP to determine the type of credentials provided by the user to your SAML IdP to confirm the users identity. No matter the type of credentials your organization uses, whether that be PIV and PIN, user id and token, username and password, or even biometrics, supporting and verifying those credentials is the responsibility of your SAML IdP. Once the SAML IdP verifies the users identity then it sends the SAML authn response back to the SAML Proxy which is then translated to request headers. Thus abstracting the type of credentials provided to the SAML IdP from the OpenShift OAuth system.
Implementation
Authentication
If you are interested in implementing this solution then detailed instructions can be found in the openshift/request-header-saml-service-provider project on GitHub.
A word of caution, as illustrated there are many subsystems involved in this solution and many connections between all those systems, a failure in one causes the entire system not to work. While there are some debugging tips in the openshift/request-header-saml-service-provider project they are be no means comprehensive of everything that could go wrong. If your SAML IdP is Microsoft ADFS then the mod_auth_mellon documentation (Apache HTTPD Module used in the SAML Proxy) has some helpful debugging tips as well.
It can not be stressed enough the importance of planning for this implementation to take a couple to a few days. It is highly recommended when trying to debug that you get a screen sharing conference call going that includes your OpenShift and IdP administrators at the same time so as to be able to see logs from and make configuration adjustments to both systems in real time.
Authorization
The OpenShift documentation on Syncing groups with LDAP is very good but does not outline a process for automating the sync process or presenting it as Infrastructure as Code. The community supported RedHatOfficial/ansible-redhat_openshift_utils project on GitHub has an ocp-ldap-groups-sync.yml playbook which can be used to automate and represent your LDAP group sync and group to role mapping as infrastructure as code. Like the openshift/request-header-saml-service-provider project this project is only supported by the community and does not have any official Red Hat Support support.
Support
It is important to understand the limits of the support for this solution assuming you have a Red Hat subscription to OpenShift Container Platform. Referencing the picture everything in the Web Console and and Master API containers and their configuration is officially supported. The SAML Proxy, the one provided and configured via the openshift/request-header-saml-service-provider project, is community supported only. Additionally your IdP configuration is the responsibility of your IdP administrators and vendor(s). Keep this in mind when/if opening a support case for help with this solution as Red Hat support will be able to help with your Web Console and Master API configurations and troubleshooting, but the troubleshooting of the SAML Proxy and your IdP is on you and the community.
If you are interested in getting help with this solution reach out to your existing Red Hat Account Executive or vist Red Hat Consulting to get a conversation started.
Connect with Red Hat Services
Learn more about Red Hat Consulting
Learn more about Red Hat Training
Learn more about Red Hat Certification
Join the Red Hat Learning Community
Subscribe to the Training Newsletter
Follow Red Hat Services on Twitter
Follow Red Hat Open Innovation Labs on Twitter
Like Red Hat Services on Facebook
Watch Red Hat Training videos on YouTube
Follow Red Hat Certified Professionals on LinkedIn
