OAuth 2.0

Version 15


     

    What is it?

     

    Your Jive server is an OAuth 2.0 server, in strict OAuth 2.0 terms, Jive acts as both Authorization Server and Resource Server.

     

    What are the common use cases?

     

    Enables integration possibilities. Provide controlled API access to content in Jive to a third-party service. Add-ons such as Producteev, StreamOnce & Dealroom are such "third-party" clients that use OAuth.

     

    How do I use it?

     

    Based on your needs you may use either the Authorization Code Grant or the Resource Owner Password Credentials Grant.

    Jive does not implement the two other standard grants defined by the specification: Implicit Grant & Client Credentials Grant.

     

    In order to use OAuth you first have to register a client with Jive.

     

    How do I use it to make Jive REST API calls?

     

    If you specifically want to use OAuth 2.0 for REST API calls, refer to How To Use OAuth 2.0 for REST API Calls.

     

     

    Creating an OAuth 2.0 client (app)

     

    In a typical implementation of an OAuth server

    • client developer usually registers for an account with the server
    • client developer then logs in and uses a web interface to create an OAuth client.

    In Jive (the product) this is not how you can create clients (or in facebook terms "apps"), instead a client developer must follow these steps:

    • Create an add-on package. Instructions and sample can be found at https://community.jivesoftware.com/docs/DOC-99941 For exercising this particular grant, a bare-bones add-on is all that is needed. One such add-on package is attached to this document.
    • Next step is to have this package be installed in a Jive instance. There are two ways to achieve that. You must be logged in as admin.
      1. From the Add-Ons menu item choose "New Add-on"-->"Upload Package" and upload the attached package.
      2. Install such an add-on from the Global Registry.
    • At the end of successful installation a notification is sent to the client that includes client id & client secret. The administrator may also view this client id & secret from the UI.

     

    Obtaining an Access Token using Authorization Code Grant

     

    The implementation is as per the specification. Once an add-on has been installed from the registry (or during development uploaded to a Jive instance from the Add-ons menu), in general

    1. the user logs in to the client's web application in a browser.
    2. Client redirects the user the Jive's authorization end-point typically in a new smaller browser window, which is <jive-url>/oauth2/authorize
    3. Client includes the required parameters client_id=<client_id>&response_type=code and any optional parameters, scope, state or redirect_uri.
    4. If the browser doesn't have a logged in session for Jive, Jive asks the user to login first.
    5. Jive presents an authorization screen asking the user to allow or deny the authorization grant (scope is not shown to user at this time).
    6. Assuming user allows authorization, Jive will redirect to user back to the redirect_uri (if it was sent to the authorization end-point) or to the redirect_uri provided in the add-on.
    7. A short lived authorization code is attached as a query parameter to the redirect URL along with state parameter if it was provided earlier, eg: https://client.application.com/oauth2/redirect?code=<authz_code>
    8. Client makes a POST request to the token end-point authorizing the request using client credentials. In curl this would be
      curl -u 'mqi3a01xvyubsp585hdeqtry8vqbi5j1.i:e692pxphtzyq2nn75htldedoqzog2atk.s' -d 'code=ee3q0hlz6jr8oqwt0qojo4x79mnwuk1q.c&grant_type=authorization_code&client_id=mqi3a01xvyubsp585hdeqtry8vqbi5j1.i' <jive-url>/oauth2/token
    9. Jive responds with eg. {"scope":"uri:/api","token_type":"bearer","expires_in":"172799","refresh_token":"6i85jzwkwpjfkllhrdtqzlownvr55lh0b2k39mwu.r","access_token":"9dqwqywtar14ikpljs4s53bu7qat9qi8agltxttm.t"}

     

    Obtaining an Access Token using Resource Owner Password Credentials Grant

     

    For this particular grant type, the client must obtain username and password from a Jive instance user. Then the client makes a request to the Jive instance where the extension is installed as described in the OAuth specification.

     

    Here is a sample using curl:

    curl -u '<client-id>:<client-secret>' -d'grant_type=password&username=userone&password=psswd1' https://<URL-of-Jive-Service>/oauth2/token

     

    If Jive can authenticate client credentials, user credentials are valid and the user has access to the client then the response will contain access and refresh tokens as show in this example:

    {"token_type":"bearer","expires_in":"172799","refresh_token":"6rge0n89rroc25186rzak4qgix3xeqx4tk4dqgvn.r","access_token":"a9n37vij6h73vbzwys6gxcpeke2k3oirri1djmws.t"}

     

    This above example does not send an optional parameter called "scope". In the only scope we implement and enforce is URI based.

    The exact syntax is very straightforward, for example uri:/api/core/v3 allows only v3 API calls. The default is uri:/

    (If Jive URL has a non-root context, the scope should not include the context path).

     

    Making resource access requests

     

    Once the access token was obtained using one of the above grant types making resource requests is quite straightforward:

     

    curl -X POST -i -H 'Authorization: Bearer <access_token>' -H 'Content-Type: application/json' 'https://<URL-to-Jive-Service>/api/core/v3/contents' --data '{ "type": "discussion", "content": { "type": "text/html", "text":"Starting a discussion"}, "subject": "A new discussion"}'

     

    Refreshing access token

     

    Access tokens are by default valid for 48 hours. This information is provided in the response as a value for "expires_in" parameter, unit is seconds. What is also provided is a refresh token. Typically a new access token is obtained by the client by presenting this refresh token when the current expires. Refresh tokens also have expiration but they are  for much longer, in Jive this value by default is over 10 years. To make a refresh token request

    • a client authenticates itself using HTTP Basic auth where client id & secret are used as username and password respectively.
    • client makes a POST to the /oauth2/token endpoint with refresh_token & grant_type parameters in the body.

     

    Eg. curl -i -u '<client id>:<client secret>' -d 'refresh_token=<refresh token>&grant_type=refresh_token' https://<jive url>/oauth2/token

     

    Note: Clients may end up having multiple valid access tokens (expiring at different times) at any given time using this API.

    Note 2: If you are using a Jive cloud release (01/2014), release 7.0.1 or later it is possible to change the defaults for expiration times for access and refresh tokens as an admin. It is possible to configure these expiration settings at the system level (applies to all add-ons/clients) or for a specific add-on.

     

    Revoking Authorization

     

    A user may view and/or revoke authorization they previously granted to a client. To do this the user has to login to their community and go to the Add-ons page (it is typically in the drop-down menu next at top right corner). Under the "Apps Management" tab the user can see the authorizations given for each client and a "Revoke Access" button. In Jive Cloud and versions 7.0.2 or later if the user has administrator privileges then the user can also revoke authorizations that were given by other users of the community. Alternatively an administrator may also use Jive Core V3 REST API to revoke authorizations.

     

    Show me an example!

    Note:  This step process has been baked into the Jive SDK (v 0.1.208+). 

     

         jive-sdk create oauth2-client --oauthAuthorizeUrl="YOUR_REDIRECT_URL"

     

    and the SDK will auto-setup your project and build your add-on.  See the jive-sdk help documentation for more information.

     

    Examples are embedded.

    Important: If you choose to use the attached sample addon be sure to provide a different UUID value for the "id" field in meta.json.

     

    References & Further Reading

     

    RFC 6749 - The OAuth 2.0 Authorization Framework