The Generic Password Credentials 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 Client Credentials 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 Client Credentials 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 GenericPasswordCredentialsGrantOAuthProvider.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 GenericPasswordCredentialsGrantOAuthProvider 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.ComponentModel;
using System.Collections.Specialized;
using System.Windows.Forms;
using Nemiro.OAuth;
using Neuron.Esb.OAuth;

He then begins to write his code for the provider.

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

[DisplayName("Generic Password Credentials Grant OAuth Provider")]
public class GenericPasswordCredentialsGrantOAuthProvider : 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
• TokenUrl
• Scope
• Username
• Password

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.")]
[PropertyOrder(2)]

For the ClientSecret and Password accessors 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)
{
}

Sam now 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 GenericClientCredentialsGrantOAuth2Client : OAuth2Client

Sam starts his code by creating a couple of class variables as the values will be needed in multiple methods within the class.

public override string ProviderName
{
        get { return "Generic Client Credentials Grant OAuth Provider"; }
}

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

public GenericPasswordCredentialsGrantOAuth2Client(string accessTokenUrl, string clientId, string clientSecret, string username, string password, string scope) : base(accessTokenUrl, accessTokenUrl, clientId, clientSecret)
{
    base.Username = username;
    base.Password = password;
    base.Scope = scope;
    base.SupportRefreshToken = false;
}

Moving into the meat of the code Sam creates a method for the OAuth2Client called GenericAuthCodeGrantOAuth2Client which sets values for the class level variables as well as the base variable of SupportRefreshToken.

protected override void GetAccessToken()
{
    var parameters = new NameValueCollection
    {
        { "grant_type", GrantType.Password },
        { "client_id", base.ApplicationId },
        { "username", base.Username },
        { "password", base.Password }
    };

    if (!String.IsNullOrEmpty(base.ApplicationSecret))
        parameters.Add("client_secret", base.ApplicationSecret);

    if (base.Scope != null)
        parameters.Add("scope", base.Scope);

    var result = OAuthUtility.Post
    (
        endpoint: this.AccessTokenUrl,
        parameters: parameters,
        authorization: new HttpAuthorization(AuthorizationType.Basic, OAuthUtility.ToBase64String("{0}:{1}", this.ApplicationId, this.ApplicationSecret))
    );

    if (result.ContainsKey("error"))
    {
        this.AccessToken = new OAuth2AccessToken(new ErrorResult(result));
    }
    else
    {
        this.AccessToken = new OAuth2AccessToken(result);
    }
}

Sam then overrides the GetAccessToken method in the base class, so that he can insert the values from his class level variables into the parameters collection before sending the authorization request to Generic for the access token.

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 GenericPasswordCredentialsGrantOAuth2Client(tokenUrl, this.clientId, this.clientSecret, this.username, this.password, this.scope);

This code allows Sam to specify 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

bool success = false;

try
{
    var client = this.GetClient();
    var token = client.AccessTokenValue;
    if (!String.IsNullOrEmpty(token))
        success = true;

    if (success)
    {
        MessageBox.Show(mainForm, "Azure Resource Owner Password Credentials OAuth Test Successful", "Success");
        return client.AccessToken;
    }
    else
    {
        MessageBox.Show(mainForm, "Unable to obtain an access token - unknown error", "Test Failed");
        return null;
    }
}
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 client access token class and then uses that to test Sam’s access to Generic.

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.