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
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.
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":
SAML & GitLab
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
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.
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
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
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
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.
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 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.
is maintained by the amazing people at OneLogin.