OAuth Setup

From Grooper Wiki

OAuth is an authentication method that allows third-party applications web access without sharing passwords.

  • Microsoft Entra ID (formerly Azure Active Directory) is the only supported OAuth provider at this time.

Benefits to OAuth:

  • Security - Users do not have to share their passwords with third party applications.
  • 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.

Both the Grooper website and the GWS website can be configured with OAuth authentication.

  • 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 - 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.

OAuth authentication for application users (Grooper)

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 an Azure 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.

  • 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.


Create an app registration in Entra ID for Grooper.

  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://{domainURI}/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.
  9. 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
  10. Create a client secret and copy it down (You will need this later).
    • In the "Overview" screen, click the "Add a certificate or secret" link next to "Client credentials".
    • Press the "New client secret" button.
    • Name the client secret (Description) and set an expiration date (Expiration).
    • Press the "Add" button.
    • 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.
  11. Under "Manage", go to the "Authentication" screen.
    • If you have not done so already, you can configure a Redirect URI here.
  12. Under "Implicit grand and hybrid flows", check the box next to "ID tokens (used for implicit and hybrid flows)".
  13. Press the "Save" button.

Configure the Grooper website.

  • 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").

OAuth client credentials for apps (GWS)

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).

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


Retrieved from "https://wiki.grooper.com/index.php?title=OAuth_Setup&oldid=29564"