Open sourcing our identity provider for Healthcare Bluebook (SAML) single sign on

Piotr S.

Open Source Software AppStream Studio Healthcare Bluebook SAML SSO

TLDR

In a recent HealthTech engagement, we had the task of integrating Healthcare Bluebook's Single Sign-On (SSO) into a client's product. As a byproduct, we developed the AppStream.HealthcareBluebook open-source library, making SSO integration in .NET Core applications easy. Now, you don't have to build it from scratch yourself.

Before you begin

To get started with the AppStream.HealthcareBluebook library, you'll need to directly engage with Healthcare Bluebook and register your application as an Identity Provider in their system. When reaching out, you'll be asked to provide essential values such as the Issuer value for the <Assertion> tag, the intended Audience for the Assertion, and the X509 Certificate – the public key of your code signing certificate used to sign the SAMLResponse. In return, Healthcare Bluebook will furnish you with a clientid, serving as a unique identifier for your application within their system. You'll use these values to fill in the configuration in the appsettings.json file.

You'll also decide on how the memberid value is constructed which will be used to identify your app's users.

Getting started

Installation

Kickstart your integration journey by installing the AppStream.HealthcareBluebook NuGet package. Run the following command in your .NET Core web application:

dotnet add package AppStream.HealthcareBluebook

Configuration

Configure the library in your web application's startup code. Depending on your certificate storage preference, choose one of the following options:

If your signing certificate is in a file on your machine:

builder.Services 
    .AddHealthcareBluebook() 
    .WithCertFileCertificateProvider();

If your signing certificate is in Azure Key Vault:

builder.Services 
    .AddHealthcareBluebook() 
    .WithAzureKeyVaultCertificateProvider();

If your signing certificate is installed in the Windows Certificate Store:

builder.Services 
    .AddHealthcareBluebook() 
    .WithWindowsStoreCertificateProvider();

Or create and use your own implementation of ISigningCertificateProvider:

builder.Services 
    .AddHealthcareBluebook() 
    .WithCertificateProvider<YourSigningCertificateProvider>();

App Settings

Configure your app settings in your appsettings.json or equivalent configuration file:

{ 
  "HcbbSaml": { 
    "Audience": ">> HCBB audience <<", 
    "ClientIdAttributeName": "clientid", 
    "ClientIdAttributeValue": ">> your client id <<", 
    "Issuer": ">> your saml 'issuer' value <<", 
    "MemberIdAttributeName": "memberid", 
    "SignatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", 
    "SingleSignOnDestination": "url to HCBB SSO" 
  }, 
  "AzureKeyVault": { // needed only when using AzureKeyVaultSigningCertificateProvider 
    "CertificateName": ">> name of the cert in the key vault <<", 
    "KeyVaultUrl": ">> url to your key vault <<" 
  }, 
  "CertFile": { // needed only when using CertFileSigningCertificateProvider 
    "FileName": "cert file name", 
    "Password": "cert password" 
  },
  "WindowsCertificateStore": { // needed only when using WindowsStoreSigningCertificateProvider
    "StoreName": "Me",
    "StoreLocation": "LocalMachine",
    "FindType": "FindByThumbprint",
    "FindValue": "cert thumbprint"

Integration

Inject IHcbbSamlResponseGenerator into your controller and return the SAML response to the browser:

public class HomeController : Controller 
{  
    private readonly IHcbbSamlResponseGenerator _hcbbSamlResponseGenerator; 

    public HomeController(IHcbbSamlResponseGenerator hcbbSamlResponseGenerator) 
    { 
        _hcbbSamlResponseGenerator = hcbbSamlResponseGenerator; 
    } 

    public IActionResult GoToHcbb() 
    { 
        return _hcbbSamlResponseGenerator 
            .GenerateHcbbSamlResponse("insert member id here"