Skip to content

Configuring SSO

Jump to bottom
Arianna Cooper edited this page Oct 17, 2024 · 6 revisions

SAML in BloodHound

BloodHound supports SAML 2.0 for Single Sign On to authenticate users to your local tenant environment. This walkthrough will be using authentik as the chosen identity provider, as it is included in our docker-compose.dev.yml file to facilitate various authentication flows.

  1. First, run just bh-sso in the terminal in order to spin up the authentik docker services

    just bh-sso

  2. Go to http://authentik.localhost/if/flow/initial-setup/ to register an admin email and password for your authentik server. If you're already registered, sign in as usual instead:

  3. Afterwards, click "Admin interface" on the top right:

  4. Then navigate to the left side bar menu under "Applications" and click "Providers". You will first create a provider object by clicking on either of the blue "Create" buttons:

  5. Choose the "SAML Provider" option and click "Next". You should see these options below:

  6. Make sure to fill out/choose these parameters below (the rest can be left alone), and click "Finish":

    Name: authentik
Authentication flow: default-authentication-flow (Welcome to authentik!)
Authorization flow: default-provider-authorization-explicit-consent (Authorize Application)
ACS URL: http://bloodhound.localhost/api/v2/login/saml/authentik/acs 
Issuer: authentik
Service Provider Binding: Post 
Signing Certificate: authentik Self-signed Certificate

  7. Next, you will proceed to create an Application. Navigate to the left side bar menu under "Applications" and click "Applications". Click on either of the blue "Create" buttons to get started. You should see these options below:

  8. Make sure to fill out/choose these parameters below (the rest can be left alone), and click "Create":

    Name: bhce
Slug: bhce
Provider: authentik 
Launch URL: http://bloodhound.localhost/ui/login
Check mark toggle to: Open in new tab

  9. Now that both the Provider and Application are created, you'll need to download the "Metadata" and "signing certificate" in the "Related objects" section of the page below:

  10. Copy and paste the contents (WITHOUT the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) from your "signing certificate" into the "sp_cert" field of your build.config.json file like below:

    Note: This command will strip the new lines and throw the contents of the file into your clipboard (it makes it a lot easier to paste everything all on one line)

    tr -d '\n' < /path/to/your/signing-certificate-pem-file | pbcopy

  11. The contents of the "sp_key" field come from creating your own private key in the terminal. Use the command below to create it. Once finished, copy and paste like the above (WITH -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----)

    openssl genpkey -out private_key.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048

  12. The last thing you need to do in authentik is create a new user (the one that will be logging into bhce via saml). Navigate to the left side bar menu under "Directory" and click "Users". Click on the blue "Create" button to get started. You should see these options below:

  13. Make sure to fill out/choose these parameters below (the rest can be left alone), and click "Create":

    Username: SomeUserName
User type: Internal
email: [email protected]

  14. Afterwards, click on your newly created user and set the password:

  15. Now it's time to set up the SAML configuration on bhce. Click the gear icon on the top right of the page, and click "Administration". Then navigate to the left side menu under "Authentication" and click "SAML Configuration". Fill in the "SAML Provider Name" with "authentik" and choose the "Metadata" file you downloaded from authentik earlier and click "Submit":

    Notice that the ACS URL is the same as the ACS URL on authentik below:

  16. Just as you created a new user within the authentik side, you must do the same on the bhce side. Navigate to the left side menu under "Users" and click "Manage Users". Make sure that the "Email Address" and "Principal Name" are the exact same ones you have in authentik. Then click "Save":

    Note: Make sure the admin and new user don't have the same email address

  17. Great! Now that everything is set on both ends, log out of bhce and try to login via sso. There should be a new button for it like below:

  18. Then choose the newly created "authentik" SSO Provider and click "Continue":

  19. You should now be redirected to authentik, which will then ask for your consent on signing into bhce.

  20. And once you click "Continue", you will have successfully logged into bhce via SAML SSO!

OICD in Bloodhound

Coming soon!

Clone this wiki locally