User Authentication
Feature Introduction
If your AR content is only available for certain group of people and you want to add some restrictions as what kind of content people can see, you can implement authentication mechanism in your layer.
The Layar Reality Browser (including Layar Player) behaves like a normal web browser, honoring sending/storing of cookies in the central cookie store of the device. Developers can make use of cookies to identify valid users.
Key Steps to Implement
Configure the "additional settings" tab on the publishing site
The following settings can be used to manage the user authentication flow. They are available under the "additional settings" tab of the layer editing page on the publishing site.
| Key | Value | Example | Explanation |
|---|---|---|---|
| valid cookie required (optional) | boolean | false (by default) | Indicates whether authentication is required prior to launching the layer. If it is checked (true), the layar client will firstly check whether there is a cookie, if not, it will redirect the user to the login page defined in "URL for layer settings page". By default it is unchecked(false), it means the layer can be launched without authentication. |
| URL for layer settings page(required when 'Enable additional settings' is checked) | URL | https://m.hyves.nl/layar/signin | The URL to call for the webview to authenticate the user. Usually https. NOTE that this URL needs to be on the same domain as the poiURL (it's just a cookie we're using, so all normal browser cookie rules apply), different sub domains are allowed. |
| Description for button (required when 'Enable additional settings' is checked) | string | User Authentication | A description is shown on top of the button which explains what this button is about. |
| Button label(required when 'Enable additional settings' is checked) | string | login | The text that is displayed on the button itself. |
| Replace filters(optional) | boolean | false (by default) | Indicates whether the web page launched by 'URL for layer settings page' will replace the entire filter settings defined under "Filters" tab. If it is checked (true), the 'URL for layer settings page' will appear under the filter settings button in the AR view. By default, it is unchecked (false). |
| Parameters added in request | string | https://custom.layar.nl/login.php?lon=4.933156943889342&lat=52.373196116536235 | A group of preset parameters that can be added to the request when the button is clicked. The possible multiple values are "latitude", "longitude", "country code", "accuracy", "language", "API version". |
Special Error Code in getPOIs Response
| Key | Value | Example | Explanation |
|---|---|---|---|
| errorCode | Integer | "errorCode": 30 |
The errorCode for the response. - 30: Indicating that this layer requires authentication. When this error code is returned in getPOI response, the client should open the webview at the 'URL for layer settings page' defined by the layer. |
| errorString | String | "errorString": "auth required" |
The corresponding errorString will not be displayed to the user. |
Cookie Management in Layar
The Layar Reality Browser (including Layar Player) behaves like a normal web browser, honoring sending/storing of cookies in the central cookie store of the device:
- Whenever a URL is opened for which the domain corresponds to that of a cookie, the cookie is to be sent.
- Whenever a cookie is received, it is stored within the domain where it comes from.
- The layar client obeys cookie validation rules, i.e. cookies can only be stored if the domain they come from corresponds to the domain in the cookie.
Please NOTE that if a cookie is set from outside of Layar reality browser (or the app which implements the layar Player), it will NOT be sent to the Layar client (or layar Player) in the getPOI request. For instance, a user is authenticated in an android app which implements a layar intent to launch a particular layer in Layar Reality browser, the cookie set will not be sent to the layar client.
On the Layar server side, for each layer, "poiDomainURL" parameter is used for knowing what domain the getPOI request/response belongs to for sending/receiving cookies.
The layar client complies to the following requirements:
- When there is a cookie in the general cookie store for the poiDomainURL, that cookie gets sent in EVERY getPOI request for that layer.
- For every HTTP request other than requests to Layar server (i.e. directly to external parties), the client checks if there are cookies stored for the corresponding domain and if so, send the cookie, if valid. Explicitly this includes: requests in any WebView inside the app (the layer additional settings page, any webview coming from a layer action or POI action) and async or text/plain HTTP requests coming from layer or POI actions.
- If a cookie is received in the getPOI response, it is stored as belonging to the poiDomainURL. That way it will get sent in subsequent getPOI requests for that layer and any other direct HTTP request to that domain.
- If a cookie is received in any response to a direct HTTP request to a 3rd party domain, it is stored in the general cookie store.
- If authRequired is true in the layer details, then the client redirects the user to authURL web page if no valid cookie is available for the poiDomainURL.
- The cookies will be sent/stored by the layar clients regardless whether the layer has 'additional settings' enabled(regardless whether authURL set or not).
General Interactive Flow
As mentioned above, Layers may have a new field 'URL for layer settings page' in the definition to indicate support for authentication. This is the login URL where the Layar client should direct the webview for authentication. This has to be in the same domain as the layer provider's getPOI url(defined under API endpoint URL). The layer provider should set a cookie that applies to layer provider's getPOI url.
- There are 4 ways to start the authentication:
- If the 'valid cookie required' field of a layer is set to 'true', the authentication page will automatically be called whenever a user opens up the layer without a valid cookie. If there is a valid cookie for the layer, the usual GetPOI request is sent with the cookie and no redirect to the authentication page is needed.
- As a response to the GetPOI request, a layer provider can indicate that authentication is needed. For example, if 'valid cookie required' is false, the client will just send the getPOI request. The layer provider can choose to require authentication by returning the errorCode 30. Also the cookie sent might not be valid anymore. Also in such case the layer provider can send back errorCode 30.
- The layer provider can choose to use the 'URL for layer settings page' also in an action of a POI, which will automatically direct the user to the login page.
- The user can start authentication using the special button pointing to the 'URL for layer settings page' in a layer. The button can be found on filter settings page, right after all the filter settings.
Please NOTE the following situation:
If 'show filter before loading layer' defined under the Filters tab is true (checked) and the 'URL for layer settings page' is used for user authentication:
- if 'replace filters' is true, 'URL for layer settings page' is always shown when launching the layer. It will rule the value of 'valid cookie required'. Pressing the filter settings button will show the web page associated with 'URL for layer settings page'.
- If 'replace filters' is false, then the button to link to the 'URL for layer settings page' is shown in the filter settings, after all the other filters. The 'Description for button' text is shown above the button, the button itself uses the 'Button label'.
- The steps that follow the redirect in a webview to the authentication page are:
- The Login url ('URL for layer settings page') is opened in an embedded browser. This page(s) authenticates the user (any mechanism can be used, like self hosted authentication/OAuth etc.) and can take him to a 'home page' that can have more (dynamic) settings to choose for the layer. Any no. of html pages can be used with flows between them.
- The user is returned to the Layar view he was in when the embedded browser is redirected to a layar intent (layar://thelayer/?action=refresh). Visiting this layar intent means that the authentication (and possibly configuration) of layer is complete and user can return to Layar app. The provider needs to set cookies that apply to the provider's getPOI url before visiting this layar intent.
- When the layar intent is called, all cookies that apply to getPOI url (only) are stored in the layer( cookie expiry is to be handled by Layar app, according to cookie spec). The cookie might replace previous cookies that were set, e.g. the user was asked to log in again because a cookie that was sent was not valid. This is the example above for errorCode 30. User-Agent and Cookies are sent in the HTTP headers as for all other Layar requests.
- The stored cookies are sent to the layarservice app for all future getPOI requests. The layarservice getPOI handler forwards all cookies it receives to the layer provider's getPOI url so that the request can be identified with a particular user session. NOTE that redirects are not allowed on the getPOI request as subsequent requests will not pass the cookie for security reasons. The GetPOI URL needs to be on the same domain as the 'URL for layer settings page'.
The following diagram shows the user authentication flow when "valid cookie required" is true and no cookie is set when the layer is launched. The "Authentication" refers to the "URL for layer settings page" and should be managed by third party developers, for instance it can be implemented as a part of the POI server. Please NOTE that the Layar server is managing the communication between the Layar Client and third party POI server in real life. It is not mentioned in the diagram below for simplicity.
Under the following two situations, layar client directly sends the getPOI request to the POI URL (POI server) without visiting the authentication page firstly. The POI server needs to check whether there is a valid cookie or not and provide the appropriate response accordingly.
- "Valid Cookie Required" is true (checked) and Layar client detects a cookie set for the corresponding domain
- "Valid Cookie Required" is false (unchecked)
Please NOTE that the client app has full support for https (layer provider can choose to use this for additional security). If the getPOI url of layer provider is https, the client app to layar service getPOIs call will also be over https. The Layar server will forward the call also over https.
Create custom filter settings page
Besides user authentication, developers can use 'URL for layer settings page' under "Additional settings" tab for other purposes, such as a custom filter settings page. The mechanism mentioned above applies to this use case. Basically, developers need to store all the filter settings in cookies so that they will be passed in subsequent getPOIs requests. In the script which returns POI response can use these filters to determine which POIs should be returned.
On the "Additional settings" page, normally "Replace filters" is checked to replace filters provided by Layar. If "Valid cookie required" is true, the custom filter page is shown first when no valid cookie is available. This can be used when you want users to configure the filter settings first.
The following diagram shows the flow of using custom filters when "valid cookie required" is false and "Replace filters" is true. The "Custom Filters" refers to the "URL for layer settings page".
