Professional Documents
Culture Documents
OAuth2.0 in ConnnectionsCloud
OAuth2.0 in ConnnectionsCloud
0
in IBM Connections Cloud
Contents
Overview..................................................................................................................................................................2
Application registration...........................................................................................................................................3
Flow for third-party data access...............................................................................................................................5
Conclusion.............................................................................................................................................................14
References..............................................................................................................................................................14
Overview
The OAuth 2.0 flow is suited for web applications, desktop applications, and third-party extensions. Example
use are project management, electronic signatures, customer relationship management, and innovation
solutions.
To understand the OAuth 2.0 flow, consider the scenario with a courier working on behalf of a customer. This
scenario assumes that Paul is registered with the bank as a trusted courier, and Mike has a bank account. Mike
wants Paul to run an errand for him at the bank. But before Paul can access Paul's bank account, he must be
authorized using the following steps:
1. Mike asks Paul to go to the bank on his behalf.
2. Paul gives Mike his previously registered ID to submit to the Bank.
3. Mike goes to the Bank, proves his own identity, and then submits Paul's ID to register Paul as his courier.
4. Bank confirms with Mike: "Do you want to allow Paul to access your assets?"
5. As Mike trusts Paul, he agrees.
6. Bank grants a temporary code to Mike.
7. Mike passes the temporary code to Paul.
8. Paul immediately goes to the bank to submit the code because the code is short-lived (if Paul waits too long,
the code expires and the process must begin all over again).
9. Bank validates the temporary code submitted by Paul.
10. Bank issues Paul a token that lets him bypass the registration check for the next two hours.
11. Paul accesses Mike's assets. (Note: The Connections Cloud implementation of OAuth 2.0 provides
unlimited access to user resources).
12. Within 2 hours, Paul must renew the token so he can continue to access Mike's assets.
Application registration
When a third-party application is integrated with IBM Connections Cloud, customers can "opt in" by registering
the application within their organization, which makes the application available to all users within that
organization. Applications can be registered with organizations in specific geographies (Central Europe,
Americas, or Asia Pacific).
To register a third party-application with IBM Connections Cloud, complete the following steps:
1. Log in to IBM Connections Cloud.
2. In the top navigation bar, click the arrow next to your profile picture and select Account Settings.
3. In the side navigation, click Internal Apps.
4. Click Register App.
5. In the Register App window, provide the application details as explained in Table 1.
Table 1. Application registration fields
Field name Example value Description
App Name Test Application - Paul This field is not used as part of the OAuth 2.0 flow; it is used only
to identify the application in the list of Internal Applications. The
best practice is to include the name of the owner in the
application name, as shown in the example.
Auth Type OAuth 2.0 Indicates the type of authentication used by the application that
you are registering: Basic, OAuth 1.0a, or OAuth 2.0.
Registering an OAuth 2.0 application automatically creates an
OAuth 1.0a application registration as well.
Access Grant 90 Days Specify the life (duration) of the refresh token, in days. You can
Duration set the duration for as many as 90 days, but you might decide to
set a shorter duration for security reasons.
Note the difference between the duration of the access token and
the refresh token:
Access token: Used to call actual APIs and live only about two
hours.
Callback URL https://localhost/call Provide any URL that can be accessed by the application being
back registered. This value must match the callback that is sent to the
authorization URL, described in the next section.
The customer callback URL enables the third-party application to direct to any URL (secure or insecure)
using any protocol (for example, notes:// or myapp://). The OAuth 2.0 flow allows the application to be
public or private, as long as it can connect with IBM Connections Cloud.
Best practice is to use a secure protocol such as https or wss. The callback URL redirects the user back to the
third-party application from IBM Connections Cloud, and includes the short-lived access code as a URL
parameter.
Note: IBM Connections Cloud does not support OAuth scopes, which limit access to data or limit the Read-
Write capabilities of the third-party application.
6. Click OK.
IBM Connections Cloud displays a message stating that the application was registered successfully:
After the application is registered, the OAuth credentials are available. To obtain the credentials, complete the
following steps:
1. Click Account Settings > Internal Apps.
2. Find your application's name (for example, "Test Application - Paul") in the list of Internal Apps.
3. Click application_name > Show Credentials.
4. Click Show Client Secret.
5. Copy the ClientID, Client Secret, and Callback URL values. Example values are shown in Table 2.
Callback URL https://localhost/callbac The callback URL that you provided when you
k registered the application with Connections Cloud.
The third-party application must store its OAuth credentials in a secure location, and treat the information as
confidential data.
The authorization URL is unique for each IBM Connections Cloud environment. If the user logs into the
Americas service (https://apps.na.collabserv.com), the third-party application must be registered with
the organization on the Americas data center. The authorization URL would be
https://apps.na.collabserv.com/manage/oauth2/authorize. Table 4 lists the authorization URLs for
the Connections Cloud environments.
Table 4. Authorization URLs for Connections Cloud environments
Environment Authorization URL
North America https://apps.na.collabserv.com/manage/oauth2/authorize
Europe https://apps.ce.collabserv.com/manage/oauth2/authorize
Asia-Pacific https://apps.ap.collabserv.com/manage/oauth2/authorize
For example, a third-party application calling IBM Connections Cloud with the Americas service would use the
URL https://apps.na.collabserv.com/manage/oauth2/authorize?
response_type=code&client_id=app_example&callback_uri=http://localhost/callback.
7. IBM Connections Cloud returns the user to the registered callback URL with a short-lived access code.
IBM Connections Cloud redirects the user's browser to the callback URL, which includes a unique identifying
code, using the format: https:///callback?code=1236879. The code is short-lived (90 seconds). The third-
party application must convert to a more permanent OAuth credential within that time-frame.
8. Third-party application exchanges the short-lived authorization code for a set of user-specific
credentials: an access token and a refresh token.
To exchanged the short-lived authorization code, the third-party application must make an HTTP GET or HTTP
POST request to the token URL. The request must have the HTTP Header Content-Type set to
application/x-www-form-urlencoded. The request body must be URL-encoded and must contain the
parameters listed in Table 6.
Table 6. URL parameters for a request to exchange a short-lived authorization code
Parameter name Parameter value
callback_uri The URL for the third-party application’s callback URL:
callback_uri=CALLBACK_URI
client_secret Third-party application client secret:
client_secret=CLIENT_SECRET
client_id Third--pParty application client ID:
client_id=CLIENT_ID
grant-type There is only one allowed value-- authorization_code:
grant_type=authorization_code
code The short-lived access code received by the third-pParty application
code=AUTHORIZATION_CODE
The HTTP GET method uses the Authorization header with OAuth 2.0 instead of the POST body. The values
are added to the authorization header in the following set format:
Authorization: OAuth callback_uri="CALLBACK_URI",client_secret="CLIENT_SECRET",
client_id="CLIENT_ID", grant_type="authorization_code", code="AUTHORIZATION_CODE"
The token URL is unique for each IBM Connections Cloud environment. If the user logs into the Americas
service (https://apps.na.collabserv.com), the third-party application must be registered with the organization on
the Americas data center, and the token URL would be:
https://apps.na.collabserv.com/manage/oauth2/token. Table 7 lists the token URLs for the various
Connections Cloud environments.
Table 7. Token URLs for Connections Cloud environments
Environment Token URL
North America https://apps.na.collabserv.com/manage/oauth2/token
Europe https://apps.ce.collabserv.com/manage/oauth2/token
Asia-Pacific https://apps.ap.collabserv.com/manage/oauth2/token
If the request is successful, the parameters listed in Table 8 are returned in the body of the response, with an
HTTP response code of 200.
Table 8. User-specific authorization data that is returned to the application
Parameter name Parameter value
access_token The access token that is used as a bearer token to access the protected resource, and is valid
for two hours from time it is granted. The maximum number of characters is 256.
refresh_token A long-lived refresh token that can be used to obtain a new access token when the access
token expires. The maximum number of characters is 256.
Note: The value of the refresh token is confidential and should be protected.
issued_on The details of when the access token was created. The created timestamp is based in epochs.
expires_in The amount of time, in milliseconds, that the access token is valid.
token_type The default value is Bearer.
For any invalid request, the OAuth 2.0 provider responds to the third-party application with one of the errors
listed in Table 9.
Table 9. OAuth error codes for invalid authorization requests
Error Type Status Code Error Message and Detail
BAD REQUEST 400 oauth_absent_parameters: <parameter_list>
The <parameter_list> parameters must be included in the request.
BAD REQUEST 400 oauth_duplicated_parameters: <parameter_list>
Duplicate parameters were passed with the request.
BAD REQUEST 400 oauth_unsupported_parameters: <parameter_list>
Unsupported parameters were passed with the request.
BAD REQUEST 400 oauth_invalid_parameters: <parameter_list>
Invalid parameters were passed with the request.
BAD REQUEST 400 oauth_unsupported_grant_type
The grant_type parameter passed with the request is not supported in
IBM Connections Cloud. The following grant types are supported: code,
refresh_token, and authorization_code.
9. Third-party application stores the access token and refresh token for the user, so that the third-party
application can act on behalf of the user
The application should store the OAuth 2.0 response data in a secure data store.
10. Third-party application uses the access token to use IBM Connections Cloud APIs.
The application uses the authorization header with the Bearer value to access the IBM Connections Cloud APIs.
The application should confirm the user’s identity with the given access token using the Authorization Bearer
Token. The getUserIdentity request returns user information such as subscriber ID, customer ID, name, and
email.
URL https://apps.na.collabserv.com/manage/oauth/getUserIdentity
Header Authorization: Bearer
When the third-party application invokes an API request with an expired access token, the error code 401 is
returned with an oauth_access_token_expired error message. After receiving the error message, the application
must use the refresh token to get a new access token.
Table 10 lists the input parameters used in the HTTP GET request for a long-lived refresh token.
Table 10. Input parameters for requesting a long-lived refresh token
Parameter name Parameter value
grant_type Set the value to refresh_token.
client_id The client ID of the third-party application. The client ID is provided at the time the
application is registered.
client_secret The client secret of the third-party application. The client secret is provided at the time the
application is registered. The maximum number of characters is 256.
refresh_token A long-lived refresh token that can be used to obtain a new access token when the access
token expires. The maximum number of characters is 256.
Note: The value of the refresh token is confidential and should be protected.
If the request is successful, the parameters listed in Table 11 are returned in the body of the response, with an
HTTP response code of 200.
Table 11. Parameters included in the response to a successful request for a long-lived refresh token
Parameter name Parameter value
access_token The short-lived access token. The default life span of the token is two hours and the
maximum number of characters is 256.
refresh_token A long-lived refresh token that can be used to obtain a new access token when the current
access token expires. The maximum number of characters is 256.
Note: The value of the refresh token is confidential and should be protected.
issued_on The details of when the access token was created.
expires_in The amount of time, in milliseconds, that the access token is valid.
token_type The default value is Bearer.
For any invalid request, the OAuth 2.0 provider responds to the third-party application with one of the error
messages listed in Table 12.
12. Third-party application stores the updated refresh and access tokens
The application updates the stored OAuth data for the user (just as it did in step 9). At this point the application
can continue to use the Connections Cloud APIs until the tokens expire (as long as 90 days, depending on how
the user granted access). Long-running tasks, scheduled tasks, and integrations no longer need the user’s direct
authorization to connect with IBM Connections Cloud.
Conclusion
IBM Connections Cloud recommends the use of OAuth 2.0 for authenticating users with third-party
applications. OAuth 2.0 removes the need to store username-password pairs, allows for granular access to data,
and works in concert with SAML authentication.
For more information on using OAuth 2.0 in an application, review the photosharing-java sample code on
GitHub.
References
For developers new to OAuth 2.0, the following links will help you to become familiar with the authorization
flow.
● "About OAuth 2.0" article on the OAuth Community site
● "Developing an IBM SmartCloud for Social Business application" on the IBM developerWorks site
● "Open Authorization" article in the IBM Connections Cloud Developers wiki
● "User Authentication" article in the JavaScript Web Guide section of the Firebase site
● "Obtaining access tokens" article in the Twitter Developer's documentation
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines
Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of
IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark
information" at www.ibm.com/legal/copytrade.shtml.