AWS IAM Identity Center (successor to AWS SSO) Integration Guide for GitLab
Introduction
This document helps you configure IAM Identity Center to facilitate single sign-on (SSO) for GitLab using SAML.
Topics
Prerequisites
You'll need the following to set up SSO access to GitLab:
-
Access to the IAM Identity Center console with permissions to manage applications.
-
A GitLab account with permissions to configure SAML.
-
An active domain name that you specified while registering the account with GitLab. For example, gitlab.awssso.
-
Install the GitLab Enterprise edition on a virtual machine with public access, and use the fully qualified domain name for further configuration in IAM Identity Center. For more information, you can visit the Installation page in Gitlab.
Setup instructions
- On the Configure page in the IAM Identity Center Console, in the Details section, fill in the Display name, and the Description(optional) of the application.
Note
We suggest that you choose a unique display name if you plan to have more than one of the same application.
- Download the IAM Identity Center certificate to generate the fingerprint.
- Execute this command using command prompt and get the SHA1 fingerprint of the X509 certificate you just downloaded.
openssl x509 -noout -fingerprint -sha1 -inform pem -in [certificate-file.crt]
- Use the following values as required while configuring SSO in GitLab.
-
Use the values obtained for SSO configuration and complete the SAML integration in the installed GitLab application. For more information on SAML integration instructions, visit SAML integrations in GitLab.
-
Open a new tab, and access your GitLab Enterprise URL using "https://DOMAINNAME.com".
-
Upon first login, fill in New password and Confirm password, and choose Change your password.
-
On the Sign in page, use the new password for the
root
user, and choose Sign in. -
Referencing the documentation provided by GitLab, configure a user to use SSO in GitLab.
-
On the Users page, choose a user.
-
Choose Identities, and click New identity.
-
Fill in the display name for the identity provider in Provider. For example, IAM Identity Center.
-
Fill in the user's email address in identifier, and click Save Changes.
-
Use "https://DOMAINNAME.com/users/auth/saml/metadata" and download the GitLab SAML 2.0 metadata.
-
Go back to the previous tab, and access the IAM Identity Center console page where you are configuring the application.
-
Under Application metadata, choose Browse next to Application SAML metadata file, and upload the downloaded GitLab metadata.
-
Choose Save Changes.
-
Assign a user to the application in IAM Identity Center.
Verification
Use the following sections to verify the SSO integration.
Note
Ensure that the user performing the verification is logged out of both IAM Identity Center and the application before performing the steps in each section.
Verifying SSO from IAM Identity Center
-
Access the AWS access portal using the credentials of a user assigned to the GitLab application.
-
In the list of applications, choose GitLab to initiate a login to GitLab.
-
If login was successful you will be signed-in to the GitLab application.
Troubleshooting
If sign in was not successful, please see the troubleshooting steps.
Verifying Service Provider Initiated SSO from GitLab
-
Access GitLab using "https://DOMAINNAME.com/users/sign_in".
-
On the Sign in page, below the user credentials section, choose the button that is labelled with your identity provider name. For example, IAM Identity Center.
-
Fill in the credentials of a user assigned to the application in the IAM Identity Center console and a user which exists in GitLab.
-
Choose Sign In.
-
On the GitLab home page, verify that both GitLab and IAM Identity Center are logged in with the same user.
Troubleshooting
If sign in was not successful, please see the troubleshooting steps.
Troubleshooting
Error | Issue | Solution |
---|---|---|
"404 The page could not be found or you don't have permission to view it." | The IAM Identity Center certificate specified in GitLab is incorrect. | Make sure that the IAM Identity Center certificate is specified correctly in GitLab. |
"404 The page could not be found or you don't have permission to view it." | The ACS URL of GitLab specified in IAM Identity Center is incorrect. | Make sure that the ACS URL of GitLab is specified correctly in IAM Identity Center. |
"500 Whoops, something went wrong on our end." | The Entity ID of GitLab specified in IAM Identity Center is incorrect. | Make sure that the Entity ID of GitLab is specified correctly in AWSSSO. |
Other | When IAM Identity Center creates a SAML Assertion for a user, it uses the value of the 'email' and 'subject' fields (if they are present) from the connected directory to populate the 'Email' and 'Subject' attributes in the SAML assertion. Many service providers expect these attributes to contain the user's email address. By default your directory is configured to send 'windowsUPN' in both fields. | Your directory may be configured to contain the users email in the 'Email' attribute instead. If so, you may need to change this in your Connected directory settings. |
For general troubleshooting problems, please refer to Troubleshooting Guide.
User Provisioning Types
There are two user provisioning you need to aware of:
-
Preprovisioned users
Preprovisioned users, means users must already exist in the downstream SaaS application. For instance, you may need to create SaaS users with the same subject as the AD users.
-
JIT users
JIT (or Just-In-Time) users, means users do not necessarily exist in the downstream SaaS application, and will be provisioned/created/registered the first time the user federates. You may need to enable JIT option in your SaaS application for the AD domain.