User Login and Accounts

Introduction

Our Accounts integration system is designed to create rich, engaging experiences for your visitors on their devices, while requiring the minimum amount of support from your integration team. Let us do the heavy lifting when it comes to managing the complex lifecycle of sessions, native UI, location tracking, and messaging.

We hope you'll use this system to build amazing experiences that wouldn't be possible until now. Help your visitors spend less time wondering where to go and what to do, and more time delighting them with a seamless mobile experience that can truly become an individual concierge.

App Level Login

For apps with visitor account login, visitors have access to all of the content in your app, except for visitor account-specific information.

In order to support customers who would like their Meridian-powered apps to require a login before any content in the app is accessible, the Meridian team has developed a new feature called app level login.

App level login is configured exactly like visitor account login, except that it's presented first, after the app finishes loading.

With app level login enabled in a white-label app, visitors will be presented with a login screen after the splash screen. Visitors won't be able to see any content in the app, unless they log in with a valid account ID and password.

Limitations of App Level Login

If your visitors have another way to access the content in your app, the app level login won't prevent them from seeing it.

If you have an older version of your app that doesn't have app level login, visitors with the old version will be able to access all of the content in your app even if you've enabled app level login in the new version. If you want to use app level login, it's best to add it to all published versions of your app.

It's important to know that your Meridian-powered app content can be accessed using the Meridian AppViewer app, if you have an account for that location or organization or a share link from someone who has an account.

There are other ways to access a location's data. The Meridian API is open, which means anyone with a location's app ID can request data for that location through the API. Android also has apps that can launch specific screens within other apps, which makes it possible to bypass the Meridian-powered app login screen.

User Login

Meridian's User Login feature uses a browser-like API to support creating logins for 3rd-party account systems. This will enable you to provide your visitors access to their user accounts in your organization.

Once logged in, the Meridian-powered app will store your visitors' Session IDs to keep them logged in. This works like website cookies stored in browsers.

Through Meridian's User Login API, you'll be able to provide services like:

  • Current room reservation
  • Reward/loyalty status
  • Appointment time and location

This article explains how User Login works, as well as how it uses the OAuth 2.0 protocol.

User Login Configuration

To get to the User Login form, in the Meridian Editor sidebar, click Settings. Under Settings, click Organization, and then click User Login.

The User Login fields will let you customize the login page your visitors will see in your Meridian-powered app.

Configuring Visitor Login in the Organization settings panel

USER LOGIN URL

The User Login URL is the location a user's username and password will be sent for the purposes of logging in.

USER LOGOUT URL

The User Logout URL will log a user out of your system.

USER INFO URL

Once a user has been authenticated, the User Info URL is the page that will load in the Meridian-powered app.

INBOX URL

If your system supports messages to your users, the Inbox URL will take the visitor to those messages.

INBOX COUNT URL

Use the Inbox Count URL to display the number of unread messages.

CREATE ACCOUNT URL

The Create Account URL is optional. If you want to let your visitors create an account through your Meridian-powered app, add the URL to your account creation page.

FORGOT PASSWORD URL

The Forgot Password URL is optional. If you want to let your visitors reset their passwords through your Meridian-powered app, add the URL to your password reset page.

LOGIN NAME LABEL

You can customize the Login Name Label as Username, User ID, or Email. This is the greyed-out text that appears in the Username field on the User Login screen.

LOGIN PROMPT

Login Prompt lets you create a customized message to visitors when they log in through your Meridian-powered app.

Login Experience

When you enable the User Login feature in your Meridian-powered app, an Account tab will be added to the Tab Bar.

When your visitors go to the account tab for the first time, they'll be presented with a Sign In screen:

Your visitors can enter their usernames and passwords to login to their accounts.

Logging in with OAuth

OAuth 2.0 is a web standard for authorizing apps and other web sites to access your secure content. OAuth is the mechanism that lets you use your Google or Twitter account to log in to other web sites, for example.

For a readable summary of the OAuth 2.0 protocol, please see Aaron Parecki's article "OAuth 2 Simplified".

Meridian's User Login feature uses the OAuth 2.0 protocol to handle the exchange of credentials for logging in. This protocol is defined by the OAuth 2.0 Resource Owner Password Flow, as described in this flow chart in the OAuth 2.0 spec.

Resource Owner Password is designed to give apps you control, such as your Meridian-powered app, access to other data you control. This is similar to HTTP Basic Auth, but it's more secure.

The following articles provide more information about using the OAuth 2 protocol in this way:

User Login API Flow

In your Meridian-powered app, after a visitor enters a username and password, the app will send an HTTP Post request to Login URL you defined in the Meridian Editor:

POST /oauth/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

client_id=meridian&grant;_type=password&username;=jsmith&password;=mypass&device;_id=b312hb12&app;_id=1923082

POST defines the OAuth path. Host defines the server. Both of these are customizable. In order for this to work, your server must support SSL. When your server receives this, it will respond with a JSON document describing the outcome, whether the visitor successfully logged in or not:

{
    "access_token": "f2288c2b-1d08-4aac-a210-d62c0901f915",
    "token_type": "bearer",
    "refresh_token": "3f94522d-5a5a-4a22-bc85-f5f5a56920b4",
    "expires_in": 43199
}

If the login operation failed, you can send back an explanation message:

{
    "error": "invalid_grant",
    "error_description": "System error: fail to process username & password combination."
}

Following a successful login, when the client notices that the access_token has expired, it will attempt to use the long-lived refresh_token to get a new one:

POST /oauth/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

client_id=meridian&grant;_type=refresh_token&refresh;_token=3f94522d-5a5a-4a22-bc85-f5f5a56920b4&device;_id=b312hb12&app;_id=1923082

The response returns a new valid access_token that will be used for subsequent requests from the client.

There are many language and framework-specific OAuth libraries you can use to implement these server-side API calls, as listed on the OAuth 2.0 site.

Account Home

Once a user is logged in, the Account tab will no longer displays the Login form. Instead, it will display some basic information about the user:

This information is fetched from a configurable 3rd-party URL:

POST /user_info HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer f2288c2b-1d08-4aac-a210-d62c0901f915

device_id=b312hb12&app;_id=1923082

The access_token received during login is used as the Bearer token in the Authorization HTTP header. For OAuth 2, this is the standard way to access resources requiring authentication.

Upon a successful login, the server responds with a JSON document describing the data it would like to present to the user:

{
    "name": "Nick Newton",
    "info": "123,000 Points",
    "badge": "President",
    "image": "http://example.com/user_avatar.png",
    "links": [
        {
            "title": "My Offers",
            "link": "pages/345"
        },
        {
            "title": "My Room",
            "link": "placemarks/346_2325"
        },
    ]
}

All top-level fields are optional.

The **link** value is the ID of a Page or Placemark for your location in the Meridian Editor. If you want to link to an external URL (i.e., one that begins with 'http://'), you'll first create a Meridian page with a type **Web Page** with an external URL. Mark that page as **Requires Login** if the content at the external URL: requires the user to be logged in to their account.

The URL is fetched every time the Account page is displayed, and if any values change in the response, then the UI will be updated appropriately.

Logging Out

When the user touches the Log Out button, the Meridian-powered app makes a call to revoke the access_token:

POST /oauth/revoke HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

token=f2288c2b-1d08-4aac-a210-d62c0901f915&device;_id=b312hb12&app;_id=1923082

The log out process provides a good opportunity for the server to clean up any associated user resources.

Using Accounts in the Sandbox

When the user is logged into your Meridian-powered app, you'll probably want to present them with a more personalized experience. The easiest way to do this is by writing custom pages using the App Sandbox.

Let's say you want to create a page called "My Reservation" that will display a user's current hotel room number and directions to the room.

The "My Reservation" page will need to be created from your server in the same way your other web pages are, because Meridian doesn't have access to your rooms database.

For example, here's an example of a URL you might publish:

https://example.com/my_reservation?token=f2288c2b-1d08-4aac-a210-d62c0901f915&device_id=b312hb12

On every Sandbox page that's marked "requires login", the access request uses the "Authorization" HTTP header. The access_token isn't appended to the URL.

The above URL might respond with some HTML that describe's the visitor's room:

    
        

Hello John Smith, your room number is 1546.

As you can see, you can customize your Meridian-powered app, so that your visitors could easily do things such as looking up their reservations and getting directions to their rooms.