Paul Murray - SAML SSO
module-name: "SAML"
area: "Product Knowledge"
gitlab-group: "Manage:Access"
maintainers:
- cynthia
- anton
Overview
Goal: Set a clear path for SAML SSO Expert training
Objectives: At the end of this module, you should be able to:
- Understand how GitLab leverages the OmniAuth gem with a SAML Strategy to act as a SAML 2.0 Service Provider
- Understand how to set up SAML apps for SSO for Groups
- Troubleshoot customer's issues with SAML
This is a prerequisite to the SCIM module. Remember to contribute to any documentation that needs updating.
Stage 0: Create and commit to the module
-
Create an issue using this template by making the Issue Title: SAML SSO - -
Add yourself and your trainer as the assignees. -
Notify your manager to let them know you've started. -
Optional: Commit to this by notifying the current experts that they can start routing SAML SSO questions to you. -
Optional: Set a milestone, if applicable, and a due date to help motivate yourself!
Stage 1: Become familiar with what SAML is
-
Done with Stage 1
-
Read through the GitLab SAML Documentation. -
Read through the omniauth-saml gem documentation. -
Read through the GitLab SAML SSO for Groups Documentation. -
Watch the Manage 201 SAML knowledge sharing. You can access the slides as well. -
Watch the Support Authentication Deep Dive (recorded Dec 2022) and review the accompanied slides:
Slides
Stage 2: Technical Setup
-
Done with Stage 2
-
Implement SAML
SAML works on both GitLab.com and Self-managed. But it's much easier to do all tests on self- managed once you setup your instance. No restrictions or having to use ultimate/premium trials on groups like in SaaS.
-
Note: If you do encounter a scenario where you want or need to test SAML/SSO on a top-level paid GitLab.com group, follow the instructions in Testing Environment: on GitLab.com section.
-
Note: If using GDK, follow the SAML How To Documentation. If you prefer, you can use the same Docker images but with a non-GDK instance of GitLab.
-
Note: If you are using support resources, you would need to create a firewall rule to allow the custom ports.
-
Note: Refer to the Testing Environment page within the Support Team Handbook for details on Azure or Okta access for SAML testing purposes.
-
Set up instance-wide SAML on your GitLab instance. -
Set up Group SAML on your GitLab instance. Note: You can check our docs to configure group SAML for Omnibus Installation and Source Installations. -
Contribute to the documentation with any issues or troubleshooting steps.
The most used IdPs that you would deal with in tickets are
Azure
andOkta
. Pick one of them and comment out the other. (Your choice is: _______ )-
Setup and configure Group SAML. -
Setup Azure or Okta. Refer to Azure Setup notes or Okta Setup notes, and troubleshooting group SAML. -
Create subgroups in your group and Setup Group Links.
-
Stage 3: Tickets
-
Done with Stage 3
-
Go through 10 solved SAML/SSO tickets to check the responses and get a sense of the types of frequently asked questions that come up. -
__ -
__ -
__ -
__ -
__ -
__ -
__ -
__ -
__ -
__
-
-
Answer 5 SAML/SSO tickets and paste the links here, even if a ticket seems too advanced for you to answer. Find the answers from an expert and relay them to the customers. Tickets should cover at least 2 different SAML providers, and both SaaS and Self-Managed.
Stage 4: Pair on Customer Calls (Optional)
-
Done with Stage 4
-
Pair on two calls, where a customer has a problem with SAML/SSO. -
call with ___ -
call with ___
-
Stage 5: Assessment
Note: Please do not look at the assessment until you are ready to complete it.
-
Done with Stage X
-
Complete the assessment.
- If you are linked to a Google form, please complete the self-assessment. If you have any questions about the answers, please ask your trainer or an expert.
- If something is incorrect, please consult with your trainer or an expert and fix it in the Support Team Drive Training/Training Module Assessments folder.
Penultimate Stage: Review
Any updates or improvements needed? If there are any dead links, out of date or inaccurate content, missing content whether in this module or in other documentation, list it below as tasks for yourself! Once ready, have a maintainer or manager review.
-
Update ...
Final Stage
-
Have your trainer review your assessment. If you do not have a trainer, ask an expert to review. -
Manager: schedule a call (or integrate into 1:1) to review how the module went. -
Submit a MR to update modules
andknowledge_areas
in the Support Team yaml file with this training module's topic. You will now be listed as an expert in SAML on Skills by Person page.
SAML is often used together with SCIM so it may be worth starting the SCIM module next.