Client configuration and use:¶

Configuration¶

Configuring an OLYMPUS client is fairly simple. When the application client instantiates the relevant type of OLYMPUS client, eg. PestoClient or PabcClient, it must provide a) a list of IdP servers, b) a client cryptomodule and c) a CredentialManagement implementation in the case of the PabcClient.

a) The list of servers should be provided as a list of PestoIdPRestConnection objects, each taking a URL, an access token and an id parameter. Note that the access token is only used in connection with starting the key-refreshing protocol, and should be null for non-admin users/applications. The PestoIdPRestConnect is essentially just a REST wrapper for the IdP functionality. An application developer may therefore implement a different wrapper is necessarry.
b) A SoftwareClientCryptoModule may be used as the cryptomodule. As the name suggests, the SoftwareClientCryptoModule offers a software implementation of various necessary cryptographic operations. If desired, a custom implementation of ClientCryptoModule may be used, allowing the application to utilize hardware based cryptographic operations.
c) As the PabcClient operates with credentials in order to support offline usage, the PabcClient needs an CredentialManagement interface to access these credentials. The PSCredentiaManagement class may be used for this purpose. Note that the PSCredentialManagement class requires a storage component. The InMemoryCredentialStorage can be used for this, however this storage is not secure and should not be used outside of testing. Instead a custom implementation should be used, allowing the credentials to be stored in a secure manner, ie. in hardware.

Sample code of configuring a PestoClient and PabcClient, to use a vIdP located at https://127.0.0.1:8090, https://127.0.0.1:8091 and https://127.0.0.1:8092 may be found below:

       List<PestoIdP> idpList = new ArrayList<>();
       idpList.add(new PestoIdPRESTConnection("http://127.0.0.1:8090", null, 0));
       idpList.add(new PestoIdPRESTConnection("http://127.0.0.1:8091", null, 1));
       idpList.add(new PestoIdPRESTConnection("http://127.0.0.1:8092", null, 2));
       ClientCryptoModule cryptoModule = new SoftwareClientCryptoModule(new Random(0), modulus);
       //PestoClient:
       UserClient client = new PestoClient(idpList, cryptoModule);
       //PabcClient:
       PSCredentialManagement credentialManagement = new PSCredentialManagement(true, new InMemoryCredentialStorage());
       credentialManagement.setup(publicParam, publicKeys, seed);
       UserClient client = new PabcClient(restIdps, credentialManagement, cryptoModule);

Usage¶

After the appropriate OLYMPUS client has been initialized, it is possible to access the methods of the UserClient interface, e.g. createUser(…), proveIdentity(…), authenticate(…), etc. The calls have a number of parameters in common:

Username - The user’s account name
Password - The user’s password
Token - In case MFA is enabled, this is the OTP code or response to a challenge. If MFA is not enabled for the account, a null value can be used.
Type - In case MFA is enabled, this should is the MFA scheme name. The concrete value is dependant on the vIdP deployment and is further described in the IdP section. In case MFA is not used, the string “NONE” must be used.
IdentityProof - In order to attach attributes to an account an IdentityProof must be supplied. The concrete instantiation of the IdentityProof to use, is dependant on the vIdP deployment and is further described in the IdP section.
Policy - The policy specifies what the output of the authenticate method should contain. The policy contains an identifier and a list of predicates. A Predicate consists of an attribute name, an operation and a value used with comparing operations.

The following sample code will create a new user account (named “Bob” with the password “Secret”). After that, it will enable MFA, with a Google Authenticator app and finally it will attempt to authenticate, with a policy comparing the user’s age with 18 and revealing the name of the user.

       client.createUser("Bob", "Secret");
       String challenge = client.requestMFAChallenge("Bob", "Secret", "GOOGLE_AUTHENTICATOR");
       String mfaToken = ... // Use the challenge and a Google Authenticator app to generate the mfaToken out of band.
       client.confirmMFA("Bob", "Secret", mfaToken, "GOOGLE_AUTHENTICATOR");     
       List<Predicate> predicates = new ArrayList<>();
       predicates.add(new Predicate("Name", Operation.REVEAL, null));
       predicates.add(new Predicate("Age", Operation.GREATERTHAN, new Attribute(18)));
       Policy policy = new Policy(predicates, "policy-identifier"); 
       String token = client.authenticate("Bob", "Secret", policy, mfaToken, "GOOGLE_AUTHENTICATOR");