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.
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 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.
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.
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:
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.
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