OAuth Setup

From Grooper Wiki

FYI

Looking for OAuth Service Login setup for Exchange connections? You're in the wrong place.

This article is about setting up OAuth for the Grooper and GWS websites, not setting up Exchange CMIS Connections to use the OAuth client credentials flow. For information on setting up OAuth for Exchange connections, visit the OAuth Service Login setup portion in the Exchange article.

Login with your Microsoft credentials with OAuth

OAuth is an authentication method that allows third-party applications web access without sharing passwords. Both the Grooper website and the GWS website can be configured with OAuth authentication.

  • Microsoft Entra ID (formerly Azure Active Directory) is the only supported OAuth provider at this time.
Grooper and OAuth - When you configure the Grooper website to use OAuth, users will log into Grooper using their Entra ID credentials. Microsoft will ask you to approve the login and grant access. This allows Grooper log in using Microsoft authentication servers.
  • Previous login methods are still supported and Windows remains default login method for the Grooper web app.
  • OAuth is required if you are (1) extending an AI Assistant to an external channel like Teams using Azure Bot Services and (2) want users to be able provide users links to download Grooper documents or open documents in Grooper in the chat response. This mechanism secures the links sent between Grooper, the Azure bot, and the chat channel.
GWS and OAuth - Grooper Web Services (GWS) uses OAuth client credentials to communicate with Azure Bot Services.
  • This authentication method is required for users wanting to extend AI Assistants to external channels like Teams using Azure Bot Services.
  • For users that what to provide links in the chat response to download Grooper documents or open documents in Grooper, both the Grooper website and GWS websites will need to be secured with OAuth.


Benefits to OAuth:

  • Security - Users do not have to share their passwords with third party applications. Microsoft Entra ID supports multifactor authentication as well.
  • Simplified logins - Users can log into multiple applications with existing accounts. In the case of Grooper, with a Microsoft Entra ID account (formerly Azure Active Directory).
  • Integrations - OAuth is the security standard for app-to-app communication. Securing Grooper with OAuth allows us new integration options, including using Azure Bot Services to extend AI Assistants to external chat channels.

⚠

IMPORTANT! OAuth settings must be configured every time a new Grooper Web Client build is installed.

OAuth settings are stored configured in the Grooper and GWS websites' web.config files. These files are erased and regenerated every time the Grooper Web Client installer runs. Please back up these settings before running the Grooper Web Client installer. You will need to re-enter them every time you install the Grooper Web Client.

Basic steps

You are probably familiar with OAuth already if your organization uses Microsoft applications. When these applications ask you for a username and password, they are likely using OAuth behind the scenes to authenticate your access.

To do this you will:

(1) Create a Microsoft Entra ID app registration for Grooper

  • An "app registration" registers an external application with Entra ID (formerly Azure Active Directory).
  • This gives identity to applications (like Grooper) in an organization's domain/tenant.

And (2) configure the the Grooper website (and GWS website if needed).

  • You will disable Windows authentication for the Grooper website and enable Anonymous authentication. When configured this way, Grooper will look in the website's config file for the info it needs to authenticate with Microsoft OAuth servers instead. If present, it will use OAuth to authenticate the user attempting to open the Grooper web app.
  • You will edit the Grooper website's configuration file, entering the app registration's client ID, client secret, tenant ID and redirect URI. This information is what allows Microsoft OAuth servers to identify Grooper as a registered application and authenticate the user attempting to open the Grooper web app.

Registering an app in Entra ID for Grooper

Whether configuring OAuth for the Grooper website or the GWS website, your first step is making an app registration for Grooper in Microsoft Entra ID (formerly Azure Active Directory). This registration will identify Grooper as a trusted application within your tenant and allow Entra ID users access when opening the Grooper application and allow app-to-app communication for GWS API endpoints.

Create the app registration

  1. Go to the Microsoft Azure portal (portal.azure.com)
  2. Search for "Microsoft Entra ID"
  3. Under "Manage", select "App registrations".
  4. Press the "New registration" button.
  5. Enter a name for the app registration.
  6. Select the "supported account type".
  7. Configure the Redirect URI" (You will need this later).
    • Select "Web" for the platform type.
    • The URI will follow this format: https://{webserver-name-or-domain-name}/Grooper/Auth/Callback
    • If you forget to do this, you can add a redirect URI later. However, it will be needed when configuring the Grooper web server.
  8. Press the "Register" button to register the app.

Make note of the "Client ID" and "Tenant ID" (You will need these later).

In the app registrations "Overview" screen, make note of the "Application (client) ID" and "Directory (tenant) ID" values.

  • Application (client) ID = Client ID
  • Directory (tenant) ID = Tenant ID

Create a client secret and copy it down (You will need this later).

  1. In the "Overview" screen, click the "Add a certificate or secret" link next to "Client credentials".
  2. Press the "New client secret" button.
  3. Name the client secret (Description) and set an expiration date (Expiration).
  4. Press the "Add" button.
  5. Under "Value" copy the client secret using the "Copy to clipboard" button.
    • This is your only chance to copy the client secret. Do not lose it. You will need it later when configuring the Grooper web server.

Configure for hybrid authentication flow.

  1. Under "Manage", go to the "Authentication" screen.
    • If you have not done so already, you can configure a Redirect URI here.
  2. Under "Implicit grand and hybrid flows", check the box next to "ID tokens (used for implicit and hybrid flows)".
  3. Press the "Save" button.

Configure API permissions.

You will need to add a few Microsoft Graph permissions to allow the app to query your domain's directory and sign in users.

  1. Under "Manage", go to the "API permissions" screen.
  2. Select "Add a permission".
  3. Select "Microsoft Graph".
  4. Select "Application permissions".
  5. Search for and select the following permissions:
    • Directory.Read.All
    • Group.Read.All
    • User.Read.All
  6. Select "Add permissions" to add the selected permissions.
    • Admin consent is required for these permissions. If you are not your organization's Azure administrator, you will need to request these permissions are approved by your administrator.

Configuring OAuth for Grooper app users

Configuring OAuth for the Grooper website will use OAuth user authentication.

This will authenticate users attempting to open the Grooper application in a browser using Microsoft OAuth servers. To impliment OAuth authentication, you will need:

  • The Azure tenant ID
  • The Grooper app registration's client ID
  • The Grooper app registration's tenant ID
  • The Grooper app registration's redirect URI

Configuration steps:

  • BE AWARE! You will need to do this every time you install Grooper Web Client, including when you install new minor builds. Installing Grooper Web Client will wipe clean all previous settings entered in the website's configuration file.
  1. On the Grooper web server, open Internet Information Services (IIS) Manager.
  2. In the "Connections" panel, navigate to the Grooper website.
  3. Under "IIS", open "Authentication".
  4. Select "Windows Authentication". In the "Actions" panel, select "Disable".
  5. If disabled, select "Anonymous Authentication". In the "Actions" panel, select "Enable".
  6. Go back to the Grooper website.
  7. Under "Management", open the "Configuration Editor".
  8. Using the "Section" dropdown, select "appSettings".
  9. Open the "(Collection)" editor.
  10. Select "ida:ClientId". In the Properties panel, select "value" and enter the app registration's client id.
  11. Select "ida:ClientSecret". In the Properties panel, select "value" and enter the app registration's client secret.
  12. Verify "ida:AADInstance" is "https://login.microsoftonline.com/". This value should be present by default.
  13. Select "ida:TenantId". In the Properties panel, select "value" and enter the app registration's tenant id.
  14. Select "ida:RedirectUri". In the Properties panel, select "value" and enter the app registration's redirect URI.
    • "ida:PostLogoutUri" is not implemented at this time.
  15. Close the Collection Editor.
  16. In the "Actions" panel, select "Apply".
  17. Restart the Grooper app pool (In the Connections panel, select "Application Pools". Select "GrooperAppPool" from the list. In the Actions panel, select "Recycle").

Configuring OAuth for GWS

Configuring OAuth for the GWS website will use OAuth client credentials.

OAuth also allows secures "app to app" communication. This is what allows Grooper's AI Assistants to integrate with Azure bot services, extending AI Assistants to channels like Teams, Slack and email. The Grooper Web Services (GWS) API handles communication between Grooper assets (such as an AI Assistant) and external applications (such as an Azure bot resource). With both applications registered in Entra ID (i.e. Grooper and an Azure bot), OAuth authenticates their communication between each other.

  • A full write up on integrating AI Assistants with Azure bot services can be found in the Azure Bot Service article.


To secure communication between the GWS API and other applications with OAuth, you will need:

  • The Azure tenant ID
  • The Grooper app registration's client ID
  • The client id and client secret for each external application (i.e. each Azure bot).

Configuration steps:

  • BE AWARE! You will need to do this every time you install Grooper Web Client, including when you install new minor builds. Installing Grooper Web Client will wipe clean all previous settings entered in the website's configuration file.
  1. On the Grooper web server, open Internet Information Services (IIS) Manager.
  2. In the "Connections" panel, navigate to the GWS website.
  3. Under "IIS", open "Authentication".
  4. Select "Windows Authentication". In the "Actions" panel, select "Disable".
  5. If disabled, select "Anonymous Authentication". In the "Actions" panel, select "Enable".
  6. Go back to the GWS website.
  7. Under "Management", open the "Configuration Editor".
  8. Using the "Section" dropdown, select "appSettings".
  9. Open the "(Collection)" editor.
  10. Select "ida:ClientId". In the Properties panel, select "value" and enter the Grooper app registration's client id.
  11. Verify "ida:AADInstance" is "https://login.microsoftonline.com/". This value should be present by default.
  12. Select "ida:TenantId". In the Properties panel, select "value" and enter the Grooper app registration's tenant id.
  13. Select "bot:ClientId:1". For "value" in the Properties panel, you will enter an Azure bot's "Microsoft App ID".
    • Multiple Azure Bot resources can be added using the format "bot:ClientId:2", "bot:ClientId:3", etc.
  14. (Optional) Select "AppUrl". In the Properties panel enter the Grooper application's URL (replace "{insert_grooper_url}" with the web server's machine name or its domain name).
    • This is required if you want an AI Assistant to send links in an Azure bot's response that can be opened in Grooper. When OAuth is also configured for the Grooper website, this will take the user to Grooper, presenting them with an OAuth login screen.
  15. Close the Collection Editor.
  16. In the "Actions" panel, select "Apply".
  17. Restart the Grooper app pool (In the Connections panel, select "Application Pools". Select "GrooperAppPool" from the list. In the Actions panel, select "Recycle").
Retrieved from "https://wiki.grooper.com/index.php?title=OAuth_Setup&oldid=31067"