Show/Hide Toolbars

Therefore Web API Programming Interface 1.0

Therefore Web API > Developers Guide > Basics

Connection and Authentication

Scroll

Non US-ASCII characters in user-names or passwords

 

User-names or passwords containing characters outside the US-ASCII character repertoire will cause interoperability issues between the Web API server and clients, unless both communication partners agree on what character encoding scheme is to be used. Client can inform the Web API server about the character encoding via the Therefore-Auth-Codepage HTTP header passing the code page number of the encoding:

 

Therefore-Auth-Codepage: <code page number>

 

If the Therefore-Auth-Codepage header is not set in the HTTP request, a default code page/encoding will be used on the Web API server for the received user-name and password. The default code page depends on the system language.

 

Here is an example how the Therefore-Auth-Codepage HTTP header looks like in a request:

 

WebAPI.Connection.AuthCodepageSample

 

 

List of code pages accepted by Therefore Web API:

 

Code page number

Name

Display name

.NET Framework support

936

gb2312

Chinese Simplified (GB2312)

✓

1200

utf-16

Unicode

✓

1201

unicodeFFFE

Unicode (Big endian)

✓

1252

Windows-1252

Western European (Windows)

✓

10003

x-mac-korean

Korean (Mac)

✓

10008

x-mac-chinesesimp

Chinese Simplified (Mac)

✓

12000

utf-32

Unicode (UTF-32)

✓

12001

utf-32BE

Unicode (UTF-32 Big endian)

✓

20127

us-ascii

US-ASCII

✓

20936

x-cp20936

Chinese Simplified (GB2312-80)

✓

20949

x-cp20949

Korean Wansung

✓

28591

iso-8859-1

Western European (ISO)

✓

28598

iso-8859-8

Hebrew (ISO-Visual)

✓

38598

iso-8859-8-i

Hebrew (ISO-Logical)

✓

50220

iso-2022-jp

Japanese (JIS)

✓

50221

csISO2022JP

Japanese (JIS-Allow 1 byte Kana)

✓

50222

iso-2022-jp

Japanese (JIS-Allow 1 byte Kana - SO/SI)

✓

50225

iso-2022-kr

Korean (ISO)

✓

50227

x-cp50227

Chinese Simplified (ISO-2022)

✓

51932

euc-jp

Japanese (EUC)

✓

51936

EUC-CN

Chinese Simplified (EUC)

✓

51949

euc-kr

Korean (EUC)

✓

52936

hz-gb-2312

Chinese Simplified (HZ)

✓

54936

GB18030

Chinese Simplified (GB18030)

✓

57002

x-iscii-de

ISCII Devanagari

✓

57003

x-iscii-be

ISCII Bengali

✓

57004

x-iscii-ta

ISCII Tamil

✓

57005

x-iscii-te

ISCII Telugu

✓

57006

x-iscii-as

ISCII Assamese

✓

57007

x-iscii-or

ISCII Oriya

✓

57008

x-iscii-ka

ISCII Kannada

✓

57009

x-iscii-ma

ISCII Malayalam

✓

57010

x-iscii-gu

ISCII Gujarati

✓

57011

x-iscii-pa

ISCII Punjabi

✓

65000

utf-7

Unicode (UTF-7)

✓

65001

utf-8

Unicode (UTF-8)

✓

 

Examples (C#/WCF)

 

To set the Therefore-Auth-Codepage HTTP header in a .Net WCF client you can use the endpoint behavior from the Web API SDK Samples. The behavior class name is CredentialsCodePageProviderBehavior.

 

To see how to use this behavior, refer to the Web API SDK samples:

osee the SharedServiceReference.ClientConnection.CreateClientBasicAuth() method if you use service reference;

oor the Common.ThereforeServiceConnection.CreateChannelFactory() method if you use shared contract DLL.

 

 

Connection and Authentication Samples

 

In this section you can find code samples about how to connect to the Web API. Please see Web API SDK Samples for more details.

 

Technology on Client Side

Authentication Type

Basic

Windows

.Net Framework 2.0 only

web reference

sample

sample

.Net Framework 3.0 or newer

service reference
(configuration in file)

sample

sample

service reference
(configuration via code)

sample

sample

 

note

 

All Web API clients for Windows Authenticated users require Impersonation level of Impersonation to be set to authenticate the user.

Here is a code sample to set the level:

 

 ThereforeServiceClient client = CreateClientWindowsAuth();

 client.ClientCredentials.Windows.AllowedImpersonationLevel = TokenImpersonationLevel.Impersonation;

 

 

 

Connection and Authentication by using web references (auto generated proxy)

For full code sample, please see OldClient_Net20.csproj project in WebAPI SDK Samples.

 

Basic authentication:

 

 // 1. Declare Web API Service Client.

 OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapUserPassword service;

 

 // 2. Set tenant name if required.

 if (!String.IsNullOrEmpty(tenantName))

         service = new ThereforeWS0001_SoapUserPasswordHttpsWithTenantSupport(tenantName);

 else

         service = new OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapUserPassword();

 

 // 3. Set credentials

 // TODO: Set correct user name/password of Thereforeâ„¢ user

 NetworkCredential netCredential = new NetworkCredential("username""userpassword");

 Uri uri = new Uri(service.Url);

 ICredentials credentials = netCredential.GetCredential(uri"Basic");

 service.Credentials = credentials;

 service.PreAuthenticate = true;

 

 // 4. Execute web operation

 GetCategoriesTreeResponse response = service.GetCategoriesTree(new GetCategoriesTreeParams());

 

 // 5. Process response

 MessageBox.Show("Found :" + response.TreeItems.Length.ToString());

 

 

 Extend automatically generated proxy to support tenants

 

 public class ThereforeWS0001_SoapUserPasswordHttpsWithTenantSupport : OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapUserPassword

 {

         private string tenantName;

 

         public ThereforeWS0001_SoapUserPasswordHttpsWithTenantSupport(string tenantName)

         {

                 this.tenantName = tenantName;

         }

 

         protected override System.Net.WebRequest GetWebRequest(Uri uri)

         {

                 var request = base.GetWebRequest(uri);

                 request.Headers.Add("TenantName"tenantName);

                 return request;

         }

 }

 

 

Windows integrated authentication:

 

 // 1. Declare Web API Service Client.

 OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapWinCredentials service;

 

 // 2. Set tenant name if required.

 if (!String.IsNullOrEmpty(tenantName))

         service = new ThereforeWS0001__SoapWinCredentialsHttpsWithTenantSupport(tenantName);

 else

         service = new OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapWinCredentials();

 

 // 3. Set credentials

 service.UseDefaultCredentials = true;

 

 // 4. Execute web operation

 GetCategoriesTreeResponse response = service.GetCategoriesTree(new GetCategoriesTreeParams());

 

 // 5. Process response

 MessageBox.Show("Found :" + response.TreeItems.Length.ToString());

 

 

 Extend automatically generated proxy to support tenants

 

 public class ThereforeWS0001__SoapWinCredentialsHttpsWithTenantSupport : OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapWinCredentials

 {

         private string tenantName;

 

         public ThereforeWS0001__SoapWinCredentialsHttpsWithTenantSupport(string tenantName)

         {

                 this.tenantName = tenantName;

         }

 

         protected override System.Net.WebRequest GetWebRequest(Uri uri)

         {

                 var request = base.GetWebRequest(uri);

                 request.Headers.Add("TenantName"tenantName);

                 return request;

         }

 }

 

 

Connection and Authentication by using service references (configuration in file)

 

        /// <summary>

        /// Creates service client by using basic credentials.

        /// </summary>

        /// <returns></returns>

        private ThereforeServiceClient CreateClientBasicAuthConfig()

        {

            ThereforeServiceClient client = new ThereforeServiceClient("ThereforeWS0001_SoapUserPassword");

            client.ClientCredentials.UserName.UserName = "username";

            client.ClientCredentials.UserName.Password = "userpassword";

 

            return client;

        }

 

        /// <summary>

        /// Creates service client by using windows current user credentials.

        /// </summary>

        /// <returns></returns>

        private ThereforeServiceClient CreateClientWindowsAuthConfig()

        {

            ThereforeServiceClient client = new ThereforeServiceClient("ThereforeWS0001_SoapWinCredentials");

            return client;

        }

 

Connection and Authentication by using service references (configuration via code)

 

        private ThereforeServiceClient CreateClientBasicAuth()

        {

            //TODO: update it to the actual values

            string EndpointUriSoapun = "http://<servername>:8001/theservice/v0001/soapun";

 

            //basic

            BasicHttpBinding binding = new BasicHttpBinding();

            EndpointAddress address = new EndpointAddress(EndpointUriSoapun);

 

            binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;  //NOTE: use it for http protocol

            //binding.Security.Mode = BasicHttpSecurityMode.Transport;  //NOTE: use it for https protocol

            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;

            binding.MaxReceivedMessageSize = int.MaxValue;

            binding.ReceiveTimeout = new System.TimeSpan(0, 20, 0);

            binding.SendTimeout = new System.TimeSpan(0, 20, 0);

 

            ThereforeServiceClient client = new ThereforeServiceClient(bindingaddress);

            client.ClientCredentials.UserName.UserName = "username";

            client.ClientCredentials.UserName.Password = "userpassword";

 

            return client;

        }

 

        private ThereforeServiceClient CreateClientWindowsAuth()

        {

            //TODO: update it to the actual values

            string EndpointUriSoapwin = "http://<servername>:8001/theservice/v0001/soapwin";

 

            //win

            BasicHttpBinding binding = new BasicHttpBinding();

            EndpointAddress address = new EndpointAddress(EndpointUriSoapwin);

 

            binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;  //NOTE: use it for http protocol

            //binding.Security.Mode = BasicHttpSecurityMode.Transport;  //NOTE: use it for https protocol

 

            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Windows;

            binding.MaxReceivedMessageSize = int.MaxValue;

            binding.ReceiveTimeout = new System.TimeSpan(0, 20, 0);

            binding.SendTimeout = new System.TimeSpan(0, 20, 0);

 

            ThereforeServiceClient client = new ThereforeServiceClient(bindingaddress);

            return client;

        }

 

 

© 2023 Therefore Corporation, all rights reserved.