Skip to main content

Setting Up SSO SAML 2.0 With Keycloak

info

SAML-based authentication is only available on Enterprise plans (both self-hosted and on SigNoz Cloud).

Overview​

Keycloak is an open-source identity and access management tool which makes it easy to add authentication to applications and secure with minimum effort.

In enterprise plan of SigNoz, you can enforce Single Sign-On (SSO) using SAML 2.0. Keycloak can be used as a user directory to save user data while acting as the identity provider (IdP) for the SSO.

Prerequisites​

  • SigNoz application up and running
  • Helm version 3.8 or above
  • SigNoz helm chart version 0.4.3 or above
  • Enterprise plan of SigNoz
  • Set up cert-manager and Nginx ingress controller
  • SigNoz Frontend ingress with TLS
info

If you have not set up cert-manager, Nginx ingress controller, or have Signoz with TLS, you can follow the guide here to set it up.

Set up Single Sign-On using SAML​

For this tutorial, you will be required to have Keycloak up and running.

It is assumed that you have set up Keycloak or any other identity and access management tool with SSL/TLS certificates.

In case you do not have Keycloak set up and want to install Keycloak using SigNoz chart, you can follow the instructions in this section before proceeding further.

Steps to Set Up SAML​

Let's assume https://signoz.domain.com as the endpoint where SigNoz is publicly accessible whereas https://signoz-keycloak.domain.com being the secured endpoint of Keycloak.

  1. Go to the Keycloak Admin console UI and sign in as an administrator

    Admin login page

  2. Create a new realm: SigNoz

    Create SigNoz realm

  3. Create new client of type SAML with client ID same as that of secured SigNoz endpoint: signoz.domain.com

    Create client page

  4. Update Access settings configurations

    • Set Home URL to https://signoz.domain.com/api/v1/complete/saml
    • Set Valid redirect URIs to https://signoz.domain.com/*

    Client access settings

  5. Go to Clients > Client scopes, and select signoz.domain.com-dedicated and add predefined mappers in SigNoz client: role list, X500 email, and X500 given name

    Predefined mappers

  6. In SAML capabilities section, select email for Name ID format

    SAML capabilities email id

  7. Go to Clients > Keys, and turn off the Client signature required option from signing keys config

    Client signature required

  8. Create new user which is to be used for login. Be sure to include email id in username and email fields

    Create new user

  9. Make sure to create credentials for the created user and turn off the temporary toggle

    New user credentials

  10. Go to Realm settings > General, open SAML 2.0 Identity Provider Metadata endpoint

    SAML 2.0 identity provider metadata

    From the XML file, make note of the followings:

  • SAML location URL with the /protocol/saml suffix which is SAML ACS URL
  • SAML entity id
  • SAML X.509 certificate

  1. In SigNoz UI, go to Settings > Organization Settings > Authenticated Domains

    Add an authenticated domains which will be the domain of the user email; in case of [email protected], it will be domain.com.

    Add authenticated domain

  2. SAML configurations from Step 10 is set in SigNoz and enable the Enforce SSO toggle

    SigNoz SAML configuration

  3. Open your browser with incognito (or private) mode, and open your SigNoz URL and click Login followed by SSO Login

    SSO Login

  4. You will be redirected to Keycloak user login page, enter Keycloak user credentials from Step 8 and Step 9

    Keycloak user login

Now, you should be logged in to SigNoz using Keycloak SSO.

(Optional) Install Keycloak using SigNoz Helm Chart​

You can install the Keycloak using SigNoz helm chart. We can set custom namespace, admin console credentials, postgres admin and user credentials, and ingress related configurations.

Let's include them in existing override-values.yaml:

keycloak:
  enabled: true

  auth:
    adminUser: admin
    adminPassword: adminpass123

  postgresql:
    auth:
      postgresPassword: pgadminpass123
      username: bn_keycloak
      password: bn_keycloak123

  ingress:
    enabled: true
    ingressClassName: nginx
    pathType: ImplementationSpecific
    path: /
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hostname: signoz-keycloak.domain.com
    servicePort: http

    tls: true
    selfSigned: false
info

You will need to replace domain.com with company domain or something relevant.

Make sure that you have Nginx ingress controller and Cert-manager installed and you have a ClusterIssuer named letsencrypt-prod. You can follow the instructions from the guide here.

To install or upgrade SigNoz release with the updated configurations in override-values.yaml:

helm -n platform upgrade \
    --create-namespace --install \
    my-release signoz/signoz \
    -f override-values.yaml

You should be able to access Keycloak UI using the domain name in ingress.hostname.