Skip to content

Configuring SSO

Jump to bottom
Arianna Cooper edited this page Nov 14, 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. 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. Note: Initial bootstrapping of authentik may take some time.

    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. If you have multiple SSO providers, choose the newly created "authentik" SSO Provider and click "Continue":

  20. You should now be redirected to authentik, which will then ask for your credentials and consent to sign into bhce.

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

OIDC in BloodHound

BloodHound now supports OpenID Connect (OIDC) for Single Sign-On to authenticate users to your local tenant environment! This walkthrough will also 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 OIDC 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. Note: Initial bootstrapping of authentik may take some time.

    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 "OAuth2/OpenID 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-oidc (any alphanumeric name with spaces is supported)
Authentication flow: default-authentication-flow (Welcome to authentik!)
Authorization flow: default-provider-authorization-explicit-consent (Authorize Application)
Client type: Public
Redirect URIs/Origins(RegEx): http://bloodhound.localhost/api/v2/sso/authentik-oidc/callback

  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-authentik (any alphanumeric name with spaces is supported)
Slug: bhce-oidc
Provider: authentik-oidc
Launch URL: http://bloodhound.localhost/ui/login
Check mark toggle to: Open in new tab

  9. The last thing you need to do in authentik is create a new user (the one that will be logging into bhce via OIDC). 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:

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

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

  12. Now it's time to set up the OIDC 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 "SSO Configuration". Fill in the "OIDC Provider Name" with "authentik oidc". The "Client ID" and "Issuer" contents must be copied and pasted from authentik. Once all that information is filled in, click "Submit":

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

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

  15. If you multiple SSO Providers, choose the newly created "authentik oidc" SSO Provider and click "Continue":

  16. You should now be redirected to authentik, which will then ask for your credentials and consent to sign into bhce.

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

Clone this wiki locally