This document discusses how access to protected ENS APIs is designed, and how to use the Okkam security proxy in your Java applications to enable remote WS APIs access. We highly recommend the reader to go throughout the document for better understanding of the designed security process and the difference between non-protected ENS APIs and the protected APIs.
Should you have any questions regarding the use of the security proxy component, or how to access protected WS APIs,
please contact us at
This e-mail address is being protected from spambots. You need JavaScript enabled to view it
.
Security Proxy Concept
Facilitating secure and trusted interactions with ENS, it has been designed and developed security proxy component on both, client-side and service-side. The main goal behind the proxy design is to hide complexity and facilitate management of security technologies to OKKAM users, application developers, as well as, to ENS core development itself.
Access to ENS APIs requires Web services technologies. There are well-defined security standards for Web services that facilitate establishing secure and trusted interactions between entities. Some of adopted Web services standards are WS-Security, WS-Trust, WS-SecurityPolicy, WS-SecureConversation etc.
Figure 1: Client-Server Model of Security Proxy
Figure 1 shows the security proxy approach deployed in the ENS. All messages to and from the ENS are communicated via the proxy components.
Another main goal behind the proxy design is to make secure communications as transparent as possible to OKKAM-enabled applications, as well as, provide necessary authentication and access control mechanisms. To achieve transparent and intuitive interactions with ENS it has been designed that the proxy component implements all remote ENS APIs as they were locally deployed. Thus the proxy component becomes as local replica of ENS APIs with respect to user-side applications.
Another main achievement of the proxy is encapsulation of authentication and access control mechanism for accessing ENS APIs. The main goal here remains the same – achieving as much transparent as possible authentication and access control process to OKKAM-enabled applications.
Technically, the proxy approach provides confidential channel between the user-side proxy and the server-side proxy components. The confidential channel is established with a mutual certificate security mechanism that uses both, client and server-side public-key (identity) certificates to establish confidential communication channel between the client-side and server-side proxies.
A confidential channel is established if a user is a registered OKKAM user, i.e. a legitimate OKKAM user. Note that the user-side proxy component works always on behalf of a registered entity, i.e. the proxy authorizes to ENS as being the entity itself.
Once mutual authentication and a confidential channel are established, there is a mandatory access control process that controls if a registered user is allowed to access requested ENS APIs. The server-side proxy and a client-side proxy automatically negotiate if more access rights are necessary and present the necessary credentials (certified attributes). We refer to OKKAM D2.1 for details of the proxy architecture and the access control process.
Accessing Protected ENS APIs
The ENS provides a set of core functionalities made available as Web Services APIs [1]. All ENS functionalities, i.e. all WS APIs are referred to as public WS APIs. Although, all APIs are (available as) public accessible services, some of the functionalities are designed for controlled access, i.e. named as protected WS APIs. Those WS APIs, from the public description, which require protected access have been “copied” into a separate WS APIs description for controlled access only via the proxy component. Thus, there are two sets of WS APIs: Public WS APIs [2] and Protected WS APIs [3]. All ENS APIs are made publicly accessible but, however, those of them that require protected access have no functional “body” but instead always return an authorization exception with a message “Unauthorized public access”.
Any developer should use the public APIs to know what functionalities ENS provides and what interface the developer has to conform to, in order to use core ENS services.All interactions with protected ENS APIs must be performed via the security proxy. For this reason, to make access to ENS API as transparent as possible, the proxy component replicates all ENS APIs as locally accessible to your (ENS-enabled) applications. Figure 2 shows the proxy-based message flow of using the WS APIs.
Figure 2: Proxy-based Interactions with ENS APIs
Applications can establish direct or indirect via proxy communications with the ENS APIs. We note again that the proxy component replicates locally all ENS APIs, which facilitates developers of uniform access management. All APIs can be accessed via the proxy component, without keeping in mind which of those require protected access and which do not. Those APIs with no required protection the proxy just dispatches the respective requests/responses, as shown in the figure.The proxy component has two main usage modes: As a local host service and as a library to applications. The local host service implements the same (identical) ENS WS APIs but as locally accessible WS APIs. The library usage, in contrast, provides the respective Java APIs of the remote ENS APIs. In either of the modes the proxy component establishes secure and trusted communications with ENS on behalf of a user.
Public Web Services APIs (Java-like signatures)
/**
* Loads the entity with the input oid
*
* @param oid The uri of the entity to load
* @return an xml string that represent the loaded entity
*
* @throws OkkamCoreException
*/
public String getEntity(String oid) throws OkkamCoreException /**
* Queries the Okkam Node and return the entities that match the input query
*
* @param query The input query
* @return the MatchingCandidate set of the results
*
* @throws OkkamCoreException
*/
public MatchingCandidate[] findEntity(String query) throws OkkamCoreException
/**
* Gets the alternative ids for the input entity
*
* @param oid The okkam uri of the entity to check
* @return a list of alternative ids
*
* @throws OkkamCoreException
*/
public String[] getAlternativeIds(String oid) throws OkkamCoreException
/**
* Gets the okkam id that has the input id as alternative id
*
* @param alternativeId The alternative id to check
* @return a list of okkam uris
*
* @throws OkkamCoreException
*/
public String[] getOidsByAlternativeId(String alternativeId) throws OkkamCoreException
/**
* Loads a list of entities from okkam
*
* @param oids The uris of the entities to load
* @return a list of xmls
*
* @throws OkkamCoreException
*/
public String[] getEntities(String[] oids) throws OkkamCoreException
/**
* Loads the entity template for the input type
*
* @param type
* @return an xml
*
* @throws OkkamCoreException
*/
public String getTypeTemplate(String type) throws OkkamCoreException
/**
* Gets similar entities
*
* @param entity The xml representation of the entity to check
* @return a list of the similar entities as xml string
*
* @throws OkkamCoreException
*/
public String[] getMatches(String entity) throws OkkamCoreException
/**
* Locks an entity
*
* @param oid The uri of the entity to lock
* @return String Ticket for the locked entity
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public String lockEntity(String oid) throws OkkamAuthorizationException, OkkamCoreException
/**
* Locks a list of entities
*
* @param oids The uris of the entities to lock
* @return String[] Array of tickets for the locked entities
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public String[] lockEntities(String[] oids) throws OkkamAuthorizationException, OkkamCoreException
/**
* Unlocks an entity
*
* @param oid The uri of the entity to unlock
* @param ticket The ticket to unlock the input entity
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public void unlockEntity(String oid, String ticket)
throws OkkamAuthorizationException, OkkamCoreException
/**
*
* @param entity
* @param ignoreDuplicates
* @return An EntityValidationReport
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public EntityValidationReport validateEntity(
String entity, boolean ignoreDuplicates) throws OkkamAuthorizationException, OkkamCoreException
/**
* Creates a new Entity
*
* @param certificate
* @return String
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public String createNewEntity(String certificate) throws OkkamAuthorizationException, OkkamCoreException
/**
* Deletes an entity
*
* @param oid The uri of the entity to delete
* @param ticket The ticket to delete the entity
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public void deleteEntity(String oid, String ticket) throws OkkamAuthorizationException, OkkamCoreException
/**
* Merges a list of entities
*
* @param oids Array of uris with the entities to merge
* @param mergedEntity the merged entity
* @param tickets Array of tickets
* @return A NewEntityResultClient
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public NewEntityResultClient mergeEntities(String[] oids, String mergedEntity, String[] tickets)
throws OkkamAuthorizationException, OkkamCoreException
/**
* Splits an Entity
*
* @param oid The uri of the entity to split
* @param splitEntities The array of split entities
* @param ticket The ticket
* @return Array of NewEntityResultClient
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public NewEntityResultClient[] splitEntity(String oid, String[] splitEntities, String ticket)
throws OkkamAuthorizationException, OkkamCoreException
/**
* Updates an entity
*
* @param ticket The ticket to update the entity
* @param certificate The certificate of the entity to update
*
* @throws OkkamAuthorizationException if insufficient access rights.
* @throws OkkamCoreException
*/
public void updateEntity(String ticket, String certificate) throws OkkamAuthorizationException, OkkamCoreException
/**
* Returns the ENS node public-key certificate (X.509 format)
*
* @return X509 Certificate encoded as a byte array
*/
public byte[] getServerCertificate()
Protected Web Services APIs from the list of public APIs with corresponding access control requirements.
/** Requires administrator privileged access. */
public String lockEntity(String oid) throws OkkamAuthorizationException, OkkamCoreException
/** Requires administrator privileged access. */
public String[] lockEntities(String[] oids) throws OkkamAuthorizationException, OkkamCoreException
/** Requires administrator privileged access. */
public void unlockEntity(String oid, String ticket) throws OkkamAuthorizationException, OkkamCoreException
/** Requires Okkam user or administrator privileged access. */
public EntityValidationReport validateEntity(String entity, boolean ignoreDuplicates)
throws OkkamAuthorizationException, OkkamCoreException
/** Requires Okkam user or administrator privileged access. */
public String createNewEntity(String certificate) throws OkkamAuthorizationException, OkkamCoreException
/** Requires administrator privileged access. */
public void deleteEntity(String oid, String ticket) throws OkkamAuthorizationException, OkkamCoreException
/** Requires administrator privileged access. */
public NewEntityResultClient mergeEntities(String[] oids, String mergedEntity, String[] tickets)
throws OkkamAuthorizationException, OkkamCoreException
/** Requires administrator privileged access. */
public NewEntityResultClient[] splitEntity(String oid, String[] splitEntities, String ticket)
throws OkkamAuthorizationException, OkkamCoreException
/** Requires administrator privileged access. */
public void updateEntity(String ticket, String certificate) throws OkkamAuthorizationException, OkkamCoreException
Protected Security Specific APIs (Java-like signatures)
public byte[] registerUser(String firstName, String lastName, String username, String password, String email,
String organization, String country, boolean storeUserPrivateKey)
throws RemoteException, OkkamAuthorizationException
public void removeRegisteredUser(String email) throws RemoteException, OkkamAuthorizationException
public byte[] certifyUserAttribute(String x509UserCert, AttributeRoleName attribute, int validityInDays)
throws RemoteException, OkkamAuthorizationException
public CredentialResponse getAuthorizationWS(String requestedService, String requestedCredential,
List<Credential> presentedCredentials, List<String> deniedCredentials)
Using Okkam Security Proxy inside Java Code
Download Okkam security proxy from the download section of the community portal. Unzip it to a local folder of your project space. Refer to that folder as ProxyRoot folder.
You need the following java libraries in your Java classpath:
- BouncyCastle security library (for Java 6 or later) allocated in ProxyRoot/dist/lib/bcprov-jdk16-143.jar
- iAccess authorization system library (v2.0 or later) allocated in ProxyRoot/dist/lib/iAccessClient20beta005.jar
- METRO libraries (v1.5 or later) allocated in ProxyRoot/dist/lib/webservices-rt.jar and ProxyRoot/dist/lib/webservices-tools.jar
- Okkam security proxy library (v1.11 or later) allocated in ProxyRoot/dist/okkam-proxy.jar
Below is the code example of how to use the okkam-proxy inside your java code:
01 import org.iaccess.accesscontrollayer.IAccessManager;
02 import org.okkam.proxyclient.security.iaccess.AuthorizationManager;
03 import org.okkam.proxyclient.security.iaccess.IAccessClientOkkam;
...
10 String OKKAM_SERVER = "http://api.okkam.org/okkam-core/WebServices";
11
12 try
13 {
14 AuthorizationManager authManager = AuthorizationManager.getInstance();
15 // username and password from a user registration process.
16 authManager.initIAccess(username, password);
17 // At this point, all the certificates are to be loaded
18 AccessManager iAccessManager = authManager.getIAccessManager();
19 IAccessClientOkkam client = new IAccessClientOkkam(
20 iAccessManager, OKKAM_SERVER);
21
22 //For example when the client application wants to invoke
createNewEntity() with an input message. Input is a data object according to ENS APIs.
23 String result = client.createNewEntity(input);
24 }
25 catch(Exception e)
26 {
27 e.printStackTrace();
28 }
In this case, the okkam-proxy library will look for the user’s keystore and certificates in the ProxyRoot folder wich, by default, is the folder where the okkam-proxy application is executed. The ProxyRoot folder should contain the data folder, with the user’s keytores and certificates, plus other configuration files.
When the application is running in a Web environment, it may be difficult to know where the actual ProxyRoot folder is located. For this reason, it is possible to select the ProxyRoot folder when the AuthorizationManager instance is initialized. To do this, we only have to initialize the AuthorizationManager instance in this way:
14 AuthorizationManager authManager = AuthorizationManager.getInstance();
15 // username and password from a user registration process.
16 authManager.initIAccess(username, password, PROXY_ROOT);
Where PROXY_ROOT is the path to the ProxyRoot folder.
How to Run Security Proxy with Already Registered Certificate Data (P12 format)
If you have registered to OKKAM via the Web front-end (via http://register.okkam.org), you can use your .p12 registration data directly in the security proxy application. You have to copy the .p12 file into the PROXY_ROOT/data/keystores/ folder and run your application. The proxy should automatically detect that the specified username corresponds to a .p12 file and will convert it into .jks format.
If the above does not work for you, there is a workaround by copying the .p12 file as indicated above and then run the proxy GUI in PROXY_ROOT/okkam-proxy.exe if Windows OS or PROXY_ROOT/okkam-proxy.sh if Unix OS. Then, login using your username and password, and if successful login quit the proxy. In this case the proxy automatically converts the .p12 data file into .jks data file (in the same folder).
If you get an exception of illegal key size you should install
The Cryptography Extension (JCE) Unlimited Strength on your JVM. Follow the link below to download the policy file.
Inside the zip you will find the steps to replace the policy file.
[1] http://community.okkam.org/index.php/Documentation/APIs/
[2] Public APIs WSDL: http://api.okkam.org/okkam-core/WebServices?wsdl
[3] Protected APIs WSDL: http://api.okkam.org/okkam-core/WebServicesSecured?wsdl
