gitlab-org--gitlab-foss/doc/administration/auth/okta.md

type	stage	group	info
reference	Manage	Access	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Okta SSO provider

Okta is a Single Sign-on provider that can be used to authenticate with GitLab.

The following documentation enables Okta as a SAML provider.

Configure the Okta application

The following guidance is based on this Okta article, on adding a SAML Application with an Okta Developer account:

1. In the Okta admin section, make sure to select Classic UI view in the top left corner. From there, choose to Add an App.

2. When the app screen comes up you see another button to Create an App and choose SAML 2.0 on the next screen.

3. Optionally you can add a logo (you can choose it from https://about.gitlab.com/press/). You'll have to crop and resize it.

4. Next, you'll need the to fill in the SAML general configuration. Here's an example (showing the required URLs and attribute mapping): image.

   

5. The last part of the configuration is the feedback section where you can just say you're a customer and creating an app for internal use.

6. When you have your app you'll have a few tabs on the top of the app's profile. Click on the SAML 2.0 configuration instructions button which should look like the following:

   

7. On the screen that comes up take note of the Identity Provider Single Sign-On URL which you'll use for the idp_sso_target_url on your GitLab configuration file.

8. Before you leave Okta make sure you add your user and groups if any.

---

Now that the Okta app is configured, it's time to enable it in GitLab.

Configure GitLab

1. See Initial OmniAuth Configuration for initial settings.

2. To allow your users to use Okta to sign up without having to manually create an account first, don't forget to add the following values to your configuration:

   For Omnibus GitLab installations

   Edit /etc/gitlab/gitlab.rb:

   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
   gitlab_rails['omniauth_block_auto_created_users'] = false
   

   ---

   For installations from source

   Edit config/gitlab.yml:

   allow_single_sign_on: ["saml"]
   block_auto_created_users: false
   

3. You can also automatically link Okta users with existing GitLab users if their email addresses match by adding the following setting:

   For Omnibus GitLab installations

   Edit /etc/gitlab/gitlab.rb:

   gitlab_rails['omniauth_auto_link_saml_user'] = true
   

   ---

   For installations from source

   Edit config/gitlab.yml:

   auto_link_saml_user: true
   

4. Add the provider configuration.

   Notes:

   • Change the value for assertion_consumer_service_url to match the HTTPS endpoint of GitLab (append users/auth/saml/callback to the HTTPS URL of your GitLab installation to generate the correct value).

   • To get the idp_cert_fingerprint fingerprint, first download the certificate from the Okta app you registered and then run: openssl x509 -in okta.cert -noout -fingerprint. Substitute okta.cert with the location of your certificate.

   • Change the value of idp_sso_target_url, with the value of the Identity Provider Single Sign-On URL from the step when you configured the Okta app.

   • Change the value of issuer to the value of the Audience Restriction from your Okta app configuration. This will identify GitLab to the IdP.

   • Leave name_identifier_format as-is.

   For Omnibus GitLab installations

   gitlab_rails['omniauth_providers'] = [
     {
       name: 'saml',
       args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
              },
       label: 'Okta' # optional label for SAML login button, defaults to "Saml"
     }
   ]
   

   For installations from source

   - {
       name: 'saml',
       args: {
              assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
              idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
              idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
              issuer: 'https://gitlab.example.com',
              name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
            },
       label: 'Okta' # optional label for SAML login button, defaults to "Saml"
     }
   

5. Reconfigure or restart GitLab for Omnibus and installations from source respectively for the changes to take effect.

You might want to try this out on an incognito browser window.

Configuring groups

NOTE: Make sure the groups exist and are assigned to the Okta app.

You can take a look of the SAML documentation on configuring groups.