Setting Up SAML2 Federated Single Sign-On (SSO)
As IdPs come in all shapes and sizes, the following topic discusses in general what you must do to configure Federated SSO. As you will see in the description below, the person in your organization responsible for managing your IdP will need to interact with Codefresh support team to successfully set up a trust between your IdP and Codefresh SP.
Before you set up Federated SSO
- Have your account set up with Codefresh enterprise plan.
- Ensure you have a working SAML 2.0 compliant Identity Provider (IdP).
- Identify someone in your organization who is familiar with configuring and managing your organization’s IdP.
- Ensure that your IdP’s system clock is synchronized with a reliable time source. If it’s not, tokens generated will be unusable and SSO will fail.
Summary of Federated SSO Setup
Codefresh expects the following user attributes to be passed through SAML between your Idp and Codefresh SP:
- User email address
- User first name
- User last name
- User full name
- User unique ID that isn’t subject to change in your identity management environment
How does the connection process work?
Once Federated SSO has been configured, the process works as follows:
Steps 2 to 7 happens in the background and are transparent to the user.
- A user logs in to Codefresh and enters their email
- The user is redirected to Codefresh Service Provider (SP) to initiate SSO
- The user’s browser is then redirected to the customer IdP
- Once authenticated by the corporate side, a SAML token is sent to the user’s browser
- The SAML assertion is then forwarded to Codefresh SP
- If you are a valid Codefresh user for this SSO connection, an SSO token is returned to the user’s browser
- The user’s browser then returns a token to Codefresh and access is granted for your account
Setting Up SAML Integration
Go to your SSO settings by clicking on Account settings on the left sidebar in the Codefresh UI and then selecting Single Sign-on again from the left sibar (or visit directly https://g.codefresh.io/account-admin/sso)
Click the ADD SINGLE SIGN-ON button and select SAML from the drop-down
Fill in the fields:
- Client Name - leave the field empty and it will get an autogenerated value once you save the settings.
- Display Name - any arbitrary name you want to give in this integration.
- IDP Entry - The SSO endpoint of your Identity Provider. (Ex: For Azure SAML, this is the Login URL)
- Application Certificate - The security certificate of your Identity Provider. Paste the value directly on the field. Do not convert to base64 or any other encoding by hand. (Ex: For Azure SAML, this will be Certificate (Base64) and the value needed is between the —–BEGIN … and —–END… from the downloaded cert)
- Assertion URL -
is taken from the SSO configuration you created on the section above. It was automatically generated by Codefresh after saving the SSO settings).
- Auto Sync users and teams to Codefresh - This only works for Google / GSuite SAML integration.
When syncing users with custom schema, in the Sync field, add the custom schemaName. Otherwise, if you are syncing all users and groups, leave this field empty.
Click the SAVE button and make sure to note down the
Client Name that was autogenerated.
Then in the settings of your Identity Provider create a new Service Provider and provide the following:
- Service Provider SSO Endpoint - (Assertion consumer service URL) -
- Service Provider Entity ID -
The mandatory fields needed for SAML assertions are:
- firstName - user first name
- lastName - user last name
- email - user email
- NameID - user email (some IDPs like OneLogin and Ping Federate will need this)
To configure users sync for SAML IDP you need to do the following:
- Select a G Suite provider
- Enable Auto Sync users and teams to Codefresh
- Set JSON Keyfile, Admin Email and Sync interval
The instructions for getting the JSON Keyfile, and Admin Email are the same as for Google SSO.
Notice that these settings are for the SaaS version of Codefresh. For an on-premise Codefresh setup you need to use the URLs that match your installation.
Once everything is finished, you should test the integration. Once it’s working, proceed to the next steps that are:
Notice that Codefresh has an internal cache for SSO configurations and it might take up to five minutes for your changes to take effect.