The Generic Code Grant OAuth Provider Sample will show you how to setup a custom OAuth provider for Generic for use in conjunction with Neuron ESB.

Note: It Is recommended that you already be familiar with both Neuron ESB and the Visual Studio before starting this tutorial. You will also need to ensure that both the Visual Studio and Neuron ESB are installed in your environment and configured appropriately.

This sample contains the following artifacts:

• Visual Studio Project
• Sample Documentation

While the Visual Studio project is already created for you, in order to execute this sample, you will have to follow along with Sam, and do as he does as he creates a custom OAuth provider.

Overview

There are times when it is necessary to implement custom OAuth providers in order to connect to third party applications such as Generic. While Neuron ESB allows you to import these custom OAuth providers, and use them to facilitate your connections with these applications, they need to be constructed in such a way that Neuron ESB can use. This sample will walk you through constructing a custom OAuth provider and show you how to import it for use into Neuron ESB.

Scenario

Sam Pleuser is hard at work, getting his companies third party applications integrated with their new Neuron ESB platform, when he realizes that he will need to connect to Generic using OAuth to facilitate the transfer of certain data. Not only does he need to connect to Generic, but he needs to do so using Code Grant, which is going to require him to build a custom OAuth provider.

Sam lists out his tasks so that he knows when he has to do in order to achieve his goals, and the order in which he needs to accomplish them.

• Create a custom OAuth provider for Generic using Code Grant
• Register the custom OAuth provider with Neuron ESB for use in conjunction with service connectors.

Now that he has an idea of what he needs to do Sam can begin the process.

First Sam opens up his instance of Visual Studio and creates a new class library project. Custom OAuth providers need to be built as class libraries for Neuron ESB to be able to consume them and use them in the Neuron ESB Explorer.

Sam knows that he is going to be integrating with Neuron ESB 3.7.5 and as such will need to ensure that his project is set to compile against .NET Framework 4.7.2. So he selects that as his target frame work when creating his project.

Once the project has been created Sam opens the solution explorer and renames the Class1.cs file to match the name of provider and OAuth type which he is creating. In this case he names the file GenericAuthCodeGrantOAuthProvider.cs

With the file named appropriately Sam now needs to make sure that he has references to the DLLs that he will need in order to complete his task.

As Neuron ESB utilizes the Nemiro.OAuth and Nemiro.OAuth.LoginForms libraries in its implementation of OAuth providers, Sam will need to reference these libraries when creating his own OAuth provider.  These libraries are shipped with Neuron ESB, so he can reference these libraries either by direct reference to the files in the Neuron installation folder or by adding them via NuGet in Visual Studio.

If Sam wants to reference the libraries directly, he simply needs to add references to these files:

• <Neuron Install Location>\<Instance>\Nemiro.OAuth.dll
• <Neuron Install Location>\<Instance>\Nemiro.OAuth.LoginForms.dll

If he decides to add them to his solution via NuGet, then he needs to add these libraries:

• Nemiro.OAuth
• Nemiro.OAuth.LoginForms

Sam also needs to make sure that he references the Neuron.Esb dll

• <Neuron Install Location>\<Instance>\Neuron.Esb.dll

As well as System.Windows.Forms.

With the proper references in place Sam opens the GenericAuthCodeGrantOAuthProvider class by double clicking it in the Solution Explorer so that he can begin to add his code. To begin Sam starts by adding a necessary using statements to his class.

using System;
using System.Text;
using System.Windows.Forms;
using System.ComponentModel;
using System.Collections.Specialized; 
using Neuron.Esb;
using Neuron.Esb.OAuth;
using Nemiro.OAuth;
using Nemiro.OAuth.LoginForms;

He then begins to write his code for the provider.

Same starts with adding a display name attribute to his GenericAuthCodeGrantOAuthProvider class, as this will provide a friendly name by which to recognize the provider in the Neuron ESB Explorer.

[DisplayName("Generic Authorization Code Grant OAuth Provider")]
public class GenericAuthCodeGrantOAuthProvider : OAuthProvider
{
}

Next Sam develops the accessors for the different settings that he will need in order to interact with Generic. He knows that he needs the following properties exposed in Neuron ESB so that he can add the appropriate information, and creates accessors for each.

• ClientId
• ClientSecret
• AuthorizationUrl
• TokenUrl
• RedirectUri
• scope

When creating the accessors Sam makes sure the decorate all of them with a DisplayName attribute, so that he can identify the accessor in the Neuron ESB Explorer, a Description attribute so that he can inform others of the purpose of the accessor and a PropertyOrder attribute so that the Neuron ESB Explorer lists them attribute in the order he envisions.

[DisplayName("Client ID")]
[Description("The Application Id assigned to your app when you registered it with Generic AD.")]
[PropertyOrder(2)]

For the ClientSecret accessor Sam also adds some additional attributes in order to obfuscate the values that are entered in their inside the Neuron ESB Explorer.

[PasswordPropertyText(true)]
[EncryptValue]

Sam knows that he will need to implement two different methods in this class, but that they will rely on other classes and methods, so he stubs them out for now and will be revisiting them once he has developed his other code.

public override OAuthBase GetClient()
{
}
public override AccessToken ClientLogin(Form mainForm)
{
}

The first class that Sam needs to construct is a class which inherits Nemiro.OAuth.OAuth2Client. This class will handle all of the interaction between Neuron ESB and the OAuth provider.  Because Sam is going to be using Generic Active Directory which has a requirement for a resource parameter, he will need to override the base class. 

Sam develops the following code in order to ingrate with Generic.

public class GenericAuthCodeGrantOAuth2Client : OAuth2Client
    {
        public override string ProviderName
        {
            get { return "Generic Authorization Code Grant OAuth Provider"; }
        }

Sam then creates an accessor for the ProviderName which will return a formatted and friendly name.

public GenericAuthCodeGrantOAuth2Client(string authUri, string tokenUri, string redirectUri, string clientId, string clientSecret, string scope)
            : base(authUri, tokenUri, clientId, clientSecret)
        {
            base.ReturnUrl = redirectUri;
            base.SupportRefreshToken = true;
            base.Scope = scope;
        }

With that class complete, Sam moves on to another class, GenericAuthCodeGrantLogin, which inherits from the Login class in Nemiro.

public class GenericAuthCodeGrantLogin : Login
    {
        public GenericAuthCodeGrantLogin(OAuthBase client) :
            base(client, responseType: "code")
        {
        }
    }

This class only contains a single method and is used solely to specify the responseType as being code, since Sam wants to use Code Grant for this OAuth provider.

With his setup complete Sam next returns to the GenericAuthCodeGrantOAuthProvider class to fill in the two methods that he previously stubbed out.

He starts with the GetClient class, adding the following code

return new GenericAuthCodeGrantOAuth2Client(this.authorizationUrl, this.tokenUrl, this.redirectUri, this.clientId, this.clientSecret, this.scope);

This code allows Sam to use the authorize and access token URLs before creating a new instance of the GenericAuthCodeGrantOAuth2Client class.

Sam then fills out the ClientLogin method with the following code

GenericAuthCodeGrantLogin login = null;

            try
            {
                var client = this.GetClient();
                login = new GenericAuthCodeGrantLogin(client);

                using (login)
                {
                    login.ShowDialog(mainForm);
                    if (login.IsSuccessfully)
                    {
                        return client.AccessToken;
                    }
                    else
                    {
                        MessageBox.Show(mainForm, String.Format("Unable to obtain an access token - {0}", login.ErrorMessage), "Test Failed");
                    }
                }
            }
            catch (Exception ex)
            {
                MessageBox.Show(mainForm, String.Format("Unable to obtain an access token - {0}", ex.Message), "Test Failed");
            }

            return null;

This method creates an instance of the GenericAuthCodeGrantLogin class and then uses that to test Sam’s access to Generic using his OAuth access token.

Once Sam has finished writing his code, he compiles the project to create the project DLL in the bin directory, which he then copies over to his Neuron ESB instance

• <Neuron Install Location>\<Instance>\OAuthProviders

Doing this will allow Sam to open the Neuron ESB Explorer and leverage his new custom OAuth provider in Security > OAuth section of the Explorer.