Updating Your Client Authentication Apps

This topic describes the updates that developers must make to their existing custom client authentication applications to make them compatible with the enhanced identity provider that is provided with the September 2024 update of BarTender Cloud.

You should not need to re-create your applications, because when the identity provider was converted from the legacy version to the enhanced version, the ClientId and ClientSecret values for all existing applications were retained. Depending on your implementation, however, you might need to make some small changes to the way that your application requests an access token.

The following sections provide information about this for each client application type and answers to common questions.

ClosedWeb Applications

To better understand how to create a BarTender Cloud-enabled application, refer to C# Web-Based Application Example.

Download the CodeFlow sample web application at the following website:

https://help.seagullscientific.com/BarTenderCloud/Content/Samples/CSharpSampleApplication/CodeFlow.zip

The CodeFlow sample web application is a revised version of the web-based "LibrarianWebApp" application that was previously provided and documented in the BarTender Cloud help system. This legacy application is located at the following website:

https://help.seagullscientific.com/BarTenderCloud/Content/Samples/CSharpSampleApplication/CSharpSampleApp_RequiredFiles.zip

The changes that are made in the CodeFlow sample web application include the following:

  • The scope "user:query" is not supported by the enhanced identity provider and must be removed, as follows (if you include it in the sign-in workflow, an error message will be displayed):

    // Configure the scope.
    options.Scope.Clear();
    options.Scope.Add("openid");
    options.Scope.Add("BarTenderServiceApi");
    options.Scope.Add("user:query");

  • Optionally, you can send a fixed organization domain ID during the sign-in workflow to bypass the organization prompt that the enhanced identity provider usually displays, as follows:

    context.ProtocolMessage.SetParameter("OrganizationDnsName", "myorg1234");

  • The OnRedirectToIdentityProviderForSignOut handler has been changed slightly with a renaming of the query parameter that is used to convey the sign-in redirect location.

ClosedConsole Applications and Services (Password-based)

To better understand how to create a BarTender Cloud-enabled console application or service, refer to C# Password-Based Application Example.

Download the ResourceOwnerPasswordFlow sample console application at the following website:

https://help.seagullscientific.com/BarTenderCloud/Content/Samples/PasswordBasedSampleApplication/PasswordBasedAuthLogon.zip

The ResourceOwnerPasswordFlow sample application is a revised version of the password-based "PasswordBasedAuthLogon" console application that was previously provided and documented in the BarTender Cloud help system. This legacy application is located at the following website:

https://help.seagullscientific.com/BarTenderCloud/Content/Samples/CSharpSampleApplication/CSharpSampleApp_RequiredFiles.zip

The changes that are made in the ResourceOwnerPasswordFlow sample console application include the following:

  • The scope "user:query" is not supported by the enhanced identity provider and must be removed, as follows (if you include it in the sign-in workflow, an error message will be displayed):

    // Configure the scope.
    options.Scope.Clear();
    options.Scope.Add("openid");
    options.Scope.Add("BarTenderServiceApi");
    options.Scope.Add("user:query");

  • Token requests must include the target organization domain ID. This is required because BarTender Cloud now allows an email address to be used with more than one organization.

    For example, retrieve the OpenID discovery document for the target cluster. For the "MyTenant" cluster, this would be an http REST GET request against the following endpoint:

     https://auth.am1.bartendercloud.com/.well-known/openid-configuration

    The returned document will include the following key-value pair: 

    "token_endpoint":
    "https://auth.am1.bartendercloud.com/connect/token",

    A correctly configured REST POST request against this endpoint, with the required OrganizationDnsName query parameter present, will then return an access token for the specified user, such as the following:  

     https://auth.am1.bartendercloud.com/connect/token?OrganizationDnsName=mytenant

ClosedFrequently Asked Questions (FAQs)

This section answers frequently asked questions about how to update your BarTender Cloud-enabled application.

What if I need my password-based application to continue to use the legacy identity provider?

Until your application is updated to work with the enhanced identity provider, do not use the discovery document approach. Instead, hard-code the appropriate URI for your tenant (line 1 in the following code sample) from one of the following, as appropriate for your organization:

  • EMEA region:  "https://bartendercloud-production.eu.auth0.com"

  • Americas/APAC region: "https://bartendercloud-production.us.auth0.com"

Copy
Uri uri = new Uri(“use the appropriate URI from above”);

                            HttpClient client = new HttpClient();
                            client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/x-www-form-urlencoded"));
                            client.BaseAddress = uri;
                            var contentBodyList = new List<KeyValuePair<string, string>>();
                            contentBodyList.Add(new KeyValuePair<string, string>("grant_type", "password"));
                            contentBodyList.Add(new KeyValuePair<string, string>("username", username));
                            contentBodyList.Add(new KeyValuePair<string, string>("password", password));
                            contentBodyList.Add(new KeyValuePair<string, string>("client_id", clientId));
                            contentBodyList.Add(new KeyValuePair<string, string>("client_string", clientSecret));
                            contentBodyList.Add(new KeyValuePair<string, string>("audience", "https://BarTenderCloudServiceApi"));
                            contentBodyList.Add(new KeyValuePair<string, string>("scope", "openid profile user:query offline_access"));

                            var request = new HttpRequestMessage(HttpMethod.Post, "") { 
                            Content = new FormUrlEncodedContent(contentBodyList) 
                            };

                        HttpResponseMessage msg = client.SendAsync(request).Result;

How do I request an access token when using Postman?

In Postman, all the fields that are shown in the following image are required. If your application supports refresh tokens, then "offline_access" would be included with the list of scopes.

How long will my application continue to work if I do not update it to work with the enhanced identity provider?

If you are using the OIDC discovery document approach that is described in the C# Password-Based Application (Legacy) topic, your application will continue to work until the current access token that it is using expires. Depending on when the access token was generated, this could happen in 0 to 30 days.