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.
In order to add successfully an identity Provider in Codefresh you need to do some preparatory work with both Codefresh and the provider.
- You need to inform your Identify provider that it will provide SSO services to Codefresh
- 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
To access the SSO configuration at the account level.
- Click on your avatar at the top right of the GUI and select Account settings
- In the new screen, select Single Sign-on from the left sidebar
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 Google as an Identity provider
See the Google 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
- Go to the collaborators screen by clicking on People on the left sidebar (under User Management)
- Add an active user that will be used for testing. We recommend you use your own user
- Change Login methog by selecting your Auth provider in the SSO drop-down
- Keep the current browser session open, and login via Corporate SSO in an incognito tab (or another browser).
- If everything works ok add more users
Before enabling SSO for all users, you MUST make sure that it is working for the test user, because if SSO is enabled for a user, Codefresh blocks logins through other IDPs for this user and only the enabled SSO is allowed. If the selected SSO method does not work for some reason, users will be locked out of Codefresh.
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
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).
Setting a default provider
If you have multiple SSO providers set you can hover your mouse on the top right of the SSO screen and setup one of them as the default provider.
If a default sso provider is set then:
- This SSO method will be automatically assigned to all new invited users
- All new users will receive an email with an invite link that points them directly to the login page of that SSO provider
Syncing of teams after initial SSO setup
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.
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:
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.