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

  • Azure
  • Okta
  • Auth0

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 Azure as an Identity provider

To setup Azure Active Directory for SSO

  1. Create a new application in Azure AD

Login to Microsoft Azure and choose Azure Active Directory from the sidebar.

Azure Active Directory

Azure Active Directory

Then under MANAGE, select App registrations.

Azure App Registrations

Azure App Registrations

Then click on the + ADD button to add a new application.

Enter a name for the application (e.g. Codefresh), select Web app/API as the Application Type, and for Sign-on URL enter https://g.codefresh.io

Azure App Registration create

Azure App Registration create
  1. Configure the permissions

Once the application has been created, you will have to configure the permissions. Click on the name of the application to open the Settings section.

Click Required permissions.

Azure App Permissions

Azure App Permissions

Then click on Windows Azure Active Directory to change the access levels.

Azure App Change Permissions

Azure App Change Permissions

The next step is to modify permissions for the app. Under DELEGATED PERMISSIONS check next to Sign in and read user profile and Read directory data. Finally click the Save button.

  1. Create the key

Next you will need to create a key which will be used as the Client Secret in Codefresh connection. Click on Keys from the Settings menu.

Change keys

Change keys

Enter a name for the key and choose the desired duration.

Note:. If you choose an expiring key, make sure to record the expiration date in your calendar, as you will need to renew the key (get a new one) before that day in order to ensure users don’t experience a service interruption.

Create key

Create key

Click on Save and the key will be displayed. Make sure to copy the value of this key before leaving this screen, otherwise you may need to create a new key. This value will need to be provided to Codefresh securely.

Create key

Create key
  1. Go back to the SSO settings screen described in the first part of this guide inside the Codefresh GUI.

You need to enter the following:

  • Display Name - Shown as display name in Azure
  • client id - your Azure Application ID (see below)
  • client secret - the key from step 3
  • tenant - <Your Microsoft Azure AD Domain>.onmicrosoft.com
  • Object ID - your Azure Object ID (see below)

Application ID

Application ID

Once you save the Identity provider, Codefresh will assign a client-name to it which identifies the SSO configuration.

SSO Client Name

SSO Client Name
  1. Configure reply URLs

As a last step you need to ensure that your Codefresh callback URL is listed in allowed reply URLs for the created application. Navigate to Azure Active Directory -> Apps registrations and select your app. Then click Settings -> Reply URLs and add:

https://g.codefresh.io/api/auth/<your_codefresh_sso_client_name>/callback

where <your_codefresh_sso_client_name> is the client name shown in the SSO configuration.

Reply URLs

Reply URLs

This concludes the SSO setup for Azure. See the following sections on how to test the integration, activate SSO for collaborators and create sync jobs.

Setting Okta as an Identity provider

  1. Log in to your Okta account. If you don’t already have one, you will need to create one.

On the general Okta dashboard, click Admin. This takes you to the Okta Admin Dashboard.

Okta Dashboard

Okta Dashboard

Using the list of shortcuts at the right-hand side of the screen, click Add Applications.

Okta Applications

Okta Applications

On the Add Application page, select Create New App.

Create new application

Create new application

On the Create a New Application Integration pop-up window, select Web as the Platform for Codefresh application, and choose OpenID Connect as the Sign on method. Click Create to proceed.

Choose Sign-on method

Choose Sign-on method
  1. You will now create your OIDC integration. On the General Settings page, provide the following:
  • App name (e.g. Codefresh)
  • App logo (optional). Feel free to download and add this picture
  • Login redirect URI: https://g.codefresh.io/api/auth/<your_codefresh_client_name>/callback you’ll be able to extract your codefresh client name a bit later in the process so we’ll need to come back to this and update it again - for now please use a temp value such as https://g.codefresh.io/api/auth/temp/callback

OpenID integration

OpenID integration

Click Save to proceed.

  1. Go back to the SSO settings screen described in the first part of this guide inside the Codefresh GUI.

You need to enter the following:

  • Display Name - Shown as application name in OKTA
  • client id - your OKTA application client ID (see below)
  • client secret* - your OKTA application client secret (see below)
  • Client Host - your OKTA organisation url (e.g https://<company>.okta.com). Keep in mind you don’t copy it from the admin view (e.g. https://<company>-admin.okta.com) because it’ll not work.
  • Access Token (optional) - OKTA API token that will be used to sync groups and users from OKTA to Codefresh. The token can be generated in OKTA by going to the security tab->API (see below)
  • App ID (optional) - your Codefresh application ID in your OKTA organization that will be used to sync groups and users from OKTA to Codefresh. This ID can be taken by navigating to your Codefresh APP in OKTA and copy it from the url (see below)

Client ID and secret

Client ID and secret

Access token

Access token

App ID

App ID
  1. Once you save the Identity provider, Codefresh will assign a client-name to it which identifies the SSO configuration. Note it down.

Client name

Client name
  1. Go Back to your OKTA Application General Settings and update the following 2 configurations with the client name generated by Codefresh:
  • Login redirect URIs - https://g.codefresh.io/api/auth/<your_codefresh_client_name>/callback
  • Initiate login URI - https://g.codefresh.io/api/auth/okta?client=<your_codefresh_client_name>

This concludes the SSO setup for Okta. See the following sections on how to test the integration, activate SSO for collaborators and create sync jobs.

Setting Auth0 as an Identity provider

Coming soon…

Testing your Identity provider

Once you setup the Identity provider do the following

  1. Go to the collaborators screen by clicking on Collaborators on the left sidebar
  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.

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'
    when:
      branch:
        only:
          - master

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.