When a user has an account, password and a license to the mobile app, they must authenticate with an identity provider such as Salesforce. There are scenarios such as two-factor authorization, password resets, when a users account is marked as inactive, that also need to handled by the identify provider.
When a Users account is deactivated, their access and refresh token(s) are revoked. The user will immediately be sign out of the app, data cleared and redirected to the login screen.
When an identity providers uses OAuth or OpenID for authentication and authorization (Salesforce, Microsoft), before they sign in, a user will be prompted with a permission based dialog like: 'i360Mobile' Wants to Use 'salesforce.com' to Sign In. This allows the app and website to share information about you. The reason this prompts the user is because the sign in uses cookies and could allow a single sign on experience between applications. You can learn more about AFWebAuthenticationSession at https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession 241 but in short the purpose of this prompt is to protect user’s privacy.
Logging Out
- When a user logs out of the app, all the local data will be cleared. This includes information saved the "file system", in memory and in draft state. A warning message will be shown to the user to information will be cleared prior to signing out.
- Be sure all items are saved remotely prior to logging out or updating the app.
MarketSharp
Session
In order to log into MarketSharp, the company needs to be on the named license format. If they are not, they will receive a message to contact their MarketSharp Account Representative to convert to the Named License Format.
If the company is in the named license format, the next check will be whether they have a license assigned to them or not. A message will appear indicating this. Users without a license will not be able to log in. Users that have a license revoked, will stay logged in, but will not be able to receive any new data and will see the message of not having a license assigned often.
Upon logging in, the user will receive both an access token and a refresh token. The access token expires after 365 days. The refresh token lasts 396 days. The access token is used for every request made to the MarketSharp server (i.e. get current user or get the appointments in the 30 day daterange). Once the access token expires, the initial request will fail. The refresh token will be used to renew the access token. Not only will the access token be renewed, but the user will also receive a new refresh token upon expiration of the access token. Once the tokens have been renewed, the initial request will be attempted again.
What this means is that if a user uses the app at least once a year they will theoretically never have to log into the app.
There is a small chance that upon the expiration of the access token, the renewal may fail. The result of this is the user is logged out. These would be considered more edge case scenarios. If a user needs to be removed from the app, removing the user's license will revoke their access.
Licenses and Active Users
When a user has their license revoked and tries to login or get data, they will receive the error: "You do not have a license assigned. Please contact your system administrator to have a license assigned to you." After the message, the user will be automatically be logged out after 5 seconds.
Knows Errors
Error: We're sorry, this application does not support your current version of MarketSharp. Please have your account't System Admin contact your MarketSharp Account Representative
Solution: The MarketSharp organization is not on named licenses and needs updated to named licenses to sign in.
Salesforce
Access to Salesforce is provided via a Connected App. Once the user signs in, users are prompted to allow our app to have access to Salesforce.
Session
By default, a users session is valid for 24 hours. However, there is a refresh token that is used behind the scenes to automatically refresh the users session so they do not have to type in their password everyday. A users session should always be valid until they users logs out.
However, a users session can manually be revoked be going to Setup > Users > Find the user want to revoke > OAuth Connected Apps > then click 'Revoke' for the mobile app. This will invalidate the users Access Token and Refresh Token and will force the the user to log out and be redirected to the home screen.
When a session has expired, all requests will fail. Thus, a new access token needs to be used. Using the refresh token, get a new access token and reply any previously failed requests since the users session is now valid. When a users access token and refresh token are revoked (i.e. deactivating the users account), the user must be signed out of the app since they no longer have access.
Licenses and Active Users
When a user has their license revoked while signed into the app, they will receive the error: "INVALID_REFRESH_TOKEN: Refresh token is no longer valid." After the message, the user will be automatically be logged out after 5 seconds.
Notes
- Changing password on desktop does not require the user on mobile to immediately sign out and back in again. Next time the user signs into the mobile app, they will have to use their most up to date password.
Supported Identity Providers
- Salesforce (production and sandbox orgs)
- MarketSharp
Links
- Connected Apps: https://help.salesforce.com/articleView?id=connected_app_about.htm&type=5
- Session Policies: https://help.salesforce.com/articleViewid=connected_app_manage_session_policies.htm&type=5
- Refresh Tokens: https://auth0.com/learn/refresh-tokens/
Testing
- Ensure that after an app has been installed for at least 24 hours, the session is still valid, user doesn't have to sign in and back out again.
- Revoke a users OAuth Connected Apps access (see users Profile, steps above). After their access has been revoked, refreshing any data in the mobile app should sign the user out as their access and refresh tokens are no longer valid.
-
Can test refreshing Access Token from removing user session from Settings > Session Management for the user
-
Can test invalid Refresh Tokens by going to Settings > Users and User > an revoking the OAuth Connected Apps for the user