OAuth2 Getting Started Guide
The ShareFile OAuth2 implementation allows users to grant an application provider access to their ShareFile resources, without having to share their username and password. Once OAuth2 has been activated on an account, and the application provider has client_id, and client_secret keys, the authentication can proceed as follows. Note that while the Web Authorization method shown below is the preferred method of authentication, in some cases like console applications, or other non web based applications you can use the OAuth2 password grant type. See the ShareFile OAuth2 password grant page for more information on authenticating with this method.
To request an OAuth2 key, please complete and submit a request.
Request Authorization
A user enters the application provider’s web portal or application and wishes to interact with some ShareFile resources. This is typically where an application provider would need to directly ask for a user’s username and password. With OAuth2 the application provider does not need access to this information, and instead the authorization is performed on a secure ShareFile server. The application should direct the user to the ShareFile authentication page with the appropriate query parameters.
https://secure.sharefile.com/oauth/authorize
| Query Parameter | Value / Description |
|---|---|
| response_type |
Use to request a token or code.
|
| client_id | The account’s client_id value, provided after registering for OAuth2 access. |
| redirect_uri | Use to specify an HTTPS URI where the response should be redirected. This should exactly match the Redirect URI provided during application registration. |
| state | An optional parameter that will be returned to the redirect_uri as is. This should be a randomly generated string used to prevent Cross Site Request Forgery (CSRF) attacks. When returned, it should be validated against the value you generated. Although optional, we strongly recommend the use of the state parameter. |
User Login / Authorization
The user will enter his or her username and password and authorize the application to access a ShareFile account. Upon successful validation of the username and password, the ShareFile authentication server will call back to the redirect_uri with the following information:
| Query Parameter | Description |
|---|---|
| code / access_token | Returns an access code or access token, depending on which was requested. |
| state | The optional value that was passed to the authorization page. |
| subdomain | The user’s ShareFile subdomain, i.e. if they access their ShareFile account through https://mycompany.sharefile.com , this value would return “mycompany”. Some username / password combinations may be active on multiple accounts. The user would need to choose an account in this case. |
| apicp | The user's ShareFile API control plane, i.e. sharefile.com, securevdr.com, etc. |
| appcp | The user's ShareFile account control plane, i.e. sharefile.com, securevdr.com, etc. |
| expires_in | The expiration time in seconds. |
| h | A SHA-256 HMAC digest of the path and query string signed with your client secret for validation that the values came from ShareFile. |
Validating the Redirect Request
In order to prevent man in the middle attacks, ShareFile will sign the path and query string when the browser is redirected as part of the authorization flow.
ShareFile will utilize your client secret to create a digest via the HMAC SHA-256 algorithm. This will allow you to trust that the values in the query string have not been tampered with.
Note: This validation should only be performed in server side code, as it requires your client secret. If you are using the token response_type and your code runs only in the user agent, you will not be able to perform this validation.
To validate the hash, follow these steps:
- Remove the "h" query string parameter from your request URI.
- Parse out just the path and remaining query string parameters. For example, if the request uri is:
https://www.myapp.com/oauth?code=c123&subdomain=mycompany&apicp=sharefile.com&appcp=sharefile.com&h=abcdef1234then the path and query string you will be validating will be/oauth?code=c123&subdomain=mycompany&apicp=sharefile.com&appcp=sharefile.com - Convert the path and query string to an array of bytes using UTF-8 encoding.
- Create a digest of the array of bytes using HMAC SHA-256, using your client secret.
- Convert the digest to text using base 64 encoding.
- URL encode the text and compare to the value in the "h" query string parameter. If they match, then you can trust the data was not tampered with. If they don't match you should ignore the values and re-authenticate.
Access Token Acquisition
When using the "code" response_type flow, the code can be exchanged for an access token and refresh token. Your application should utilize the subdomain and apicp values that were part of the authorize response to construct the URL to exchange the code for tokens.
https://{subdomain}.{apicp}/oauth/token
Header:
Content-Type: application/x-www-form-urlencoded
Content:
grant_type=authorization_code&code=[code]&client_id=[client_id]&client_secret=[client_secret]
The response will be a JSON encoded object with the following data:
| Field | Description |
|---|---|
| access_token | The access token. |
| refresh_token | The refresh token. |
| token_type | The token type. |
| apicp | The user's ShareFile API control plane, i.e. sharefile.com or securevdr for the above example. |
| appcp | The user's ShareFile account control plane, i.e. sharefile.com or securevdr for the above example. |
| subdomain | The user’s ShareFile subdomain, i.e. if they access their ShareFile account through https://mycompany.sharefile.com , this value would return “mycompany”. Some username / password combinations may be active on multiple accounts. The user would need to choose an account in this case. |
| expires_in | The expiration time in seconds. |
Authorization Header
The access_token can now be used as an authorization header in all API request. For example:
https://{subdomain}.{apicp}/sf/v3/Items(home)
Header:
Authorization: Bearer {access_token}
Refresh Token
The refresh token should be used after the access token has expired. The following endpoint should be used to refresh a token.
https://{subdomain}.{apicp}/oauth/token
Header:
Content-Type: application/x-www-form-urlencoded
Content:
grant_type=refresh_token&refresh_token=[your_refresh_token]&client_id=[client_id]&client_secret=[client_secret]
The response will again be a JSON encoded object as with the initial access token acquisition.
Authenticating in ShareFile with Postman 3
Postman 3 is a handy feature for executing HTTP Requests, and allows authorization using OAuth 2.0. This guide will help you set up Postman for use with the ShareFile API