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:

Setup instructions

  1. 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.

  1. Download the IAM Identity Center certificate to generate the fingerprint.
  1. 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]

  1. Use the following values as required while configuring SSO in GitLab.
  1. 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.

  2. Open a new tab, and access your GitLab Enterprise URL using "https://DOMAINNAME.com".

  3. Upon first login, fill in New password and Confirm password, and choose Change your password.

  4. On the Sign in page, use the new password for the root user, and choose Sign in.

  5. Referencing the documentation provided by GitLab, configure a user to use SSO in GitLab.

  6. On the Users page, choose a user.

  7. Choose Identities, and click New identity.

  8. Fill in the display name for the identity provider in Provider. For example, IAM Identity Center.

  9. Fill in the user's email address in identifier, and click Save Changes.

  10. Use "https://DOMAINNAME.com/users/auth/saml/metadata" and download the GitLab SAML 2.0 metadata.

  11. Go back to the previous tab, and access the IAM Identity Center console page where you are configuring the application.

  12. Under Application metadata, choose Browse next to Application SAML metadata file, and upload the downloaded GitLab metadata.

  13. Choose Save Changes.

  14. 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

  1. Access the AWS access portal using the credentials of a user assigned to the GitLab application.

  2. In the list of applications, choose GitLab to initiate a login to GitLab.

  3. 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

  1. Access GitLab using "https://DOMAINNAME.com/users/sign_in".

  2. 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.

  3. Fill in the credentials of a user assigned to the application in the IAM Identity Center console and a user which exists in GitLab.

  4. Choose Sign In.

  5. 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: