Skip to content

Update README.md #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ctrese wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update README.md #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 26 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,54 @@ This repo contains a Predix Mobile app demonstrating a simple offline login conf

It covers these key aspects of offline login support:

* Webapp setup
* Web app setup
* First time offline authentication password setup
* Authentication offline
* Management of a users offline password
* Managing a user's offline password

### Step 0 - Prerequisites
### Prerequisites

It is assumed you already have a Predix Mobile cloud services installation, have installed the Predix Mobile command line tool, and have installed a Predix Mobile iOS Container, following the Getting Started examples for those repos.

### Step 1 - Webapp setup
This example assumes that your Predix Mobile iOS Container sample app `info.plist` is configured to have `pmapp_name` as `Sample1` and `pmapp_version` as `1.0`. See the Predix Mobile iOS Container sample app repo for more information on this configuration.

This repo contains two webapps, and a Predix Mobile app configuration file. The two webapps should be published to your Predix Mobile cloud, and the Predix Mobile app configuration file should be defined using the pm tool.
### Step 1 - Web app setup

The script "setup-demo.sh" has been provided to quickly perform these steps for you, if you desire.
This repo contains two web apps and a Predix Mobile app configuration file. The two web apps should be published to your Predix Mobile cloud, and the Predix Mobile app configuration file should be defined using the pm tool.

This example assumes you have your Predix Mobile iOS Container sample app info.plist configured to have "pmapp_name" as "Sample1" and "pmapp_version" as "1.0". See the Predix Mobile iOS Container sample app repo for more information on this configuration.
You can run the script `setup-demo.sh` to quickly perform these steps for you.

### Step 2 - First time offline authentication password setup

With your machine still connected to the internet, run your Predix Mobile container. After the normal online login, you will see the first time setup page for your offline password.
1. With your machine still connected to the internet, run your Predix Mobile container. After the normal online login, you will see the first time setup page for your offline password.

What's happening here is the system has read the configration for this Predix Mobile app, and has identified that an offline login webapp has been configured. Further, it has identified that this system has no offline password configured, so it has initialized the setup step of offline login by calling the web page defined in the offline login webapp's "setup" element.
The system has read the configration for this Predix Mobile app, and it has identified that an offline login web app has been configured. It has also identified that this system has no offline password configured, so it has initialized the setup step of offline login by calling the web page defined in the offline login web app's `setup` element.

At this time, you should enter an initial offline password, and tap OK. The system will then continue onto the main webapp for this demo.
2. Enter an initial offline password, and tap OK. The system will then continue onto the main web app for this demo.

### Step 3 - Authentication offline

Now that you have successfully authenticated online, and setup your offline password, the next step is to see authentication offline in action.

Disconnect your device or computer from the network, then tap the Logout button.
1. Disconnect your device or computer from the network and tap the Logout button.

You will then see the Offline Login page.
The Offline Login page is displayed.

Here you can enter the password you setup previously to authentication in offline mode.
2. Enter the password you setup previously to authentication in offline mode.

Once you've logged in offline, reconnect your device or computer to the network, and tap Logout again to re-login online.
3. Once you've logged in offline, reconnect your device or computer to the network, and tap Logout again to re-login online.

### Step 4 - Management of a users offline password
### Step 4 - Managing a user's offline password

After logging back in to the system in Online mode, you can try changing your offline password. The Update Offline Password button will initialize this component, taking you to a basic "change password" type page. For security reasons, you can only change your offline password while authenticated online.
After logging back in to the system in Online mode, you can try changing your offline password.

The Update Offline Password button will initialize this component, taking you to a basic `change password` page. For security reasons, you can only change your offline password while authenticated online.

## Technical details

### The Predix Mobile app definition

The app.json file for this example is:
The `app.json` file for this example is:

{
"name": "Sample1",
Expand All @@ -62,13 +64,13 @@ The app.json file for this example is:
}
}

Note "starter" and "offline" entries. The "starter" you may be familiar with from other examples. It defines the main webapp that the system starts after authentication.
Note "starter" and "offline" entries. The "starter" you may be familiar with from other examples. It defines the main web app that the system starts after authentication.

The "offline" entry specifies the webapp that is responsible for offline authentication.
The "offline" entry specifies the web app that is responsible for offline authentication.

### The Offline webapp

The webapp.json file for the offline-login webapp in this example is:
The `webapp.json` file for the offline-login web app in this example is:

{
"name": "offline-login",
Expand All @@ -80,18 +82,18 @@ The webapp.json file for the offline-login webapp in this example is:
"output-folder": "./dist-zip/"
}

While similar to all webapp.json files, you can see here, the additional entries for "setup" and "update". These are the web pages called for first time initialization of the user's offline password, and to change the user's password. Also note, the "main" entry is the web page used for offline authentication itself.
While this is similar to all `webapp.json files`, there are additional entries for "setup" and "update". These are the web pages called for first time initialization of the user's offline password, and to change the user's password. Also, the "main" entry is the web page used for offline authentication itself.

The offline webapp has some unique responsibilities, and requirements:
The offline web app has some unique responsibilities, and requirements:

* It's run in a special locked-down mode of the container. The only container services this webapp can call are the auth and logging services.
* It is run in a special locked-down mode of the container. The only container services this web app can call are the auth and logging services.
* It must support three web pages for authentication, setup, and update.
* When these pages are called, they are passed a one-time token. The auth service calls back to the container must include this token as part of it's path.
* Based on the functionality of the page called, only certain functions of the auth service are allowed. For example, if the container is expecting authentication, the page cannot call the auth service to update the offline password.

## Further understanding

Please review the javascript code in each of the offline-login webapp pages, and in the demo-offline-app. Here you will find examples of not only calling the auth service to support offline login, but also examples of these services:
Please review the javascript code in each of the offline-login web app pages, and in the demo-offline-app. Here you will find examples of calling the auth service to support offline login, and also examples of these services:

* log -- log service is called to send JavaScript console logs to the container's logging system.
* boot -- boot/research is called for logging out.
Expand Down