OAuth 2.0 Flow
Your application can use OAuth to access and modify data in your Pronto organization. There are several steps required to enable OAuth integration which will require software configuration and human interaction.
See https://oauth.net/2/ for information about OAuth.
See https://github.com/Hitlabs/oauth-example for an example application, which demonstrates how to integrate with Pronto.
Step 1 - Getting an OAuth 2.0 Client ID and Secret
The first step to enable OAuth integration is to obtain a Client ID and Client Secret. The client secret should never be shared.
Generating a Client, and obtaining a Client ID and Client Secret can be done by a Pronto Organization Administrator. Log into Pronto and navigate to “Org Management”
Then navigate to “Integrations > Clients”.
Please note: If you do not see the "Integrations" option, then API access is not yet enabled for your organization. Please contact Pronto Support or your Pronto account representative to get it enabled.
Click “Create a Client”
Enter the name of your client, such as the name of the application that is integrating with Pronto, and the URL for your client application, which Pronto will perform a redirect to as part of the OAuth token exchange process. If the client application hasn’t been built yet, or you don’t know the redirect URL, it can be updated later by using the update client screen.
The secret key associated with this client will be generated and displayed. Copy the secret into your client application, and store it in a safe way. The key is stored in an encrypted state in Pronto so this is the only time the client secret will be displayed; if you lose it, a new client will have to be created. Upon navigating to the client detail screen you will also be able to see the Client ID, which you should store with the client secret, in your application.
After you have created a client, you should be able to see it in the Integrations -> Clients list view. From here a client can be clicked on, and the client info screen will be displayed.
When viewing a client you can see the Client Name, Client ID, the associated redirect URLs, and all active tokens associated with that client. From this screen a user can click “Edit Client” to update the client as necessary.
Step 2 - Redirect users of your Application to Pronto, to request OAuth access
With the Pronto Client ID and Client Secret stored securely in your application, OAuth is initiated by redirecting users of your application to the Pronto web application using an HTTP GET request.
Your Pronto organization has its own unique URL domain; you'll need to use this URL when redirecting from your application to Pronto. You can find this URL by checking the URL in your web browser during Step 1. For example:
The request must contain the following URL parameters:
client_id -- The client ID from step 1
grant_type -- "client_credentials"
response_type -- "code"
state -- typically a randomly generated value that your application can use to coordinate the various interactions between your application and pronto
redirect_uri -- one of the redirect URIs associated with the client, verbatim
scope -- One or more scopes that you want access to, separated by spaces. For example:
See the Pronto OAuth API documentation for examples and further details. https://api.pronto.io/docs
Step 3: Review and Approve the OAuth Request
Upon redirecting to the Pronto OAuth Authorize URL the user will be asked to log into Pronto and, as long as that user is an Organization Administrator, will be presented with an OAuth approval screen. The user should review the screen and understand that they are providing programmatic access to their Pronto Organization on their behalf.
To proceed, the user must click “Allow and Continue”
Step 4: Redirect back to the request_uri
If the Pronto user accepts the OAuth request (clicks “Allow and Continue”), Pronto will redirect back to the request_uri specified in the original OAuth get request, with a query string containing the OAuth2 response. You’ll need to build this redirect API into your application in order to complete this OAuth flow. Example redirect URI with query params:
Your application should verify that the state passed matches the state originally sent to Pronto in step 2, this is typically done using HTTP sessions. After verifying the state, your application should extract the `code` parameter, and use it along with the client_id and client_secret to obtain the final OAuth token, which can be subsequently used to make API calls to Pronto.
If the Pronto user doesn't accept the request for access, or if another error occurs, Pronto redirects back to your request_uri with an error parameter, rather than a code parameter, in the query string. For example:
If this happens, it may be useful to have your application redirect to an error page, where the error message, and other query parameters can be displayed to an end user. There are other OAuth failure scenarios that may result in a similar response, which should also be displayed to users for debugging purposes.
Step 5: Exchange the code for the final access token
After your application receives an OAuth code from Pronto, through the redirect API, there is one final step to get an access and refresh token. Your application should send a POST request to pronto at https://chat.pronto.io/oauth/token with the following parameters:
grant_type -- "authorization_code"
client_id -- The client ID from step 1
client_secret -- The client Secret from step 1. This is the only time your application will use the Client Secret.
redirect_uri -- The redirect URI used through the process, starting in step 2
code -- The code returned from the Pronto redirect call in step 4
A successful response will include the following parameters:
token_type -- "Bearer" You should use this token using ‘Bearer Authentication’
expires_in -- The number of seconds from now when the token will expire
access_token -- Token used to call the Pronto API to read / modify data in your organization
refresh_token -- Token used to request a new token, with a reset expiration
See OAuth API documentation for examples and further details. https://api.pronto.io/docs
When appropriate, applications integrating with Pronto should store the token locally, rather than requesting a new token for the same user each time the user uses the application. If the token is deleted, revoked, or expires, the application will get a 401 Unauthorized error from the API, in which case the application should perform the OAuth flow again to receive a new token.
Storing a token is in many ways equivalent to storing the user's password, so tokens should be stored and used in a secure manner. Some guidelines:
- Don't embed tokens in web pages.
- Don't pass tokens around in URLs.
- Properly secure the database or other data store containing the tokens.
- For web applications, practice proper techniques to avoid session attacks such as cross-site scripting, request forgery, replay attacks, etc.
- For native applications, take advantage of user keychain stores and other operating system functionality for securely storing passwords.
Access tokens have a limited lifespan. When the refresh flow is taken, Pronto will revoke the old token, issue a new access token with a new expiration timer, and return that new access token as part of the response. When refreshing tokens the user will not be asked to authorize the application again, so this can be done programmatically without user human intervention. To refresh a token, issue an HTTP POST to https://chat.pronto.io/oauth/token with the following parameters:
grant_type -- "refresh_token"
client_id -- The ID of the client this refresh token is associated with
client_secret -- The Secret Key of the client this refresh token is associated with
redirect_uri -- Any redirect URI configured in the client this refresh token is associated with
refresh_token -- The refresh token which was generated using the OAuth 2.0 flow
The response of the refresh call will be identical to the authorization code request as described previously.
If you need to revoke a token, and prevent any further API access for that token, the Pronto Org Management UI makes this easy. Navigate to the client in question.
You'll see a list of active tokens, the last time that token was used, and the IP address associated where the token was last used. To revoke, simply click "Revoke".
The revoke action will pop up a verification screen. Revoking a token for a client means any applications using that token will no longer be able to access Pronto; to re-enable pronto for that application, the full OAuth 2.0 flow will need to be executed again to restore access.
Using an Access Token to Authenticate Requests
Pronto OAuth tokens can be used to view and modify data in your Pronto organization using Bearer auth. All that is required is to make an HTTP call to pronto with a header named `Authorization` with the value `Bearer <ACCESS_TOKEN>`. The word `Bearer` must be capitalized, and there is a single space between `Bearer` and your access token.
GET /scim/v2/Groups?startIndex=1&perPage=100 HTTP/1.1
Content-Type: application/json; charset=utf-8
See https://api.pronto.io/docs for the available APIs that can be called with an OAuth token.
See https://tools.ietf.org/html/rfc6750 for more information about OAuth 2.0 Bearer Authorization.