---
title: "OAuth2"
description: ""
url: "https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/users-and-roles/oauth2/index.html"
---
Opsview Monitor supports the authentication of users via the OAuth2 provider, such as Okta or Azure AD.

## OAuth2 provider configuration process

Prior to setting up Opsview Monitor, you need to have configured your OAuth2 provider and have the following details available:

- Client ID.
- Client secret.
- OAuth2 URLs.

To configure OAuth2 authentication:

1. On the Opsview system, modify `/opt/opsview/deploy/etc/user_vars.yml` and add the following section, where items surrounded by `<>` should be replaced:

    ```
    opsview_core_web_local_overrides:
      authentication:
        realms:
          <realm_id>:
            credential:
              class: OpsviewOAuth2
              client_id: <client_id>
              client_secret: <client_secret>
              scope: openid email
              grant_uri: <grant_uri>
              token_uri: <token_uri>
              label: <label>
    ```

    These values can be set as follows:

      - `realm_id` - an identifier for this login method as will be shown on the user configuration modal. This ID should not be changed once in use for users, otherwise they will no longer be able to log in.
      - `client_id` - the client ID provided by the OAuth2 provider.
      - `client_secret`  - the client secret provided by the OAuth2 provider.
      - `grant_uri`  - the URL to which users should be redirected to sign in at the OAuth2 provider. Often located at` /authorize`.
      - `token_uri` - the token URL for the third-party. Often located at `/token`.
      - `label` - the user-friendly name for this service, which will be shown on the Login screen as “Login with <label>“.
      - `scope` - the OAuth2 provider scopes that are granted when logging into the third party. Opsview  simply needs access to view the user’s email address. With Okta, for example, the required scopes are openid and email.

2. Modify `/opt/opsview/deploy/etc/user_vars.yml` and add the following section, where items surrounded by `<>` should be replaced:

      ```
      opsview_webserver_sso_providers_url: <oauth url(s)>
      ```

    The value can be a single string e.g. opsview_webserver_sso_providers_url: https://login.microsoftonline.com or a list of strings if multiple providers are used. For example:

      ```
      opsview_webserver_sso_providers_url:
        -  https://login.microsoftonline.com 
        -  https://*.okta.com
      ```

    This value will normally be the same as the `grant_uri` (URL to which users should be redirected to sign in at the OAuth2 provider), but may vary depending on the provider.

3. (Optional) Disable local login and enable SSO-only authentication.

    Update `/opt/opsview/deploy/etc/user_vars.yml` to include:

      ```
      opsview_disable_local_login: True
      ```

      By default, this variable is set to `False`.

4. Before enabling it, make sure SSO is properly configured and that all OAuth users are added in Opsview. For more information, see [Add a User](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/users-and-roles/oauth2/index.html#add-a-user).

5. Run the following to apply the configuration.

      ```
      $ /opt/opsview/deploy/bin/opsview-deploy /opt/opsview/deploy/lib/playbooks/orchestrator-install.yml
      ```

## Add a User

Once the above steps have been completed, you will need to configure users to be able to log in via the OAuth2 provider. For each user, only one login mechanism can be provided.

To add a user that can log in via an OAuth2 provider:

1. Navigate to **Configuration > Users and Roles**.
2. Click Add New.
3. Configure the user as specified in [Users](https://docs.itrsgroup.com/docs/opsview/6.11.7/configuration/users-and-roles/users/index.html), but with the following modifications:
    - Username - should be the email address as defined in the OAuth2 provider.
    - Realm - set to the realm_id as configured above.
4. Click **Submit Changes**.

## To Login

Having followed the above steps to add an OAuth2 provider, the login page will now show a button for logging into Opsview via the OAuth2 below. For example:

![Opsview Monitor Login page](https://docscdn.itrsgroup.com/opsview/images/config-oauth2-login-page.png)

To log in, simply click the button and enter your details with the OAuth2 provider if necessary.

## Example configurations

### Okta

The below screenshot shows the Application view in Okta. 

![Okta configuration](https://docscdn.itrsgroup.com/opsview/images/config-oauth2-okta.png)

The URLs for use in the Opsview configuration are:

  - `grant_uri`: `https://<okta domain>/oauth2/v1/authorize`
  - `token_uri`: `https://<okta-domain>/oauth2/v1/token`

Due to the introduction of the content security header, a new variable is required in `user_vars.yml` to configure OAuth2 authentication.

The content security header by default blocks redirection to the OAuth2 providers authentication URL when the login form is submitted, therefore the authentication URL needs to be added to the header in the `form-action` section:

```
Content-Security-Policy
	default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; 
    connect-src 'self' https://s3.amazonaws.com/opsview-adverts-testing/; 
    img-src 'self' data: https://s3.amazonaws.com/opsview-adverts-testing/; 
    style-src 'self' 'unsafe-inline'; font-src 'self'; base-uri 'self'; 
    form-action 'self' <OAuth2 provider authentication URL>
```

To resolve this, a new user variable is created, which will need to be added to  `user_vars.yml` during OAuth2 configuring `opsview_webserver_sso_providers_url`.
The value can be a single string:

```
opsview_webserver_sso_providers_url: https://login.microsoftonline.com 
```

Or a list of strings if multiple providers are used:

```
opsview_webserver_sso_providers_url:
   -  https://login.microsoftonline.com 
   -  https://*.okta.com
```

This value will normally be the same as the `grant_uri` (URL to which users should be redirected to sign in at the OAuth2 provider) however, may vary depending on the provider. This is a top level key `opsview_webserver_sso_providers_url` and should not be nested in `opsview_core_web_local_overrides` .

### Azure Active Directory

The below screenshot shows the Application Registration view in Azure Active Directory.

![Azure Active Directory](https://docscdn.itrsgroup.com/opsview/images/config-oauth2-azure-active-directory.png)

The below screenshot shows the Client Credentials view in Azure Active Directory, which can be access through the Application Registration view above.

![Client Credentials view](https://docscdn.itrsgroup.com/opsview/images/config-oauth2-certificates-azure.png)

The URIs for use in the Opsview configuration are:

- `grant_uri`: `https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/authorize`
- `token_uri`: `https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token`

The email address used for tying an Opsview user to an Azure user is the email address provided in the user’s “Contact Info”. The below screenshot shows the User Profile view in Azure Active Directory and the relevant email field to be used.

![User Profile view](https://docscdn.itrsgroup.com/opsview/images/config-oauth2-myuser.png)

## Troubleshooting

If you are having problems with users logging in with OAuth2 providers then please check the configuration in the `user_vars.yml` carefully. 

If the problems are with browser timeouts after clicking the “Log in with xxx”, then the `grant_uri` and `token_uri` parameters could be wrong, or there is a firewall preventing communication to your OAuth2 provider. You can check these by using curl or wget, although with the `token_uri` or `grant_uri` if the response hangs then you should first check the URI is correct. If you are confident it is correct, then check your firewall.

