Connection and Authentication |
Scroll |
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:
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) |
✓ |
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.
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 |
||
.Net Framework 3.0 or newer |
service reference |
||
service reference |
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;
|
For full code sample, please see OldClient_Net20.csproj project in WebAPI SDK Samples.
// 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;
}
}
// 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;
}
}
 /// 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;
 }
 /// Creates service client by using windows current user credentials.
 /// </summary>
 /// <returns></returns>
 private ThereforeServiceClient CreateClientWindowsAuthConfig()
 {
 ThereforeServiceClient client = new ThereforeServiceClient("ThereforeWS0001_SoapWinCredentials");
 return client;
 }
 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(binding, address);
 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(binding, address);
 return client;
 }