Configure SSHepherd® to use a 3rd-Party Identity Provider

SSHepherd supports the following 3rd party Identity Provider types:

• SAML
• OIDC
• Active Directory

SSHepherd® also supports utilizing the SCIM protocol with either SAML or OIDC to provisioning users, groups and user group memberships.

Summary of Steps Necessary to Complete the Setup

1. Install the SSHepherd® C3 server using it’s internal identity provider (including creating the initial local administrative account)
2. If using SAML or OIDC, log in to your Identity Provider and configure the SSHepherd® application (and optionally configure SCIM)
3. Log in to the SSHepherd® C3 server, select the appropriate 3^rd party provider tab, and enter the configuration details to complete the integration
4. Grant Admin access to the C3 server once the accounts have been provisioned.

Step 1: Install the SSHepherd® C3 server per the documentation

The SSHepherd® C3 server installation guide can be found here. Once you have installed the SSHepherd® C3 server and created the initial local administrator account, continue to Step 2.

Step 2: Configure the SAML or OIDC Identity Provider

IMPORTANT: See the Appendices of this document for specific instructions for Microsoft Entra.

1. Create the Application for SSHepherd® in the identity provider’s console.
2. If required by the identity provider, assign/grant users and/or groups permission to use the application.
3. Configure the authentication settings in the identity provider application using the information provided below.

SAML Authentication Settings

• Entity ID: https://<yourSSHepherdC3Server>/saml/metadata
• Single Signon (SSO) URL: https://<yourSSHepherdC3Server>/saml/acs
• Name ID Format: EmailAddress (recommended)
• Logout URL: https://<yourSSHepherdC3Server>/saml/sls

Make a note of the following information from your Identity Provider. This is needed to configure the SAML settings in the SSHepherd® Admin Console and complete the integration in Step 3:

• Entity ID
• Login URL
• Logout URL
• Certificate (base64 format)

OIDC Authentication Settings

• Redirect URI: https://<yourSSHepherdC3Server>/oidc/cb
• Set claim type to token

Make a note of the following information from your Identity Provider. This is needed to configure the OIDC settings in the SSHepherd® Admin Console and complete the integration in Step 3:

• Provider URL
• Client ID
• Client Secret

Step 3: Configure SSHepherd® to use 3rd Party Authentication

1. Sign in to the SSHepherd Admin Console (https://<yourSSHepherdC3Server>) using the local admin account created during the SSHepherd® C3 server installation process.
2. Click on the “Settings” tab.
3. Select the tab for the authentication mode you want to use and enter the configuration settings you noted in Step 2.
4. Select the configured authentication mode in the “Active Authentication Mode” dropdown.

SAML Authentication Settings

OIDC Authentication Settings

• Provider URL: The URL provided by the identity provider.
• Client Id: The client id provided by the identity provider.
• Client Secret: The client secret provided by the identity provider.

Active Directory Authentication Settings

• Domain Controller: Either the FQDN or IP address of your domain controller.
• Bind User: Domain user that has enough access to enumerate users and groups.
• Bind Password: Password for the Bind User.

Step 4: Assign “Admin” role to account(s)

Allow time for the initial provisioning cycle to complete (if using AD, the C3 will do this itself, if using SAML/OIDC you will need to utilize SCIM provisioning, see below). If using SCIM provisioning, you can check the provisioning status in the Identity Provider’s portal.

Once the initial provisioning cycle is complete, assign the Admin role to any of your newly provisioned user accounts.

1. In the SSHepherd C3 Admin Console, select the Roles tab.
2. Select the “admin” role.
3. Click the ‘Include users’ button in the bottom pane, and select the user account(s) from the list of provisioned accounts to include in the admin role.
4. Click the ‘Include’ button to apply.

IMPORTANT: If you find you are unable to login after configuring SSHepherd to use your 3rd party identity provider, add /#/signin?auth=standard to the end of your SSHepherd C3 server URL. This will allow you to bypass the configured authentication and login to the C3 server directly, using your local SSHepherd administrator account.
Example:
https://<yourSSHepherdC3Server>/#/signin?auth=standard

Optional: Configure SCIM Provisioning

To configure automatic provisioning, you will need to configure settings in the identity provider’s provisioning settings:

Scim Endpoint: https://<yourSSHepherdC3Server>/scim/v2/

Authentication/Secret Token: You will create this key in the SSHepherd Web Console.

1. Login to the SSHepherd C3 Admin Console
2. Click the Keys tab
3. Click the “+” button.
4. Select the “SCIM integration” box, and type a description for the key.
5. Click “Generate Key”.
6. Copy all the green text (which is your key) and save it someplace safe. The key cannot be reviewed or recovered. If lost, you must create a new key.

Appendix A: Configuring SAML Authentication with Microsoft ENTRA

Create and configure an ENTRA Enterprise Application for SSHepherd®.

1. In the ENTRA console, Enterprise Applications, select “Create a new Application”
   • Give the application a name, and select “Integrate any other application you don’t find in the gallery (Non-gallery)”.
   • Click Create.
2. In the ENTRA console, Assign Users and Groups to the Enterprise Application.
3. Configure the Enterprise Application to use SAML authentication
4. In the Entra Enterprise Application Settings, go to Single Sign On, and Select “SAML”.
5. Identifier: https://<yourSSHepherdC3Server>/saml/metadata/
6. Reply URL: https://<yourSSHepherdC3Server>/saml/acs
7. Sign on URL: https://<yourSSHepherdC3Server>/saml/acs
8. Relay State: <leave blank>
9. Logout Url: https://<yourSSHepherdC3Server>/saml/sls
10. Under SAML Certificates, Download the Certificate (Base64)
11. Under “Set up ….”, capture the Login URL, Microsoft Entra Identifier and Logout URL fields (these will go into the Single SignOn Service URL, Single Logout Service URL and x509cert fields respectively in the C3 Web UI).

Set up SCIM provisioning

1. In the SSHepherd Admin Console, create a SCIM authentication token (see above)
2. In the Entra console, go to the Enterprise Application’s Provisioning tab. Select Provisioning Mode: “Automatic”.
3. Under Admin Credentials/Tenant URL, specify the SCIM endpoint:
   https://<yourSSHepherdC3Server>/scim/v2/
4. For the Admin Credentials/Secret Token, Paste the Scim Auth Token from Step 1.
5. Click “Save Changes”.
6. Click “Start Provisioning”.

Appendix B: Configuring OIDC Authentication with Microsoft Entra

Create and configure an ENTRA Enterprise Application for SSHepherd®

1. In the ENTRA console, Enterprise Applications, select “Create a new Application”
   • Give the application a name, and select “Integrate any other application you don’t find in the gallery (Non-gallery)”.
   • Click Create.
2. In the ENTRA console, Assign Users and Groups to the Enterprise Application.
3. In the ENTRA console, go to Applications/App Registrations, and select the Application.
4. Under Authentication, select “Add a Platform”, and add the “Web” platform.
5. Set “Redirect URI” to https://<yourSSHepherdC3Server>/oidc/cb
6. Under Certificates & Secrets, select “New client secret”, and add a new secret (make sure the save the Secret ID and value, you use these in the C3 where Secret ID = Client ID and value = Client Secret).
7. Select “Endpoints” at the top of the page, and select the URL under “OpenID Connect metadata document” and use this in the SSHepherd Admin Console in the Provider URL field.

Set up SCIM provisioning

1. In the SSHepherd Admin Console, create a SCIM authentication token (see above)
2. In the Entra console, go to the Enterprise Application’s Provisioning tab.
   • Select Provisioning Mode: “Automatic”.
3. Under Admin Credentials/Tenant URL, specify the SCIM endpoint:
   • https://<yourSSHepherdC3Server>/scim/v2/
4. For the Admin Credentials/Secret Token, Paste the SCIM authentication token from step 1.
5. Click “Save Changes”
6. Click “Start Provisioning”