Core V3 API - Run-As Feature & Signed Add-Ons

Version 7

    This feature supports use cases where you want to use a single service account to authenticate to Jive from some third party server, but then have API requests performed as if they were originally requested by a particular impersonated Jive user.  This implies a couple of important things:

    • Entitlements of the impersonated user control what content is visible, and what things can be changed.
    • New or updated content will reflect the impersonated user as the author.

    The service account must be a Full Access admin.

       

     

    By default, the feature disabled.  It is enabled by setting Jive property jive.api.run_as.strategies to a comma-delimited list of identification strategies that may be used to map incoming identities to Jive users.  Then, a client app includes an X-Jive-Run-As HTTP header, whose value is a strategy name and corresponding token.  Out of the box, four strategies are available: (example header values are in blue)

    • uri - a core v3 person uri - uri /people/1234
    • email - an email addresss - email john.doe@jive.jiveon.com
    • userid - a Jive userid - userid 1234
    • username - a Jive username - username john_doe

    † The uri strategy must be enabled to use the JavaScript Request.executeAs() method.

     

    Example values of jive.api.run_as.strategies

    • "" (no value) - The run-as capability is disabled, the X-Jive-Run-As header is ignored.
    • "uri" - Only the uri strategy is enabled
    • "email,userid" - The email and userid strategies are enabled.

     

    If something goes wrong in handling the run-as operation, messages are recorded in the log [com.jivesoftware.api.core.runas.CoreApiRunAsFilter], and the response JSON will contain a numeric "code" [4048-4052]:

     

    FaultCodeLog LevelLog MessageNotes
    Feature disabled4048WARNDenying request with X-Jive-Run-As header: Feature is disabledNo run-as strategies are enabled
    Insufficient privileges4049WARNDenying request with X-Jive-Run-As header to user [username]: Insufficient privilegesAn admin attempted to run-as another admin, with higher privileges.
    Parse exception4050WARNUnable to parse X-Jive-Run-As header: header_valueThe header value didn't seem to be formatted correctly
    Unknown strategy4051INFOUnknown X-Jive-Run-As strategy: strategyThe run-as strategy is unsupported or not enabled
    User not found4052DEBUG

    User not found using strategy 'strategy': identifier

     

    Using Run-As with Core API - Standalone

    In the event you are just making a call to APIs and would like to leverage the Run-As feature, you will need to do the following:

    1. Setup a service account user that has Full Access permissions.
    2. Configure the jive.api.run_as.strategies property in the Admin Console > System > Management > System Properties (see above)
    3. When making the service call, you will need to pass an additional header in the UI:
      • X-Jive-Run-As [INSERT VALUE HERE]
        • if strategy is email, you would insert the user's email (i.e. bob@bob.com)
        • if strategy is userid, you would insert the user's Jive ID (i.e. 1234)
        • if strategy is username, you would insert the user's username (i.e. bob)
    4. Send the command, and validate that Run-As completed as intended.

     

    Using Run-As with a Jive Add-On

    Setting up your Add-On to use the Run-As feature is a bit more straight forward and easier to manage.

     

    1. Create your Add-On Base, whether that is through the Jive SDK (Node) or the Jive SDK (Java) Jersey
    2. Get the Service Signature for your Jive Instance using the UUID for your Add:
      Visit:  https://<YOUR INSTANCE URL>/addon-services!input.jspa
      signing-package.png
      • Signature will be displayed after putting in your Add-On's UUID (located in your meta.json file's id property) and clicking Sign.
        • It will look something like (xxxxxxxxxxxxxxxxxxxxxxxxxxx=) (27 alphanumerics including an equal sign)
    3. Make sure the following stanza appears at the top of your definition.json and include the desired "Run-As" Strategy (see above for values)
      Note:  If you are using the Jive Node SDK, see jiveclientconfiguration.json on how to set your jiveServiceSignature such that it remains between builds.

          "integrationUser": {

              "systemAdmin": true,

              "jiveServiceSignature" : "xxxxxxxxxxxxxxxxxxxxxxxxxxx=",

              "runAsStrategy" : "userid"

          }

        
    4. When you install your add-on, your add-on will be given an OAuth2 Token that it can use to trade-in to get an Access Token.   This will be stored in your "community" (node store) or "jiveInstance" (jiveInstanceProvider) object.  To add this token to the request you need to add an additional header to the request (you will still also need to add the X-Jive-Run-As header, see above):

    Authorization: Bearer <YOUR ACCESS TOKEN>

       

     

    For any further questions about the Run-As feature, please feel free to reach out on this document.

     

    For a working example, you can check out the Jive SDK (Node) => Auth Example:

    jive-sdk create example-auth

       

     

    If you are interested in learning about using this feature with the Jive SDK (Java), please let us know:

    Announcing the Jive SDK (Java) Jersey Edition on GitHub Open Source