As a Service Engineer I'm in constant contact with customers, listening to their needs, and I've noticed a steadily-increasing interest in SAML from our Enterprise Customers. That inspired me to dive a little deeper into the topic in an effort to improve our integration with SAML and to add better documentation. I hope this helps our customers and our community to better understand this feature.
In this blog post I'll give you an overview of what I've been working on, how it affects GitLab, and what we plan to do with SAML in the future. Our plan is to bring SAML up to par with the features that LDAP offers within GitLab.
What is SAML?
SAML stands for Security Assertion Markup Language. It is an XML standard that allows secure web domains to exchange user authentication and authorization data. Using SAML, an online service provider can contact a separate online identity provider to authenticate users who are trying to access secure content. [1]
This gives you the ability to add users to your service without having to know anything about them beforehand. You just need to trust the identity provider.
It also provides you with the ability to enable Single Sign On (SSO) for your GitLab instance, allowing your users to access your GitLab instance without having to create a new account and set a password.
Here is an example on how the SAML request and response work. In this example GitLab would be the "Service Provider":
Public domain image from Wikipedia
SAML & GitLab
The beginnings
GitLab first introduced SAML support in version 7.12 via a contribution from our amazing community. The feature was contributed by CERN almost 10 months ago. Since the original contribution, not much changed around the SAML support offered by GitLab. But interest from our users and our customers increased. You can check all SAML related merge requests here.
Due to the increased interest, I decided to dive into all the parts required to
get GitLab to speak SAML. Here I encountered omniauth-saml, a project with thousands
of downloads that has been dormant for the past 6 months.
Reviving omniauth-saml
The omniauth-saml gem was originally developed and maintained by
Practically Green, but in the last couple of months
it lost momentum from its maintainers.
The gem on which this one is based, ruby-saml, started to add new features
recently and merge requests were made on the omniauth-saml repo to add these
new features as well, but they went without review from the maintainers
for quite some time.
Luckily the maintainers realized that there was still a lot of interest in the
omniauth-saml gem and decided
to give control of the gem to the community. Since I was one of the people
involved in the latest merge requests, I was included in the list of people
given owner access. This allowed a small group of passionate people to continue
the amazing work that the developers at Practically Green started almost 5
years ago.
Once this process was completed we immediately got to work reviewing pending pull
requests, asking community members to update their code to resolve conflicts,
solving old issues, updating dependencies, and adding a continuous integration
service. All this work culminated a few weeks ago when we released omniauth-saml
version 1.5.0
with support for Custom Attributes,
better error handling, and a couple of bug fixes.
The inclusion of these features, especially the Custom Attributes, are of great
use to GitLab users. You no longer need to change your Identity Provider (IdP)
server to match the parameters that GitLab is expecting, you can now tell
omniauth-saml, and therefore GitLab, where to look for them.
GitLab relies on omniauth-saml to
provide the integration with a SAML IdP. It also uses
Devise as an authentication platform.
Devise allows you to extend its authentication mechanism using Omniauth.
omniauth-saml is a strategy that allows Omniauth to retrieve user information
from a SAML IdP and relay this information to GitLab to either create a new user,
or bind this new authentication mechanism to an existing user (if GitLab is
configured to do so).
Along with the inclusion of better SAML documentation, these changes will help users and admins better integrate their GitLab installation with their SAML provider, and more easily detect and troubleshoot any errors.
The future
We recently started separating SAML from the rest of the regular Omniauth providers to give us some room to improve the integration between SAML and GitLab.
At the moment SAML only functions as an authentication provider, but with SAML 2.0 (the only version of SAML supported by GitLab) you can also retrieve Group Membership information from the Identity Provider, if the IdP server supports this feature and is configured to respond with this information. For this to work, the membership information needs to be added to the SAML response as a SAML Attribute in the generated SAML 2.0 Assertion.
If we leverage this feature, we would be able to manage GitLab Group Memberships
via SAML, as we do now for LDAP within Enterprise Edition. This would allow
admins to offload the management of user groups to a different service, offer
their users an SSO system, and not have to worry about setting up LDAP as well
as SAML to accomplish both. For this we will need to use ruby-saml directly.
ruby-saml
ruby-saml is a Ruby library for
implementing client-side SAML authorization. omniauth-saml relies on this library
for initialization and validation of a SAML request/response protocol. ruby-saml
is maintained by the amazing people at OneLogin.
We still need to investigate how to best approach this endeavour and determine how much work it would be. But our plan is to bring SAML up to par with the features that LDAP offers within GitLab.
Are you integrating SAML with GitLab or any other application? Let us know if you
run into any problems with GitLab & SAML
or omniauth-saml by creating
issues in the respective repository.