Understanding Jive Mobile's SSO Compliance

    Introduction

    This document supplements the information available in Security for Jive Mobile.  While available to all Jive Mobile licensees running Jive 5.0.1+, this approach to mobile authentication is most appropriate when:

    1. The instance is for internal employees.  Note that Device Registration is the default for internal communities as of 5.0.1.
    2. A SSO system is in place (SAML, Kerberos, etc.).  The goal with this configuration is compliance with SSO systems, not actual mobile participation in the direct SSO flow.  The benefits to this approach are:
      • No user credentials flow through Jive.
      • The end user experience is efficient and maximizes the potential for usage.  We have found that challenging users for credentials every time they wish to quickly check on a notification or post an update dramatically hinders their willingness to participate.
      • Access from a given device can be revoked remotely.  Note that only the end user can revoke his/her own tokens as it's done via the user's Preferences page.  There is not utility for managing all access tokens that's available to the Admin.  However, if a users Jive account is deactivated, the tokens registered for that user are automatically invalidated.  It is important to note that merely deactivating the user in your Identity Provider system is insufficient; the account in Jive must be deactivated as the token validation flow does not ping the IDP every time.
    3. The instance is hosted by Jive.  On-premise customers can certainly utilize this as well but may also wish to consider the pros/cons outlined in Mobile On-Premise Plugin for Jive 5 & 6.


    Note that when Jive Mobile is configured for this mode of authentication it will apply to all devices and access means (iPhone native and mobile web, Android native and mobile web, BlackBerry mobile web, iPad mobile web). 


    Changing from this mode of authentication, enabling the passcode option, or changing any of the default property values can all be achieved by entering a case in your organization's Jive Community group.


    Device Registration

    A key aspect of the registration flow is an understanding of the "tokens" at work in this system.  To clarify:

    1. Activation token - this is a one-time use token that is generated in the Jive UI for the user to enter into the Mobile UI in the browser they are trying to authorize. 
      • This token’s default expiration period is 20 minutes and is configurable.
      • When Mobile takes the one-time use token, it exchanges it with the Jive instance for a request token.
    2. Refresh token - is a non-expiring token that is presented by the mobile client each time it wishes to authenticate. 
      • Abstractly, this can be thought of as equivalent to a "remember me" cookie with no expiration date.  Unlike "remember me", (1) it contains no actual credentials and (2) it can be revoked remotely without changing any passwords.
    3. Access token - is the equivalent of the "session ID".  That is, it's a token that is returned by the Jive instance in response to a valid request token, and is used to authenticate every subsequent content request. 
      • The access token has a limited validity period on the Jive side, which can be configured to be as little as an hour. 

     

    Example mobile device registration data flow:

    1. Jive user generates activation token in the Jive UI.
    2. Jive user loads the Jive Mobile app and enters the token.
    3. The token is transmitted via the Mobile Gateway to the Jive instance – if it is valid, then a valid refresh token is returned to the mobile client.
    4. The mobile app stores the refresh token locally.  When it receives any HTTP 401 (unauthorized) responses to any Core API requests, it submits the request token to the Jive instance via the Mobile Gateway.
    5. If the refresh token is valid, the Jive instance returns an access token.
    6. The access token is stored in session scope by the mobile app, and submitted along with every Core API request.


    Activation token:

    prefs.png                    


    Entry form on the device:

    entry.png


    Jive oAuth2 Provider Services

    The following details describe the oAuth2 services that provide the backing for mobile device registration.

     

    Four categories of properties:

    • Activation Settings
    • OAuth2 Token Settings
    • Token Renewal Settings
    • Expired Token Cleanup Settings

     

    Activation Settings

    These properties control the generation of activation codes used for oAuth pairings, before any oauth credentials are created.

    Jive PropertyDefaultDescription
    1. jive.oauth.activation.code.length

    8

    The length of the activation code to generate, minimum 5, maximum 24

    1. jive.oauth.activation.code.possible_chars

    0123456789

    The set of characters to use when building a random activation code. Limited to alpha numeric.

    1. jive.oauth.activation.code.expires_minutes

    20

    How long an activation code will be valid.

     

    OAuth2 Token Settings

    These properties configure the mechanisms that manage OAuth2 tokens, specifically token creation and token lifespan.

    Jive PropertyDefaultDescription
    1. jive.oauth.access_token.size_bytes

    64

    The size, in bytes, of each randomly generated access token.

    1. jive.oauth.access_token.ttl_hours

    12

    The duration, in hours, an access token is valid for.

    1. jive.oauth.refresh_token.ttl_hours

    17532

    The duration, in hours, a refresh token is valid for. The default value is about 2 years.

     

     

    Token Renewal Settings

    These properties concern the renewal of active or recently expired OAuth refresh tokens. Renewal entails the issuance of a new refresh token for the same client id.

    Jive PropertyDefaultDescription
    1. jive.oauth.refresh_token.early_renewal_hours

    336

    A user can renew an activation this many hours before it expires. A value of zero means that activations can only be renewed after they expire, while a negative value disables this feature.

     

    Expired Token Cleanup Settings

    These properties deal with the automated clean up of expired data.

    Jive PropertyDefaultDescription
    1. jive.oauth.task.expire.frequency_hours

    4

    How often the expiry task runs. If this value is set to 0 or is negative, it will run every 90 seconds. When this task runs, expired data is removed. Expired access tokens and activation codes are removed if they are expired.

    1. jive.oauth.refresh_token.remove_delay_hours

    168

    After a refresh token expires, it will linger in the database. After this number of hours, these refresh tokens and the corresponding client id & secret will be removed. The default value is approximately 7 days.

    1. jive.oauth.expired_pairings.remove_delay_hours

    48

    If a pairing is created, but is never activated, the expired record will linger in the database. After this number of hours, the pairing will be removed.

     

     
    Passcode

    To supplement the Mobile Device Registration Flow, a Jive instance can require the user to enter a passcode to unlock access to the app after a specified period of inactivity. 

    • For Jive 5.0.1 - 5.0.3 the creation and storage of the passcode is done client-side.  This is effective for casual access attempts and is intended to protect the app until the user revokes the device's access manually via the Preferences page.
    • For Jive 5.0.4+, Jive shifted the creation, storage, and validation of the passcode server-side to eliminate vulnerability to client-side attacks (i.e., script or storage manipulation) that can bypass a client-side passcode.  This document focuses on the server-side passcode implementation as it is the go-forward process.  Note that customers migrating from client-side to server-side will need to inform their users of the change as a new token and passcode will be needed.

     

    Changes to the activation process:

    • At the time the user requests a device activation code from Jive, the user is also required to enter a passcode.

    passcode.png

     

     

    Changes to data access from mobile client:

    • In addition to expiring after its normal interval, the access token is locked when it is first created, and after a configurable period of inactivity (default 20 minutes)
    • If the access token is locked, any requests made with that access token will be rejected with a 401 that includes a code indicating the access token is locked.
    • Once the access token has been locked, it can only be unlocked by submitting an unlock request.  This request consists of an HMAC-SHA256 encoding of the refresh token combined with the passcode.
    • When the mobile client receives a 401 “locked” error response, it will lock the client interface and require that the passcode be entered before proceeding. 
      • If the passcode + refresh token combination is not validated by the Jive instance, the user cannot proceed.
      • After a configurable number of consecutive failed unlock requests, the access token is locked permanently.  The user will be required to re-activate the device from the Jive instance to regain mobile access.

     

    The figure below illustrates data flow with server-side passcode enabled.  Though it is not illustrated, the Jive Mobile Gateway mediates all requests between the Mobile Client and the Jive instance.

    PasscodeFlow.png


    Data Security

    • On the Jive side, the passcode is stored encrypted with SHA256+HMAC.
    • The passcode is never cached or stored by the mobile client.
    • All traffic between the Jive Mobile Gateway and mobile clients is sent over HTTPS.  If the Jive instance configures communication with the Jive Mobile Gateway over HTTPS (recommended), then all traffic between the Gateway and Jive instance is also encrypted.

     

    Passcode Configuration

    The following parameters can be configured for the secure passcode feature:

    • Whether it is enabled or disabled for mobile devices
    • Minimum number of characters for the passcode
    • Number of minutes idle before the access token is locked and passcode is required
    • Number of invalid requests before permanently locking the passcode


     

    Jive PropertyDefault Value
    jive.oauth.passcodefalse
    jive.oauth.passcode.timeout10
    jive.oauth.passcode.lockout10
    jive.oauth.passcode.minlength5