Configuring SSO

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. This guide assumes you are setting up SSO for development of BloodHound Community Edition, however, there are elements that can be borrowed from this guide to configure any SAML identity provider in your deployed BloodHound instance.

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" in the "Related objects" section of the page below:

   

10. In order to leverage your SAML IDP you will need to provide BloodHound with a Service Provider (SP) certificate and key. To quickly generate a self-signed certificate and key you can run the following command:

    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
    

11. Copy and paste the contents of your certificate WITHOUT the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines into the "sp_cert" field of your BloodHound configuration file (e.g. build.config.json for local dev):

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

    # For macos
    tr -d '\n' < /path/to/your/cert.pem | pbcopy
    

    

12. Copy and paste the contents of your SP private key into the "sp_key" field of your BloodHound coniguration file. However, you need to include newline characters \n within the content. And ensure you retain the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- header and footer.

13. 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:

    

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

    Username: SomeUserName
    User type: Internal
    email: spam@example1.com
    

    

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

    

16. 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:

    

17. 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

18. 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:

    

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

    

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

    

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

OIDC in BloodHound

Coming soon!