BizTalk Server: Step-by-Step Guide For Restoring SSO Master Secret

Article
1/17/2024

Introduction

This is a step-by-step guide for restoring the SSO master secret.

This is a companion article (soon to be released for sysprep) that should be used as a guide for any automation that involves SSO Secret restoration using automation.

I wrote this specifically to overcome a specific gap in the SSOConfig management tool, as it requires human intervention to enter the password.

Prerequisites

You must have a valid SSO Secret backup file.
You must know the secret password that was used to generate the SSO Secret backup file.
The user must be at least a LEVEL 4 user (see Minimum Security Rights for security levels).
You must be able to compile the ssoSecretRestore project using Visual Studio 2013
You must have the same version of Enterprise SSO in your development project as on the BizTalk Server.

Step by Step

Compile the ssoSecretRestore project against your version of Enterprise Single Sign-on.
Gather the secret backup file.
Gather the secret backup password.
Copy the ssoSecretRestore.exe and the Secret Backup file to the same folder.
Stop all host instances.
Confirm the Enterprise Single Sign-on Service is running.
Confirm the SQL Server with the ESSO database is running.
Start an Administrative command prompt.
Change your working directory to the same directory as step #4
run the ssoSecretRestore command.

ssoSecretRestore ssoBackup.bak password

Where ssoBackup.bak is the backup file and password is the secret password.

What could go wrong

If you don't have the SSO Secret file, there is nothing you can do, you must rebuild your environment from scratch.
If you don't have the SSO Secret password, there is nothing you can do, you must rebuild your environment from scratch.
If you compile against the wrong version of the Microsoft.EnterpriseSingleSignOn.Interop.dll, then the program won't run.
If you aren't a member of the SSO Administrators group, you will get an error "Error importing SSO Secret - User is not a member of the SSO Administrators group".
If you don't have permissions to read the SSO Backup file you will get an error "Error importing SSO Secret - Input file error".
If the SSO Backup file doesn't exist (e.g., you typed the name wrong) you will get an error "Error importing SSO Secret - Input file not found".
If you have discovered a creative way to break the software, you will get an error "Error importing SSO Secret - Unexpected Error was encountered".

Source Code

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;
using Microsoft.EnterpriseSingleSignOn.Interop;
using System.IO;
using System.Reflection.Assembly;
using System.Reflection;
using System.Globalization;
namespace ssoSecretRestore
{
    class Program
    {
         
 
        static string  Usage = @"ssoSecretRestore will restore the SSO Secret from a file
ssoSecretRestore filename password
example:
    ssoSecretRestore ssoBackup.bak pass@word1";
        static Dictionary<string, string> errorList = new  Dictionary<string, string>(3);
        static bool  exit = false;
        static byte[] commonSSOInteropToken = { 0x31, 0xbf, 0x38, 0x56, 0xad, 0x36, 0x4e, 0x35 };
        static string  filename, password = null;
        static void  Main(string[] args)
        {
            Console.Title = "SSO Secret Restore";
            Init(args);
 
            if (filename == null)
            {
                exit = true;
                Console.WriteLine("ERROR: Input filename is missing");
            }
            if (password == null)
            {
                exit = true;
                Console.WriteLine("ERROR: password is missing");
            }
            if (!exit)
            {
                ISSOConfigSS iSSO = new  Microsoft.EnterpriseSingleSignOn.Interop.ISSOConfigSS();
                try
                {
                    iSSO.RestoreSecret(filename, password);
                    Console.WriteLine("SSO Secret Restore succesful");
                }
                catch (Exception ex)
                {
                    if (ex.GetType() == typeof(COMException))
                    {
                        WriteException(ex, "COMException");
                    }
                    else if  (ex.GetType() == typeof(FileNotFoundException))
                    {
                        WriteException(ex, "FileNotFoundException");
                    }
                    else if  (ex.GetType() == typeof(UnauthorizedAccessException))
                    {
                        WriteException(ex, "UnauthorizedAccessException");
                    }
                    else
                    {
                        WriteException((Exception)ex, "Unknown");
                    }
                }
            }
            else
            {
                Console.WriteLine(Usage);
            }
        }
 
        private static  void Init(string[] args)
        {
            errorList.Add("COMException", "Error importing SSO Secret - Input file error");
            errorList.Add("FileNotFoundException", "Error importing SSO Secret - Input file not found");
            errorList.Add("UnauthorizedAccessException", "Error importing SSO Secret - User is not a member of the SSO Administrators group");
            filename = args.Length > 0 ? args[0] : null;
            password = args.Length > 1 ? args[1] : null;
        }
 
        private static  void WriteException(Exception exception,  string  ExceptionType)
        {
            Console.WriteLine("=================================================");
            if (errorList.ContainsKey(ExceptionType))
            { 
                Console.WriteLine(errorList[ExceptionType]); 
            }
            else
            {
                Console.WriteLine("Error importing SSO Secret - Unexpected Error was encountered");
            }
            Console.Write("Exception Message: " + exception.Message);
            Console.Write("Exception Stack: " + exception.StackTrace);
            if (exception.InnerException != null)
            {
                Console.WriteLine("Inner Exception Message: " + exception.InnerException.Message);
                Console.WriteLine("Inner Exception Stack: " + exception.InnerException.StackTrace);
            }
        }
    }
}

Share via