Single Sign On | Honeycommb Help Center

Single Sign-On (SSO) enables your users to authenticate with our application via your identity provider. When enabled, all other forms of authentication are disabled. Honeycommb supports SAML 2.0, OAuth 2, and JWT.

You can only enable one method of SSO at a time. Configuration for both can be reached from the community details page.

Accessing Single Sign On for your network

Single Sign On setup is currently available in Control Center 1.0. You can access your network SSO settings via Control Center 2.0 by going to Control Center > Integrations > Single Sign On and clicking the "Access in Control Center 1.0" button.

This will log you into Control Center 1.0 > Single Sign On where you can follow the steps below to activate SSO via one of our three supported protocols.

If you receive an error when trying to access Control Center 1.0, this means that you're trying to login using an account other than the network creator/owner account. Please reach out to [email protected] to create an account that can access Control Center 1.0 as it is a separate login.

SAML 2.0

These are the steps to enable SAML 2.0 as your SSO protocol

Step 1: Setup Protocol

Select SAML as the protocol. Use the ACS url and SP entity to plug into your identity provider.

We require that the name ID be returned as an email address.

We also require the following attributes:

first_name should be the first name of the user.
last_name should be the last name of the user.

Failure to map these fields will result in failed SAML auth requests.

Step 2: Fill in the IDP Entity Name

The IDP Entity name is the name of the identity provider. It should be recognizable to the end user so they know what system they're about to sign into.

Step 3a: Fill in IDP Metadata

If your provider gives you the xml metadata, simply copy paste it into the Idp Metadata field. You can skip step 3b.

If you do not have the xml metadata, proceed to step 3b.

Step 3b: Fill Details Manually

Fill in the following fields: IDP Entity, IDP SSO Target Url, IDP SLO Target Url, IDP Cert, IDP Cert Fingerprint, IDP Cert Fingerprint Algorithm. You can get these from your identity provider.

Step 4: Activate

Check the "Active" box and save. SSO via SAML will now be enabled.

OAuth2

These are the steps to enable OAuth2 as your SSO protocol

Step1: Setup Protocol

Select Oauth2 as the protocol. Use the Callback URL to plug into the identity provider.

Step 2: Setup Details

*All fields are required except the name mapping.

Provider - The name of the identity provider. It should be recognizable to the end user so they know what system they're about to sign into.
Client ID - Retrieve this from the OAuth application.
Client Secret - Retrieve this from the OAuth application.
Scope - Any additional scopes required to authenticate. See https://oauth.net/2/scope/ for additional details.
Authorization URL - The sign in url for your users. (See github example)
Token URL - The url to fetch the bearer token from. (See github example)
User URL - The url to fetch the current user from. (See github example)

Step 3: Setup Mapping

The mapping fields describe how to traverse the json response from the User URL to retrieve specific fields. We use dot notation to traverse JSON objects.

In our example, the user URL responds with the following payload:

{
    "id": 123,
    "user": {
    "email": "[email protected]",
    "username": "test_user",
    "name": "Test User"
  }
}

Email mapping would be user.email

Username mapping would be user.username

Name mapping would be user.name

Step 4: Activate

Check the "Active" box and save. SSO via OAuth2 will now be enabled.

JWT

These are the steps to enable JWT as your SSO protocol, often used when "embedding" your Honeycommb network into your mobile application using an in-app browser.

Step 1: Setup Protocol

Select JWT as the protocol and fill in the following:

Jwt Provider - The name of the provider (used to print "Login with [Jwt Provider]")

Jwt Provider URL - The URL where users sign in. The user is redirected here if they need to sign in.

Step 2: Copy the JWT Signing Key

The signing key is available after hitting save. Keep this key secret as it will be used to sign the JWT.

Step 3: Create the JWT

On your server, you will need to create a JWT with the following payload structure:

{
  external_id: "your stable identifier for the user",
  email: "[email protected]", 
  username: "user123",
  name: "First Last",
}

external_id - Required. An identifier that does not change over time.
email - Required. A unique email address for the user.
username - Required. A unique username used in Honeycommb.
name - Required. A name used for display purposes in Honeycommb.

Example in Ruby

token = JWT.encode(
  {
      external_id: '123',
      email: '[email protected]',
      username: 'username123',
      name: 'John Doe'
  },
    SIGNING_KEY

)

Step 4: Send user to the JWT consume url

Send the user to https://[your_community].honeycommb.com/jwt/consume?jwt=[token] which will then authenticate the user and forward them to the home feed.