Skip to main content

Set up SSO (Pro)

info

SSO access is an enterprise feature only available in the professional or custom package.

This article explains how to set up single-sign-on with an SSO identity-provider and CodeShield. The process is straight forward and does not take more than 10-15 minutes.

Having an external identity provider for single-sing-on to CodeShield, employees can be assigned to the CodeShield app, and login with their usual company credentials. Having set up SSO also allows all users from the same identity provider to work together with CodeShield, by optionally sharing projects and scans with each other.

info

As we employ the SAML 2.0 (Security Assertion Markup Language 2.0) standard, its possible to use any SAML-based identity provider (like Azure AD or Salesforce) to set up single-sign-on with CodeShield. If you want to connect a different identity provider than AWS SSO or Azure AD, just let us know and we are happy to assist you!

AWS SSO​

  1. Go to AWS SSO.
  2. Click on Applications in the left pane and then select Add application in the Applications configuration.
  3. Choose Add custom SAML 2.0 application.
  4. Give the application a name (like CodeShield). Leave the page open as you will need the URL to the IAM Identity Center SAML metadata file soon.
  5. Log into your CodeShield account (If you do not have a CodeShield account yet, create one first). This will be your management account. You will be able to disconnect the SAML identity provider and manage user access to all connected accounts from here later.
  6. Click on your user icon in the bottom-left corner and select SSO settings.
  7. Paste the IAM Identity Center SAML metadata file URL from 4. into the corresponding field. Click Connect IDP to connect your identity provider.
  8. After a few seconds, you will be proposed with the data to fill back into the AWS SSO application setup page from 4. Make sure to leave the current page open.
  9. Go back to the AWS SSO application set up page and fill in the Application start URL, Application ACS URL, and Application SAML audience with the values proposed by CodeShield in step 8. Submit the form.
  10. Now that AWS SSO is connected with CodeShield, you can assign the users that should be able to access CodeShield with AWS SSO. In the Application settings, click on Assign Users.
  11. Select the Users or Groups that should be able to access CodeShield and click Assign Users.
  12. Lastly, you have to add Attribute mappings to the application. Click on Actions in the application settings, and then on Edit attribute mappings.
  13. Configure the mappings as shown in the image below. Use ${user:subject} as value for the Subject and add another mapping for email with the value ${user:email}. (This will communicate a subject ID and the user's email to CodeShield once the user signs in).
  14. The setup is complete. Every user assigned to the CodeShield application in AWS SSO will now be able to sign in to CodeShield over the usual AWS SSO access portal.
info

Note that users have to login once before they are registered at CodeShield. This is a restriction of AWS SSO, CodeShield has no way to see which users are assigned to it before AWS SSO communicates their user data at their first login.

Access management​

Every user of the same identity provider can edit which other users should be able to access the user's owned account connections (and belonging scans) in the SSO settings page. The page can be reached as described in steps 5-6 of the previous section. The admin user, who owns the management account, has full control over all users and their connected accounts, and can thus even edit access rights for account connections he did not set up himself.

Azure AD​

  1. Go to Azure AD.
  2. Click on Applications in the left pane, select Enterprise applications in the submenu, and then click on New application.
  3. Choose Create your own application and give the application a name (like CodeShield). Submit the form by clicking on Create.
  4. After creating a new application in Azure AD, click on Single sign-on and choose SAML from the options. Azure will present you with a view similar to the following. Make sure to copy the App Federation Metadata Url for later.
  5. Open a new tab and log into your CodeShield account (If you do not have a CodeShield account yet, create one first). This will be your management account. You will be able to disconnect the SAML identity provider and manage user access to all connected accounts from here later.
  6. Click on your user icon in the bottom-left corner and select SSO settings.
  7. Paste the App Federation Metadata Url from 4. into the corresponding field. Click Connect IDP to connect your identity provider.
  8. After a few seconds, you will be proposed with the data to fill back into the Azure Single sign-on application setup page from 4. Make sure to leave the current page open.
  9. Go back to the Azure Single sign-on application set up page from step 4. and click on Edit besides the Basic SAML Configuration config.
  10. Fill in the Identifier field with the value of Application SAML Audience from CodeShield's dashboard (step 8.), the Reply URL field with CodeShield's Application ACS URL, the Sign on URL with CodeShield's Application start URL, and finally the Relay State URL with https://dashboard.codeshield.io/auth/saml. Submit the form.
  11. Now that Azure SSO is connected with CodeShield, you can assign the users that should be able to access CodeShield with Azure SSO. In the Application settings, click on Users and groups.
  12. Select the Users or Groups that should be able to access CodeShield.
  13. Lastly, you have to add Attributes & Claims to the application. Click on Single sign-on in the application settings, and then on Edit besides the Attributes & Claims section.
  14. Configure the mappings as shown in the image below. (This will communicate a subject ID and the user's email to CodeShield once the user signs in).
info

Sometimes user.mail is not configured to hold the email address of the Azure user entity. In such cases you will run into errors stating a missing email address, when trying to sign-in with such users. Make sure that you map the mail attribute to any attribute of your users that holds their email address. Usually user.userprincipalname (UPN) also holds the user's email address, as this is the main identifier for login. However, we cannot guarantee this and suggest to contact your IT admin to identify a proper user attribute that contains the user's email.

  1. The setup is complete. You can test it for already assigned users by using the Test button seen in step 14. Every user assigned to the CodeShield application in the Azure Single sign-on application will now be able to sign in to CodeShield over the url provided by azure:
  2. You can either provision all assigned users ahead of time, or you wait for each user to sign in once. CodeShield can handle both approaches. Each user stemming from the Azure AD and the admin user (user that created the SSO connection) are free to share connections and scans with each other. See Access Management.