Add OAuth Providers

About OAuth 2

OAuth 2 is an open authorization framework that provides client applications a 'secure delegated access' over HTTP to server resources like Google, Facebook, GitHub etc on behalf of a resource owner. It can be used to build authorization workflows for web, desktop, and mobile applications. With Site24x7, you can generate Access Tokens that can be used to monitor an API endpoint secured by OAuth 2. 

Create OAuth Provider

Site24x7 lets you set-up multiple OAuth Providers for monitoring their API end points. Every OAuth Provider lets you generate a unique access token, which can be used to authorize Site24x7 to monitor their Websites/end point APIs. While configuring monitoring forms for URLs, REST API and SOAP work flows, you can use these preset OAuth access tokens for authentication purpose. To set-up an OAuth Provider, follow the steps below:

1. Login to Site24x7 client.
2. Navigate to Admin > Configuration Profiles > OAuth Providers.
3. Click the Add OAuth Provider button.
4. You'll be prompted with an Add OAuth Provider form. 
5. There are three types of Authorization Flow that Site24x7 supports:
   • Authorization Code: This type of authorization is used by Server Side Applications  
   • Client Credentials: Used with Applications API access
   • Resource Owner Password Credentials: Used by trusted applications, such as the ones used by the service itself. 

Based on the method used by the application to request authorization, and the authorization flows supported by the APIs, the OAuth Provider form will render differently. Provide the relevant details in the OAuth Provider form:

Authorization Code:

• Provider Name: Specify the name of your OAuth Application provider.
• OAuth Flow: Specify this as Authorization Code.
• Refresh Location: Choose the location from the drop-down menu where you want to refresh the token. This will collect configuration data based on the selected location.
• Refresh Interval: Specify the Refresh Interval for the OAuth token. This will be used only when the token expiry time isn't provided in the API response.The interval should be within the range of 1-9999 minutes.
• Authorization endpoint URL: The API Authorization Endpoint of the OAuth provider.
• Client ID: The unique alphanumeric string that you received from the OAuth provider while registering Site24x7 as a client.
• Client Secret: The secret string that was obtained by Site24x7 during the client registration process.
• Redirect URI: The Site24x7 URL to which the redirection happens after a successful authorization. This will be auto-populated and can't be modified by the user.
• Scope: Specify the OAuth scope that Site24x7 might need to request for the access of the OAuth application. You can provide multiple scopes depending on the level of access you need while monitoring.
  

  https://example.com/v1/oauth2/authorize?response_type=code&client_id=

  CLIENT_ID

  &redirect_uri=

  CALLBACK_URL

  &access_type=offline&scope=

  profile
• Query parameters: Additional query parameters "name-value pair" that needs to be appended to the authorization endpoint URL along with the standard params like: client_id, redirect_uri and response_type.
• Token endpoint URL: The URL of the OAuth Provider from where the Access Token is retrieved.
• Authenticated request method: Choose the method used to submit access tokens to this OAuth provider. Pick and define the method used to pass the Access Token. You can always use customized nomenclatures in the parameter fields.  
  • Request header: The access token is sent as the request header. Pass the Bearer token in the following name-value syntax:

    "Authorization: Bearer ${access.token}"

  • URI query parameter: You can pass the access token in the URI query parameter using the following syntax:

    "access_token=${access.token}"

    
• OAuth refresh failure alert: Whenever an access token can't be refreshed even after three consecutive retries, users in the selected groups will be notified. Learn how to create a User Alert Group.

Client Credentials:

Client Credentials OAuth Flow is used in scenarios where an application wants to access and update its own service account. It can be used in scenarios where an application wants to update a registered description or redirect URI, or access other data stored in its service account via the API.

For such an OAuth implementation, you must specify the following additional fields in the OAuth Provider form, in addition to all the mandatory fields that were populated in the Authorization Code flow above.

• OAuth Flow: Specify this field as Client Credentials.
• Refresh Location: Choose the location from the drop-down menu where you want to refresh the token. This will collect configuration data based on the selected location.
• Authentication Method: An application can request an access token by passing its Client ID and Client secret, to the authorization server. This can be passed using Basic authentication (where the credentials are passed in an Authorization header) or can be posted in the request body. Click the radio button to match the method to your preference.
• Request Body: Add any additional parameters to be sent while requesting for an access token. 
• OAuth refresh failure alert: Whenever an access token can't be refreshed even after three consecutive retries, users in the selected groups will be notified. Learn how to create a User Alert Group.

Resource Owner Password Credentials:

When an application is trusted by the user (i.e., it's owned by the service, or the user's desktop OS), the user can provide their service credentials (username and password) directly to the application to obtain the access token from the service.
For such an OAuth implementation, you must specify the following additional fields in the OAuth Provider form, in addition to all the mandatory fields that were populated in the Authorization Code flow above.

• OAuth Flow: Specify this field as Resource Owner Password Credentials.
• Refresh Location: Choose the location from the drop-down menu where you want to refresh the token. This will collect configuration data based on the selected location.
• Resource Owner Credentials: Provide the resource owner's username and password. 
• Authentication Method: An application can request an access token by passing its Client ID and Client secret, to the authorization server. This can be passed using Basic authentication (where the credentials are passed in an Authorization Header) or can be posted in the request body. Click the radio button to match the method to your preference.
• Request Body: Add any additional parameters to be sent while requesting for an access token. 
  
  
• OAuth refresh failure alert: Whenever an access token can't be refreshed even after three consecutive retries, users in the selected groups will be notified. Learn how to create a User Alert Group.

6. Click the Check Configurations button to test the OAuth Provider once you have entered all the details related to your OAuth Provider configuration. Once the test is complete, the result will display the related Request Header, Response Header, and the Responses of your OAuth Provider.

7. Click the Authorize button to successfully retrieve an Access Token, and Refresh Token (if provided by the OAuth provider).

OAuth Token Details

Once an OAuth Provider's profile is created, it will get automatically listed under the OAuth Providers list. You'll be shown the Provider Name, OAuth Flow used, Access Token, Refresh Token (if the provider offers it) and Access Token Expiration Time.

• Provider Name: Name of the OAuth Application Provider. 
  
• OAuth Flow: It highlights the method of authorization used by your service for secure access. It could be Authorization Code, Client Credentials, Resource Owner Password Credentials, based on your configured profile settings.
• Access Token: An access token is used for authorization and authentication while gaining access to resources on the OAuth provider application.
• Refresh Token: Refresh tokens are usually sent along with the access tokens. Refresh tokens are used to retrieve a new Access Token before the old one expires.
• Access Token Expiration Time: It defines the expiration time for the access token.
  
  • A few Access Tokens will have no refresh token linked to it. All associated monitors will fail to authenticate once the access token expires.
  • When you've a refresh token, but the access token can't be refreshed even after three consecutive retries, an alert email will be triggered for quick troubleshooting. The email will contain the response from the Authorization Server.

Edit OAuth Provider details

You can edit the OAuth Provider's configuration details or even delete the Provider profile.

• Navigate to Admin > Configuration profiles > OAuth Providers.
• Click on the profile you wish to edit/delete.
• The pop-up window that opens, shows you the edit and delete options. Click on Edit to modify the provider's details.