Setting Up OpenID Connect Federated Single Sign-On (SSO)

Codefresh natively supports login using Github, Bitbucket and Gitlab using OpenID Connect (OAUTH 2.0) protocol. This guide will review how to add additional SSO integrations based on OAUTH 2.0 as part of Codefresh Enterprise plan.

Prerequisites

In order to add successfully an identity provider in Codefresh you need to do some preparatory work with both Codefresh and the provider.

  1. You need to inform your Identify provider that it will provide SSO services to Codefresh
  2. You need to setup Codefresh and point it to your identity provider.

The first procedure differs according to you Identity provider, but the second one is common for all providers.

Note that SSO is only available to Enterprise customers. Please contact sales in order to enable it for your Codefresh account.

Identity provider options

Codefresh currently supports

  • Auth0
  • Azure
  • Okta
  • OneLogin

You can setup each provider

  1. At the Codefresh customer level
  2. At the Codefresh account level
  3. At both levels. Integrations that were created from the customer level can only be edited or removed by the customer administrator from that customer management view. The Account administrator won’t be able to edit those.

The specific way depends on your own organization and how you have chosen to give Codefresh access to your users.

To access the SSO configuration at the account level.

  1. Click on your avatar at the top right of the GUI and select Account settings
  2. In the new screen, select Single Sign-on from the left sidebar

To access the SSO configuration at the customer level

  1. Click on your avatar at the top right of the GUI and select any customer from the Customers subsection
  2. In the new screen, select Single Sign-on from the left sidebar

In both cases you will arrive to the following screen

SSO provider settings

SSO provider settings

To connect an identity provider click the add single-sign-on button and select your provider from the drop-down menu.

Codefresh SSO setup

Regardless of the Identity provider that you have chosen, the Codefresh setup is the similar for all of them. You need to provide several fields to Codefresh to activate SSO. The common ones are:

  • Display Name - A name for your Identity provider
  • Client ID - An ID that will be used for the connection
  • Client Secret - A secret associated with the ID

Some providers also need additional fields which are specific to that provider.

The process to obtain the values for these fields depends on the individual Identity provider. In the following sections we will outline the details for each one.

Setting Auth0 as an Identity provider

See the Auth0 instructions.

Setting Azure as an Identity provider

See the Azure instructions.

Setting Okta as an Identity provider

See the Okta instructions.

Setting OneLogin as an Identity provider

See the OneLogin instructions.

Testing your Identity provider

Once you setup the Identity provider do the following

  1. Go to the collaborators screen by clicking on People on the left sidebar (under User Management)
  2. Add an active user that will be used for testing. We recommend you use your own user

Adding collaborators

Adding collaborators
  1. Keep the current browser session open, and login via Corporate SSO in an incognito tab (or another browser).

Sign-in with SSO

Sign-in with SSO
  1. If everything works ok add more users

Selecting SSO method for collaborators

To add users and select their SSO method, go to Collaborators from the left sidebar. Then add the email or Codefresh username of a user.

In addition to their role you can now select the SSO method they will use

Selecting SSO method

Selecting SSO method

Notice that users that are added either manually or via synchronization (described in the next section) are by default NOT set to login via SSO. Remember to select the SSO method for each one.

It possible to use a different SSO method for each user (if you have multiple SSO configurations).

Syncing of teams after initial SSO setup

Once the initial setup is done, you can also sync your teams between Codefresh and the Identity provider. You can do this via the Codefresh Cli and specifically the sync command.

Note that currently teams/groups that contain spaces in their names are not synced. We will soon fix this limitation.

For example to sync you azure teams you can execute

codefresh synchronize teams my-client-name -t azure

You can find the client-name from the SSO UI.

SSO Client Name

SSO Client Name

Even though you can run this command manually it makes more sense to run it periodically as a job. And the obvious way to perform this, is with a Codefresh pipeline. The CLI can be used as a freestyle step.

You can create a git repository with a codefresh.yml file with the following contents:

YAML

version: '1.0'
steps:
  syncMyTeams:
    title: syncTeams
    image: codefresh/cli
    commands:
      - 'codefresh synchronize teams my-client-name -t azure'

To fully automate this pipeline you should set a cron trigger for this pipeline. The cron-trigger will be responsible for running this pipeline (and therefore synchronizing the teams) in a fully automated manner.

This way you can synchronize your teams every day/week/hour depending on you cron trigger setup.