Setting Up Single Sign-On (SSO)¶

In order for users to be able to use a Single Sign-On (SSO) provider to authenticate to the server with their client, you will need to enable your SSO provider and configure it using the Config page of the admin interface.

Currently supported interfaces for Single Sign-On (SSO) within the Enterprise server are OAuth2, OpenID Connect (OIDC), LDAP, and SAML2.

Note

SSO is currently available for clients only. You cannot use SSO to log into the server's admin interface at this time.

OAuth2 and OpenID Connect (OIDC)¶

We provide explicit support for the following OAuth2 providers (see links below for additional information on how to configure your specific provider):

Azure Active Directory OAuth2 (more information here)
GitHub OAuth2 (more information here)
GitHub Enterprise OAuth2 (more information here)
GitLab OAuth2 (more information here)
Google OAuth2 (more information here)
Okta OAuth 2 (more information here)
Slack OAuth2 V2 (more information here)

...in addition to support for custom providers:

Custom OAuth2
Custom OpenID Connect

These options are listed at the bottom of the Config page of the admin interface. Once your SSO provider has been enabled, all clients should have an additional drop-down box available while logging in that they can use to switch to authenticating with that provider.

Redirect URIs¶

When you set up an OAuth2 or OIDC provider, it will need to know what the correct "redirect URI" is for the Enterprise server. This is the URL of the endpoint in the Enterprise server that a user will be redirected to after a successful login. See the following for what this URL should be, depending on your provider:

Azure Active Directory: https://your.host.here:3535/complete/azuread-oauth2/
GitHub: https://your.host.here:3535/complete/github/
GitHub Enterprise: https://your.host.here:3535/complete/github-enterprise/
GitLab: https://your.host.here:3535/complete/gitlab/
Google: https://your.host.here:3535/complete/google-oauth2/
Okta: https://your.host.here:3535/complete/okta-oauth2/
Slack: https://your.host.here:3535/complete/slack/
Custom OAuth2: https://your.host.here:3535/complete/custom-oauth2/
Custom OpenID Connect: https://your.host.here:3535/complete/custom-oidc/

Warning

Please also make sure to change the :3535 above to your custom port number if you've changed it from the default.

Troubleshooting¶

How It Works¶

A lengthy explanation of how OAuth2 and OpenID Connect (OIDC) authentication works can be found here. But, a more brief explanation is as follows:

The client contacts the Enterprise server to get a list of authentication methods
The client selects the SSO method that you have configured above
The client attempts to log in with that SSO method, causing a browser to open locally to the configured SSO login page
The user logs into the SSO provider on that page
The SSO provider authenticates the user
The SSO provider tells the user's browser to redirect to the "redirect URI" (see above) and includes the authentication token in this request
The user's browser navigates to the "redirect URI", providing the authentication token to the Enterprise server
The user is authenticated to the Enterprise server
The client receives the authentication message from the Enterprise server and is logged in

Common Problems¶

Most, but not all, of the issues our Enterprise users have had when setting up SSO have occurred in steps 6 and 7. Common problems include:

You have provided the wrong redirect URI to your SSO provider (see list above for what the correct one should be)
DNS entries do not exist, or do not point to what they are expected, for either the SSO provider or the Enterprise server on the client
The "application" or "service" you set up in your SSO provider is limited to certain users (in GitLab, for example, you probably do not want a "User-Owned Application" because that will only authenticate your single user - use a "Group-Owned Application" or "Instance-Owned Application" instead)
Your custom SSO provider deviates from the OAuth2 or OIDC specifications in a way that the Enterprise server cannot understand
- If, after authenticating, your username is a totally messed up string that looks like a hash, this may be because the "claim" we are expecting to contain your username either isn't being reported or is reporting incorrect data

LDAP¶

Note

The Enterprise server currently only supports user authentication through LDAP. We do not support synchronizing group membership through LDAP at this time, but may do so in the future.

LDAP configuration is pretty straightforward. On the Config page of the admin interface, click to show the LDAP options. You'll need to check the box next to LDAP_AUTH_ENABLED and then fill in the following settings:

LDAP_AUTH_URL - This is the URL and port of your LDAP server (typically ldap://<YOUR_LDAP_HOST>:389).
LDAP_AUTH_USE_TLS - Check this box if your LDAP server uses TLS to encrypt connections.
LDAP_AUTH_SEARCH_BASE - Enter the search base for your LDAP user queries here.
LDAP_AUTH_SEARCH_GROUP - (Optional) This can be used to lock authentication to a specific group. Leave this blank if you don't need this functionality.
LDAP_AUTH_OBJECT_CLASS - This specifies the LDAP class that represents a user. We default to InetOrgPerson as specified in RFC 2798.
LDAP_AUTH_FORMAT_USERNAME - Change this drop-down menu to match the username format the Enterprise server should expect from your LDAP server. We default to OpenLDAP, but also provide options for Active Directory.
LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN - This should contain the login domain for Active Directory users, if you are using Active Directory.
LDAP_AUTH_CONNECTION_USERNAME - This is the username the Enterprise server should use for its connection to the LDAP server.
LDAP_AUTH_CONNECTION_PASSWORD - This is the password the Enterprise server should use for its connection to the LDAP server.
LDAP_AUTH_USER_FIELDS - This is a JSON blob that specifies which user fields in Enterprise should map to LDAP attributes retrived from them LDAP server. We require username, first_name, last_name, and email to be present. The Enterprise server values are the keys for this mapping and the LDAP attributes are the values.

SAML2¶

Note

SAML2 support is only available as a paid add-on to your Enterprise server license.

Enterprise will only present the option to configure SAML2 on the Config page of the admin interface if your server is appropriately licensed. You will need to make sure the license.dat file that is being loaded by your Enterprise server also contains your SAML2 license (the product label should read "Enterprise Server SAML2 Support"). The license.dat file is a JSON blob, so its contents should look something like this (it may be minified):

[{
    "product": "Binary Ninja Enterprise Server",
    <...>
},
{
    "product": "Enterprise Server SAML2 Support",
    <...>
}]

If it does not, but you have both license files available, you can combine them manually by copying the missing license into the JSON array. (Since this file is a JSON blob, you can't simply cat the two files together.)

Once the Enterprise server has been licensed properly, the rest of the SAML2 configuration takes place in 2 steps:

Configuring the SP (the Enterprise server) to talk to the IdP. This is covered in the "Service Provider Configuration" section below.
Configuring the IdP to talk to the SP. This is covered in the "Identity Provider Configuration" section below.

Service Provider (SP) Configuration¶

Note

In order for an Identity Provider (IdP) to be compatible with the Enterprise server, it must support HTTP-Redirect binding.

To configure the Enterprise server to work with a SAML2 Identity Provider (IdP), you will need to:

Enable SAML2 in the Enterprise Server settings (Config > Custom SAML2 > Enabled)
Update the required SAML2 settings on the Enterprise Server:
- SOCIAL_AUTH_CUSTOM_SAML2_SP_ENTITY_ID
- SOCIAL_AUTH_CUSTOM_SAML2_SP_PUBLIC_CERT
- SOCIAL_AUTH_CUSTOM_SAML2_SP_PRIVATE_KEY
- SOCIAL_AUTH_CUSTOM_SAML2_ENABLED_IDPS
(Optional) Update the optional SAML2 settings on the Enterprise Server
Export the Service Provider (SP) metadata from the Enterprise Server
Import the Enterprise Server (the "client", or SP) to your IdP
Disable "Require Client Signatures" (or the equivalent setting) in your IdP
Set the "Single Role Attribute" (or equivalent setting) in your IdP

Entity ID¶

The "Entity ID" (SOCIAL_AUTH_CUSTOM_SAML2_SP_ENTITY_ID) is a globally-unique name for a SAML2 identity that is used to identify the Service Provider (in this case, the Enterprise server). Your Entity ID is a name, in the form of a valid Universal Resource Identifier (URI), and does not need to (but may) be a resolvable web location. The Entity ID you select should:

Be a valid URI (a resolvable URL that matches the domain name you are hosting from is highly recommended)
Not contain a port number, query string, or fragment identifier
Not end with a slash (/)
Not be more than 1024 characters in length (something 30 or less is recommended)

It is also recommended (for your own sanity) that the Entity ID contains the substring "sp", since the Enterprise server will be an SP and not an IdP. An example Entity ID would be something like https://<YOUR_SERVER_HOST>/sp.

Certificate¶

Your SAML2 Service Provider (the Enterprise server) will require a valid X.509 certificate. This data needs to be copied and pasted into the SOCIAL_AUTH_CUSTOM_SAML2_SP_PUBLIC_CERT and SOCIAL_AUTH_CUSTOM_SAML2_SP_PRIVATE_KEY config options. If you do not have a certificate or key for the server, you can generate one with OpenSSL like:

openssl req -new -x509 -nodes -out enterprise-saml2.crt -keyout enterprise-saml2.key

Identity Provider(s)¶

The SOCIAL_AUTH_CUSTOM_SAML2_ENABLED_IDPS config option needs to contain each Identity Provider (IdP) you would like the Enterprise server to authenticate with. You will need to provide the following information for each IdP:

Entity ID: This is the Entity ID for the IdP (usually something like https://<YOUR_IDP_HOST>/idp)
URL: This is the redirect URL of the IdP. For a Keycloak IdP, this would probably be something like https://<YOUR_IDP_HOST>/realms/master/protocol/saml. This URL must support the HTTP-Redirect binding.
Certificate: This is the IdP's public X.509 certificate, which the Enterprise server needs for verification.
Attribute URNs: These are the Uniform Resource Names (URNs) for each attribute the Enterprise server will pull from the IdP. The default values filled in for you are the directory services URNs that should map most closely to what the Enterprise server expects. These are almost definitely not the values your IdP expects! In a Keycloak IdP, for example, you'll want to create a "Dedicated Scope" for your client (the SP) that contains a "mapping" for each of these values. Keycloak lets you name these whatever you want. Make sure the values you have chosen (or that have been chosen for you by your IdP) are plugged in for these attributes instead of their default values. You will may need to finish this step after completing the IdP configuration section below if you don't already know what these mappings will be.

To add more than one IdP, click the + Add key link below the inner "IDP" box. Then, fill in the new IdP's information as above.

Additional Configuration¶

The Enterprise server also exposes additional information about the organization and the technical and support contacts for the Enterprise server that can be registered with the IdP. This may be useful for (or even required by) your organization. The SOCIAL_AUTH_CUSTOM_SAML2_ORG_INFO key is an array and you can add extra information to be used in different locales. The default en-US locale is required and cannot be removed.

Identity Provider (IdP) Configuration¶

Once you have configured the Enterprise server, you'll need to go back to the entry you created in your IdP and configure it as an SP (or "client"). Please refer to your IdP vendor's documentation for how to do this.

To get the values you will need to fill in on the IdP, we recommend downloading an XML copy of the SP configuration from the Enterprise server. We provide an endpoint to obtain this information in XML format:

wget --no-check-certificate https://<YOUR_SERVER_HOST>/saml-metadata/ -O enterprise-saml2.xml

Some IdP vendors have a mechanism for importing this XML instead of needing to enter configuration manually. In Keycloak, for example, there is an "Import" option on the "Add Client" page where you can upload the XML file and automatically configure most of the required configuration options.

Next, there are two very important options that need to be set:

Disable "Require Client Signatures" (or the equivalent setting)
Set the "Single Role Attribute" (or equivalent setting)

Please consult your IdP vendor's documentation for how to do this. They may not be automatically set properly after the XML import above.

Note

Before you finish, make sure you have set up the appropriate attribute mappings from the SP configuration section above. If you haven't, now is the time to create those mappings and fill the attribute mappings in on the Enterprise server in the Config page.

Troubleshooting¶

The main problem Enterprise server administrators encounter with SAML is not having the attribute IDs match properly. If users are being logged in as weird identifiers for usernames or have incorrect information being filled in, this is a common cause.

If Enterprise client users are unable to log in, check and make sure your redirect URL is correct. Not having the correct redirect URL can lead to a situation where the user will view a page in their browser that never sends the information back to the Enterprise client, leaving the user stuck at a menu that says it is waiting for information from the browser.

Another common reason that clients may not be able to log in is if the Entity ID for the IdP does not match. This will cause the Enterprise server to be unable to authenticate the user because there is no matching identity being provided by the IdP.