Hexagon Geospatial

API

Turn on suggestions Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Do you mean 

Foundation - Authentication

by Technical Evangelist on ‎11-09-2016 12:11 PM (1,226 Views)

Foundation - Authentication

This article is meant to descibe the authentication process on the Smart M.App platform and assist users with the authentication process. This is necessary because any interaction with the Foundation API can only occur if proper authentication has taken place.

 

Basic Requirements for Authentication

There are a few prerequisites to making requests to our Authentication service. The first of which is to ensure that your application is properly registered with the Smart M.App platform.

 

Registering Client Applications

Registering your client application must be done before you can perform any type of authentication using the Smart M.App platform. This is because your application must be issued a unique "client id". This identifier is what informs our Foundation API which application request are coming from. The general workflow for most using the Smart M.App platform is to create your application with our M.App Studio product. If M.App Studio was used to create your application, you should have received a unique client identifier.

 

Note: If you created your application using external sources, then you must register your application with M.App Exchange to be assigned a client id.

 

Registered User Authentication

Registration not only applies to applications, but users as well. Any individual that intends to use an application registered with the Smart M.App platform must also be registered themselves unless the application allow anonymous users. This can be done by going to the Hexagon Geospatial Store, and signing up for access. Once this is accomplished they must also be given access to your application, this is done by purchasing it from the Hexagon Geospatial store.

 

Request an Authentication token

The Foundation API uses OAuth 2.0 as our framework for authenticating applications attempting to interface with the API, as well as, the users using this application. If you have already have access to Smart M.App issued client identifier, please continue the steps below:

 

First users will need to make an HTTP request to the following endpoint:

GET https://mapp.hexagongeospatial.com/uaa/authorize

 

When making this request you will need to include the following querystring parameters:

Title Required Type Values Description
response_type true String "token" The value for this parameter should always be "token" as we use OAuth 2.0 Bearer tokens for our authentication.
client_id true String Any valid Smart M.App issued client identifier The value for this parameter should be the client identifier issued to your application by the Smart M.App platform.
redirect_uri true String Any valid URL This is URL that you want to return to after you have successfully authenticated the user for this application.

 

When a request is made to this endpoint the service will first validate your querystring parameters. This is mainly for ensuring you are using a valid client indentifier. Once the service has determined your querystring parameters are correct, we need to know who is currently using this application.

 

To do this the user will be redirected to the Hexagon Geospatial Store login page:

Hexagon Geospatial Store Login

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Here, the application's user must enter their email address and password respectively. Once the user has properly authenticated, the user will be redirected to the URL specified in the "redirect_uri" property. This will allow the user to continue using the specified application as a Smart M.App authenticated user. To allow the authenticated user to make valid request to the Foundation API, please see the "Using the Foundation API as an authenticated user" section.  

 

 

Using the Foundation API as an authenticated user

After your user has properly authenticated using the Hexagon Geospatial Store, the user will be redirected to the URL specified in the "redirect_uri" querystring parameter. Once this happens the orginal HTTP authentication request should resolve, and the HTTP response should now be avaiable. In the HTTP response, you should be able to retrieve the HTTP headers for the response. The HTTP response headers should look similar to the example below:

 

HTTP/1.1 302 Found
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: x-requested-with, Content-Type, X-CSRF-Token, Authorization
Access-Control-Allow-Methods: PUT, POST, PATCH, GET, OPTIONS, DELETE
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin
Access-Control-Max-Age: 3600
Cache-Control: no-cache
Cache-Control: no-store
Content-Language: en-US
Date: Fri, 04 Nov 2016 13:52:17 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: https://mapp.hexagongeospatial.com/mappchest/#/token?access_token=eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0Nzc5OTIwNTksInVzZXJfbmFtZSI6IjAyZWM3YmExLTAzYmMtNGI0Yy04ODAxLTAxMzBlMTg4YTJjYSIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiJdLCJqdGkiOiJmNWMzYjczZC1jMDY5LTQxZjEtYWQxZS1jNjczYzUwODhhZWYiLCJjbGllbnRfaWQiOiJtYXBwLWNoZXN0LTI1NzA2Iilsdfnosdodfbnlsdknsdlfksnvlsdknfosdvnsldvknsdlvknsdvodvnsdlvknsodpvisldgfvnsdlvknwic2NvcGUiOlsiQWxsIl19.BzjurLEdlEEBMQo_3I_VdL0waFi3HFSSITEL95rS8fX8g_5NvCxNlqfvA2lOmf3bwwe7KVcoRV4DhJLffRWYdKUT9kV14qxXAFizfhvdPU8bwAfbCWK4mJ3cIyC7Dh0DORACJHxf5yELb8GQD5Vdz8lLO_jnqRrAVHQeRisR3cvGe2aHdriAjjORLigLRgYHetPIRXAwieJ5BzqNtrJOzJ6GGrg0QeCiXLFj2PF_707YY1noBFT5bXO3i-TNK9bBwTujDGc3VKdfgdfgdfDFERHJRDGSfsfsdfsdgg1K3qUUANaQxPyhRh7NzeMXbtjjIWhFa9CzrslJizzqaJdO6v8n1PqptNGaM21SfT96_WTFAMNeHA&token_type=bearer&expires_in=761321&scope=&client_id=mapp-chest-23564516585&username=02ec7ba1-0sdfsd643bc-4b4c-885565401-0130e1886sd5f161dsa2ca
Pragma: no-cache
Server: nginx/1.8.1
X-Application-Context: application:9999
X-Frame-Options: SAMEORIGIN
Content-Length: 0
Connection: keep-alive

 

The HTTP Location header is what we use to store the URL of the "redirect_uri" property along with various querystring parameters that will be necessary for future request. The querystring parameters that are returned are described below:

Title Type Description
access_token String OAuth 2.0 authentication token, this token is essential to all future HTTP request made to Foundation API.
token_type String Describes the specific type of authentication token, for Foundation API we use "Bearer" token.
expires_in Integer Integer in seconds for how long the authentication token will be valid.
client_id String Smart M.App platform client identifier for the current application. 
username String Identifier for the current user.

 

Among these querystring parameters, the "access_token" parameter is essential to all future interaction with the Foundation API. To ensure all future requests to the Foundation API are made as an authenticated user, we will use the value for the "access_token" querystring parameter. We must assign this value to our HTTP Authorization header for all future requests made to the Foundation API. We must assign the token in the following format:

 

Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0Nzc5OTIwNTksInVzZXJfbmFtZSI6IjAyZWM3YmExLTAzYmMtNGI0Yy04ODAxLTAxMzBlMTg4YTJjYSIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiJdLCJqdGkiOiJmNWMzYjczZC1jMDY5LTQxZjEtYWQxZS1jNjczYzUwODhhZWYiLCJjbGllbnRfaWQiOiJtYXBwLWNoZXN0LTI1NzA2Iiwic2NvcGUiOlsiQsfsdf651sdf6sd5f4s6fsfdsdf6562654656584sfsdfGGSDFsdsfsdfsdDfsffsdf654654WxsIl19.BzjurLEdlEEBMQo_3I_VdL0waFi3HFSSITEL95rS8fX8g_5NvCxNlqfvA2lOmf3bwwe7KVcoRV4DhJLffRWYdKUT9kV14qxXAFizfhvdPU8bwAfbCWK4mJ3cIyC7Dh0DORACJHxf5yELb8GQD5Vdz8lLO_jnqRrAVHQeRisR3cvGe2aHdriAjjORLigLRgYHetPIRXAwieJ5BzqNtrJOzJ6GGrg0QeCiXLFj2PF_707YY1noBFT5bXO3i-TNK9bBwTujDGc3VK1K3qUUANaQxPyhRh7NzeMXbtjjIWhFa9CzrslJizzqaJdO6v8n1PqptNGaM21SfT96_WTFAMNeHA

 

Correct assignment of the OAuth 2.0 Bearer token to this header should make future requests headers look like the following example:

 

HTTP/1.1
Host: mapp.hexagongeospatial.com
Connection: keep-alive
Content-Length: 495
Accept: application/json, text/plain, */*
Origin: https://mapp.hexagongeospatial.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.71 Safari/537.36
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0Nzc5OTIwNTksInVzZXJfbmFtZSI6IjAyZWM3YmExLTAzYmMtNGI0Yy04ODAxLTAxMzBlMTg4YTJjYSIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiJdLCJqdGkiOiJmNWMzYjczZC1jMDY5LTQxZjEtYWQxZS1jNjczYzUwODhhZWYiLCJjbGllbnRfaWQiOiJtYXBwLWNoZXN0LTI1NzA2Iiwic2NvcGUiOlsiQWxsIl19.BzjurLEdlEEBMQo_3I_VdL0waFi3HFSSITEL95rS8fX8g_5NvCxNlqfvA2lOmf3bwwe7KVcoRV4DhJLffRWYdKUT9kV14qxXAFizfhvdPU8bwAfbCWK4mJ3cIyC7Dh0DORACJHxf5yELb8GQD5Vdz8lLO_jnqRrAVHQeRisR3cvGe2aHdriAjjORLigLRgYHetPIRXAwieJ5BzqNtrJOzJ6GGrg0QeCiXLFj2PF_707YY1noBFT5bXO3i-TNK9bBwTujDGc3VK1K3qUUANaQxPyhRh7NzeMXbtjjIWhFa9CzrslJizzqaJdO6v8n1PqptNGaM21SfT96_WTFAMNeHA
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.8  

 

Rate this article:
0 HexPoints
Did you find this article helpful? Yes No
1 Comment (1 New)
Hide Comment
Comments
by
on ‎11-21-2016 06:45 AM

It's not clear to me whether it's possible to write a script outside the Studio that has access to the Chest. I'd like to create an app in my own IDE instead of in the Studio. 

 

I've just created a ConsumerKey and want to obtain an access_token by calling 'https://mapp.hexagongeospatial.com/uaa/authorize?client_id=<ConsumerKey>&response_type=token&redirec...>', but I get an error message: 'Full authentication is required to access this resource'

 

 

 

Contributors