VisiBroker for .NET Developer’s Guide : Using the Security service
Using the Security service
As more businesses deploy distributed applications and conduct operations over the Internet, the need for high quality application security has grown.
Sensitive information routinely passes over Internet connections between web browsers and commercial web servers; credit card numbers and bank balances are two examples. For example, users engaging in commerce with a bank over the Internet must be confident that:
•
They are in fact communicating with their bank's server, not an impostor that mimics the bank for illegal purposes.
•
The data exchanged with the bank will be unintelligible to network eavesdroppers.
•
The data exchanged with the bank software will arrive unaltered. An instruction to pay $500 on a bill must not accidentally or maliciously become $5000.
VisiBroker for .NET Security lets the client authenticate the bank's server. The bank's server can also take advantage of the secure connection to authenticate the client. In a traditional application, once a secure connection has been established, the client sends the user's name and password to authenticate. This technique can be used once a VisiBroker for .NET secure connection has been established, with the benefit that the user name and password exchanges will be encrypted.
VisiBroker for .NET Security overview
VisiBroker for .NET Security lets you establish secure connections between clients and servers, and it provides a framework for secure communication. VisiBroker for .NET Security uses the Microsoft Windows Secure Channel (Schannel) library for SSL and TLS (Transport Layer Security) communications and the Microsoft CryptoAPI for cryptographic operations.
VisiBroker for .NET Security features include
•
J2EE server and CORBA server interoperability: VisiBroker for .NET Security seamlessly interoperates with EJB security via the underlying CORBA Common Secure Interoperability specification (CSIv2).
•
Microsoft Windows Certificate Store integration: VisiBroker for .NET Security uses the Microsoft Windows Certificate Store for public and private key management.
•
ASP.NET integration: VisiBroker for .NET Security propagates the security identities authenticated by ASP.NET applications to the J2EE server or CORBA server.
•
Secure Transport Layer: VisiBroker for .NET Security utilizes SSL and TLS protocols as a secure transport layer. Both protocols provide message confidentiality, message integrity, and certificate-based authentication support through a trust model.
•
GateKeeper integration: VisiBroker for .NET Security supports a secure connection through GateKeeper. For details see “Using VisiBroker for .NET with GateKeeper” and the VisiBroker GateKeeper Guide.
Enabling VisiBroker for .NET Security
By default VisiBroker for .NET Security is disabled. To enable the VisiBroker for .NET Security include the <security> section in the configuration file as shown below:
<visinet>
<security enabled="true">
</security>
</visinet>
Alternatively, you can enable security by setting the janeva.security property to true. See (properties chapter) for instructions.
Interoperating with J2EE servers and CORBA servers
VisiBroker for .NET Security supports two kinds of user authentication:
•
User name and password authentication
•
Certificate-based authentication
VisiBroker for .NET Security supports the .NET Remoting API, a CORBA-based API, and a configuration file method of setting up the security identity. These methods are described in each of the following sections.
User name and password authentication
If the J2EE server or CORBA server requires user authentication, VisiBroker for .NET Security provides multiple ways to set up the user credentials and pass them to the server side. User name and password authentication lets a VisiBroker for .NET client authenticate users by passing a user name and password to the server. You can implement user name and password authentication in one of the following ways: the .NET Remoting API, the CORBA-based API, or the application configuration file.
Using the .NET Remoting API for user name and password authentication
The following example shows you how to use the .NET Remoting API to do user name and password authentication. The first step is to resolve the Remoting proxy reference:
// creating the CartHomeRemotingProxy configured as
// a well-known remoting object in the config file
CartHome home = new CartHomeRemotingProxy();
The next step is to resolve the Sink Properties of this Remoting proxy object:
// setup security credentials
IDictionary props =
System.Runtime.Remoting.Channels.ChannelServices.
GetChannelSinkProperties(
home);
Next, the application sets the user name and password properties:
props["username"] = "joeshopper";
props["password"] = "joepass";
Optionally, you can also set the realm.
props["realm"] = "myuprealm";
In the absence of the realm property, the realm defaults to default.
Note
Different application servers might have different names for the default realm. You can set the default realm name in the configuration file. When you need to override the default realm set in the configuration file you can set the property in the command line or programmatically as shown above. See “Configuring properties” for more information.
Once the properties are set you can invoke methods on the Remoting proxy. The user name, password, and realm are passed transparently to the server side as a part of the invocation context.
// creating a new instance of Cart session
Cart cart = home.Create(...);
Note that it is important to set the credentials before the first invocation on the Remoting proxy, otherwise the credentials are not passed to the server.
Keep in mind that every object on the same server shares the same secure connection. Once the first invocation is completed, any subsequent invocation on the same or other objects located on the same server shares the credentials established with the first invocation. To change the credentials resolve the Sink Properties and set the username and password properties again.
In the example below, you do not need to set up the credentials again for the cart object. The cart uses the same credentials established by the secure connection to the home object.
// adding a new book into the cart
Item book = new Book();
book.Title = "War and Peace";
book.Price = 20.99f;
cart.AddItem(book);
More example code is located in the <janeva_install_dir>\examples\Advanced\Security\RemotingUsernameClient directory.
Using the CORBA-based API for user name and password authentication
The following example shows how to use the CORBA-based API to establish the user credentials.
The first step is to resolve the VisiBroker for .NET security context on the orb instance. Janeva.Security.Context is the object which exposes the API with which you manipulate the user's identity.
// initialize the ORB
CORBA.ORB orb = CORBA.ORB.Init(args);
// resolve the Securuty Context
Janeva.Security.Context context =
(Janeva.Security.Context)
orb.ResolveInitialReferences("SecurityContext");
Next, to set the user name, password and realm use the Janeva.Security.IdentityWallet class as follows:
// create a wallet with the credentials
Janeva.Security.IdentityWallet wallet =
new Janeva.Security.IdentityWallet(
"joeshopper", "joepass".ToCharArray(), "myuprealm");
In the absence of the realm property, the realm defaults to default.
Note
Different application servers might have different names for the default realm. You can set the default realm name in the configuration file. When you need to override the default realm set in the configuration file you can set the property in the command line or programmatically as shown above. See “Configuring properties” for more information.
The last step is to call a Login method on the security context with the wallet:
// login in to the security conext with the wallet
context.Login(wallet);
The Janeva.Security.Context object provides different login methods. Please see the VisiBroker for .NET API reference for details.
Keep in mind that every object on the same server shares the same secure connection. Once the first invocation is completed, any subsequent invocation on the same or other objects located on the same server shares the credentials established with the first invocation. To change the credentials call Logout and then call Login again.
Once you set the credentials with the Login method you can invoke methods on the sever:
// creating a new instance of Cart session
Cart cart = home.Create(...);
Once you login to the Janeva.Security.Context the same credentials are used with any subsequent remote invocation:
// adding a new book into the cart
Item book = new Book();
book.Title = "War and Peace";
book.Price = 20.99f;
cart.AddItem(book);
Using a configuration file for user name and password authentication
The following is an example of how to set security credentials using a configuration file.
<configuration>
<visinet>
<security enabled="true">
<identity>
<username>joeshopper</username>
<password>joepass</password>
<realm>myuprealm</realm>
</identity>
</security>
</visinet>
</configuration>
Setting the identity in the configuration file has a global effect on the application. The same identity is used for each remote invocation.
Certificate-based authentication
VisiBroker for .NET certificate support is based on the Microsoft Windows Certificate Store. Before the certificate can be used with a VisiBroker for .NET application it needs to be imported into the Certificate Store. Refer to the Microsoft documentation for more information on how to issue and manage certificates.
One of the optional certificate attributes is a friendly name. VisiBroker for .NET uses the certificate's friendly name as the identifier to address a particular certificate. If a certificate does not have a friendly name you can set it in the Microsoft Windows Internet Options control panel.
Note:
When the certificate is used to authenticate the client, it is important that the certificate have both public and private keys in it. This is the requirement of the SSL/TLS protocol.
Using the .NET Remoting API for certificate-based authentication
The following example shows you how to use the .NET Remoting API to achieve certificate-based authentication.
The first step is to resolve the Remoting proxy reference:
// creating the CartHomeRemotingProxy configured as
// a well-known remoting object in the config file
CartHome home = new CartHomeRemotingProxy();
The next step is to resolve the SinkProperties of this Remoting proxy object:
// setup security credentials
IDictionary props =
System.Runtime.Remoting.Channels.ChannelServices.GetChannelSinkProperties(
home);
Next, set the certificate's friendly name:
props["certificate"] = "joeshopper";
Note
Instead of using the friendly name, you can also specify an asterisk (*) to let VisiBroker for .NET decide which certificate to use.
Once the property is set you can invoke methods on the Remoting proxy. The certificate is passed transparently to the server side as a part of the invocation context.
// creating a new instance of Cart session
Cart cart = home.Create(...);
Note that it is important to set the credentials before the first invocation on the Remoting proxy, otherwise the credentials will not be passed to the server.
Keep in mind that every object on the same server shares the same secure connection. Once the first invocation is completed, any subsequent invocation on the same or other objects located on the same server shares the credentials established with the first invocation. To change the credentials resolve the Sink Properties and set the username and password properties again.
In the example code below, you do not need to set up the credentials again for the cart object. The cart uses the same credentials established by the secure connection to the home object.
// adding a new book into the cart
Item book = new Book();
book.Title = "War and Peace";
book.Price = 20.99f;
cart.AddItem(book);
More example code is located in the <janeva_install_dir>\examples\Advanced\Security\RemotingCertificateClient directory.
Using the CORBA-based API for certificate-based authentication
The following example shows how to use the CORBA-based API to achieve certificate-based authentication.
The first step is to resolve the VisiBroker for .NET security context on the orb instance. The Janeva.Security.Context is the object which exposes the API with which you manipulate the user's identity.
// initialize the ORB
CORBA.ORB orb = CORBA.ORB.Init(args);
// resolve the Securuty Context
Janeva.Security.Context context =
(Janeva.Security.Context) orb.ResolveInitialReferences("SecurityContext");
Next, to set the certificate friendly name you need to use the Janeva.Security.CertificateWallet class as follows:
// create a wallet with the credentials
Janeva.Security.CertificateWallet wallet = new
Janeva.Security.CertificateWallet("joeshopper",
CertificateWallet.CLIENT_AUTHENTICATION);
The second parameter defines the certificate usage. This parameter is set differently when used for secure server (see “Enabling security for .NET servers”). For details on the other values for this parameter see the VisiBroker for .NET API reference.
Note
Instead of using the friendly name, you can also specify an asterisk (*) to let VisiBroker for .NET decide which certificate to use.
Last step is to call a Login method on the security context with the wallet:
// login in to the security conext with the wallet
context.Login(wallet);
The Janeva.Security.Context object provides different login methods. See the VisiBroker for .NET API reference for details.
Keep in mind that every object on the same server shares the same secure connection. Once the first invocation is completed, any subsequent invocation on the same or other objects located on the same server shares the credentials established with the first invocation. To change the credentials call Logout and then call Login again.
Once you set the credentials with the Login method you can invoke methods on the object:
// creating a new instance of Cart session
Cart cart = home.Create(...);
Once you login to the Janeva.Security.Context the same credentials are used with any subsequent remote invocation.
// adding a new book into the cart
Item book = new Book();
book.Title = "War and Peace";
book.Price = 20.99f;
cart.AddItem(book);
Using a configuration file for certificate-based authentication
The following is an example of how to specify the certificate in a configuration file.
<configuration>
<visinet>
<security enabled="true">
<identity>
<certificate>joeshopper</certificate>
</identity>
</security>
</visinet>
</configuration>
Setting the certificate in the configuration file has a global effect on the application. The identity presented by the certificate is used for each remote invocation.
ASP.NET integration
The VisiBroker for .NET Security integration with ASP.NET is based on the concept of identity assertion. Whenever the VisiBroker for .NET runtime on ASP.NET makes an outgoing call, it will propagate two identities to the called server. It will identify itself to the called server and assert the caller's identity.
The caller's identity is the identity that the browser or other clients use to communicate with the ASP.NET tier. When VisiBroker for .NET asserts this identity as the caller identity, it is, in fact, asserting to the called server that this tier trusts that this caller is authenticated and it is performing this request on behalf of this caller.
It is up to the called server to decide whether it will accept this assertion from this tier. Since the ASP.NET tier identifies itself, it allows the called server to authenticate and decide whether this tier has the privileges to make this assertion.
Note
Some servers may need explicit configuration that defines which peer identities (in this case, the identity of the ASP.NET tier) it will accept assertions from. Refer to the server's documentation for more details.
ASP.NET configuration
Within an ASP.NET environment, VisiBroker for .NET implicitly detects whether a user is authenticated and passes the user identity as the caller identity to the server side. The peer identity is established explicitly using the VisiBroker for .NET Security API as shown in the examples in “Interoperating with J2EE servers and CORBA servers”.
The following is an example of how a configuration file can establish the peer identity for an ASP.NET application. Note that this example is similar to the example in “Using a configuration file for certificate-based authentication”.
<configuration>
<visinet>
<security enabled="true">
<identity>
<username>peer</username>
<password>pwd</password>
...
</configuration>
Note
You can also explicitly set the caller identity with the Janeva.Security.Context.ImportIdentity() API. This allows you to use the trust model outside of the ASP.NET environment. See the VisiBroker for .NET API reference for details about Janeva.Security.Context.ImportIdentity.
More example code is located in the <janeva_install_dir>\examples\Advanced\Security\AspNetClient directory.
Enabling security for .NET servers
For secure .NET server applications VisiBroker for .NET Security can be enabled on the server side by setting the janeva.security.server property to true. The following is an example of how to set the property in the application configuration file.
<configuration>
<visinet>
<security>
<server enabled="true" defaultPort="15000">
<certificate>cert_friendly_name</certificate>
</server>
...
You can set the port which the VisiBroker for .NET server will use for SSL/TSL communication on the server side by setting the janeva.security.server.defaultPort property. See the previous example for how this is done in a configuration file.
The server side must be identified with a certificate per SSL/TSL protocol requirement. You can do this using the CORBA-based API or a configuration file property.
The following is an example of how to set the certificate identity in the configuration file:
<configuration>
<visinet>
<security>
<server enabled="true" defaultPort="15000">
<certificate>cert_friendly_name</certificate>
</server>
...
The following is an example of how to set the certificate identity using the CORBA-based API:
The first step is to resolve the VisiBroker for .NET security context on the orb instance. The Janeva.Security.Context is the object which exposes the API with which you manipulate the identity.
Janeva.Security.Context context = (Janeva.Security.Context)
CORBA.ORB.Init().ResolveInitialReferences("SecurityContext");
Next, to set the certificate you need to use the Janeva.Security.CertificateWallet class as follows:
Janeva.Security.CertificateWallet wallet = new Janeva.Security.CertificateWallet(
"joeshopper", Janeva.Security.CertificateWallet.SERVER_AUTHENTICATION);
Note that the second parameter defines the certificate usage for the server. For details on the other values for this parameter see the VisiBroker for .NET API reference.
The last step is to call a Login method on the security context with the wallet:
context.Login(wallet);
The Janeva.Security.Context object provides different login methods. See the VisiBroker for .NET API reference for details.
Note
When using the CORBA-based API configuration method, the certificate needs to be set up before the server starts listening for incoming requests, that is, before calling the CORBA.ORB.Run() method in your code.
More example code is located in the <janeva_install_dir>\examples\Advanced\Security\SslServer directory.