3.1 Security

In order to be served by Core (search, ...) or Cloud (read sensor data, actuate, invoke service) you need to put security headers in requests. For an extensive and up-to-date description of how to do that, you can check the SymbIoTeSecurity repository. Below, you can find a basic description on how to get a guest token.

3.1.1 Getting security headers for GUEST users

We briefly show how the clients can acquire GUEST credentials required to search and access PUBLIC resources in SymbIoTe. First comes the generic part for developers that don't want to use our Java implementation and afterwards the tutorial using our reference Java codes for symbioteSecurity library.

3.1.1.1 Acquire a GUEST Token

To acquire a GUEST Token, send empty HTTP POST request on:

https://<coreInterfaceAdress>/aam/get_guest_token

e.g. https://symbiote-open.man.poznan.pl/coreInterface/aam/get_guest_token

or

https://<platformInterworkingInterface>/aam/get_guest_token

e.g. https://symbiotedoc.tel.fer.hr/aam/get_guest_token

, depending on which platform you want to acquire the GUEST token from. Please be aware that either of them has the same authorization power. In return you will get empty response which header x-auth-token contains your GUEST token.

Example of response:

HTTP/1.1 200 
Server: nginx/1.10.3 (Ubuntu)
Date: Sat, 19 May 2018 10:39:03 GMT
Content-Length: 0
Connection: keep-alive
x-auth-token: eyJhbGciOiJFUzI1NiJ9.eyJ0dHlwIjoiR1VFU1QiLCJzdWIiOiJndWVzdCIsImlwayI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRWY3dXE2b1FxcXdzRzVDQ0l0d1RqQ3FqWUxwTmVvL0RTN2FzajB3VCsvVnRlRW5kZnoxeW9NZ2NMZUJ1OEtWTTdrY1ViQnBIVm5xblFsRCtqRFJJaFZRPT0iLCJpc3MiOiJ4cGxhdGZvcm0iLCJleHAiOjE1MjY3MjY0MDMsImlhdCI6MTUyNjcyNjM0MywianRpIjoiLTQ2NjAwMzU5Iiwic3BrIjoiTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFQ2hXZHAvQUs1Ulh0S1hkNlJscmZ3MlVYUzE3ZUc5QnRZT3Z5V2ZkUk13WmNXTFdyVlZqSDBQeEpXS2hDZmFtZkxibzB4cGNkdGVsUUNwSGl3WkNwS0E9PSJ9.Wm2cfEo0H44tfpWA7Uhi26UPXIVzN8b6bBlZru1h_tD_I5OnCRPXOxYBF3pgRuEQFjq-l-bEDzuBMlqeSikmcw

3.1.1.2. Create Security Request

Result from previous step is used to create headers in HTTP requests for searching or accessing resources.

To make use of your GUEST token you need to wrap it into our SecurityRequest. For standardized communication, we deploy it into the following HTTP headers:

• current timestamp in miliseconds goes into header
  • x-auth-timestamp
• don't change just include
  • x-auth-size=1
• special JSON structure
  • under header x-auth-1
  • containing populated field:
    • "token":"HERE_COMES_THE_TOKEN_STRING",
  • and empty fields which you don't need to care about, just put the there:
    • "authenticationChallenge":"",
    • "clientCertificate":"",
    • "clientCertificateSigningAAMCertificate":"",
    • "foreignTokenIssuingAAMCertificate":""

Example:

x-auth-timestamp: 1519652051000
x-auth-size: 1
x-auth-1:
{
    "token":"eyJhbGciOiJFUzI1NiJ9.eyJ0dHlwIjoiR1VFU1QiLCJzdWIiOiJndWVzdCIsImlwayI6Ik1GaFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRVBhZURDNElnT3VITlBmWCtURG5adXZuTHdUbHMwMERQb294aVZCTE8za3I0N0N3TXFYSm4yN3lpdFdZUkRRKzBmWG52MzFIbGJLbkxSWktqSmF5U3p3PT0iLCJpc3MiOiJTeW1iSW9UZV9Db3JlX0FBTSIsImV4cCI6MTUxMDU2Nzg2NywiaWF0IjoxNTEwNTY3MjY3LCJqdGkiOiI2MzI4NDUxMzAiLCJzcGsiOiJNRmt3RXdZSEtvWkl6ajBDQVFZSUtvWkl6ajBEQVFjRFFnQUVsdlNwYVhDa2RFZ3lYM2xJeWQ1VCs2VFgyQ0hXMDluekNjL05aY2krcGEvdmtQSG5DeFZESkpLTkZwL1hQc0g2T1hvSTkxQXJFcUJ1SlJtd3k2dWZSdz09In0.zn7xjwUq89YSNptLTFCZSpb8n65n4o24HPOw2WPTJSglfaO8paW1O5vC3n9072ktm327kj44Kgs5qqMhRy22cA",
    "authenticationChallenge":"",
    "clientCertificate":"",
    "clientCertificateSigningAAMCertificate":"",
    "foreignTokenIssuingAAMCertificate":"" 
}

With such prepared headers you can access SymbIoTe resources offered publicly, e.g. execute search queries or send request to Resource Access Proxy.

3.1.2.1 Access to public resources for Java developers

The following snippet generates the security headers

// creating REST client communicating with SymbIoTe Authorization Services 
// AAMServerAddress can be acquired from SymbIoTe web page
IAAMClient restClient = ClientFactory.getAAMClient(AAMServerAddress);

// acquiring Guest Token
String guestToken = restClient.getGuestToken();

// creating securityRequest using guest Token
SecurityRequest securityRequest = new SecurityRequest(guestToken);

// converting the prepared request into communication ready HTTP headers.
Map<String, String> securityHeaders = new HashMap<>();
securityHeaders = securityRequest.getSecurityRequestHeaderParams();

With these headers containing your GUEST token you can use SymbIoTe APIs to access public resources. It can be also acquired in the following way, using end user Java client described here:

// Initializing application security handler 
ISecurityHandler clientSH = ClientSecurityHandlerFactory.getSecurityHandler( 
			coreAAMServerAddress, 
			KEY_STORE_PATH, 
			KEY_STORE_PASSWORD, 
			clientId ); 
// examples how to retrieve AAM instances 
AAM coreAAM = clientSH.getCoreAAMInstance(); 
AAM platform1 = clientSH.getAvailableAAMs().get(platformId); 


// Acquiring GUEST token from platform1 
Token guestToken = clientSH.loginAsGuest(platform1); 


// creating securityRequest using guest Token 
SecurityRequest securityRequest = new SecurityRequest(guestToken); 


// converting the prepared request into communication ready HTTP headers. 
Map<String, String> securityHeaders = new HashMap<>(); 
securityHeaders = securityRequest.getSecurityRequestHeaderParams();

Then, after receiving the response from a SymbIoTe component, you should check if it came from component you are interested. To do that you can use the following snippet

// trying to validate the service response 
MutualAuthenticationHelper.isServiceResponseVerified(serviceResponse,
    restClient.getComponentCertificate(componentIdentifier, platformIdentifier));

, where the componentIdentifier can be read from the table available here.