HOW TO: Set Up Authentication using OAuth2.0

Summary

RMTrack supports the use of OAuth2.0 for application login/authorization. The configuration of an OAuth2.0 provider is beyond the scope of this document.

Correctly configuring OAuth2 can involve a few attempts, and RMTrack will not be available for users. Our support team would be happy to have someone on standby for assistance when you're making the change. Please contact support@rmtrack.com to arrange a date and time.

NOTE: The configuration below refers primarily to seting up Microsoft Entra ID (a.k.a. Azure AD). If you are using another OAuth2.0 provider, please contact support@rmtrack.com. 

Limitations

• Your installation MUST be configured to use HTTPS. Your system administrator can enable this, though depending on your specific circumstances this may take time and effort (and possibly even an annual fee for the SSL certificate).
• If your RMTrack installation is using the E-Signature optional feature, you MUST use a separate password instead of the same password as a user logged in with.
• RMTrack's public user signup feature will not be available.

Configuration

STEP 1: Locate the following line in the web.config file (found in the RMTrack installation folder):

<add key="owin:AutomaticAppStartup" value="false" />

STEP 2: Replace that line with the following:

<add key="owin:AutomaticAppStartup" value="true" />
<add key="owin:appStartup" value="RMTrack.Auth.OwinStartup, RMTrack.Auth" />
<add key="auth:TenantId" value="[TenantName].onmicrosoft.com" />
<add key="auth:ClientId" value="[ClientId]" />
<add key="auth:ClientSecret" value="[ClientSecret]" />
<add key="auth:Authority" value="https://login.microsoftonline.com/[TenantName].onmicrosoft.com/v2.0" />
<add key="auth:RedirectUrl" value="https://[WebServerUrl]/callback" />
<add key="auth:PostLogoutRedirectUrl" value="https://[WebServerUrl]/Security/Logout.aspx" />
<add key="auth:FriendlyName" value="RMTrack User Secondary ID label" />
<add key="auth:NameClaimName" value="preferred_username" />

STEP 3: Replace the [placeholders] in the new lines:

• [TenantName] - see AppSetting notes 3 and 6 below (occurs in 2 places) 
• [ClientId] - see AppSetting note 4 below
• [ClientSecret] - see AppSetting note 5 below
• [WebServerUrl] - see AppSetting notes 7 and 8 (occurs in 2 places) 

STEP 4: Verify that authentication mode is FORMS:  <authentication mode="Forms">

STEP 5: Explicitly remove the FormsAuthentication module under HTTP Modules. NOTE: this will be commented out in the default in the web.config.

<modules>
      <remove name="FormsAuthentication" />
</modules>

AppSettings Notes

1. owin:AutomaticAppStartup must have the value "true".
2. owin:appStartup must have the value "RMTrack.Application.OwinStartup, RMTrack.Application".
3. auth:TenantId is assigned when an organization signs up for a Microsoft cloud service. For Entra ID/Azure AD it is the first part of the Primary Domain field e.g. rmtracktestinggmail.onmicrosoft.com.
4. auth:ClientId is the client id assigned by the authentication provider for your installation of RMTrack. For Entra ID/Azure AD this is found under "App registrations".
5. auth:ClientSecret may have been provided by the authentication provider. Not all providers define a ClientSecret. Leave empty or remove if the provider does not define a client secret.
6. auth:Authority is the base URL where the authentication provider publishes the OIDC standard ".well-known/openid-configuration" document. For Entra ID/Azure AD it looks like "https://login.microsoftonline.com/[TenantName].onmicrosoft.com/v2.0". 
7. auth:RedirectUrl must be the full url of the "callback" page. In Entra ID/Azure AD this value must be added to the "RedirectURLs" for the "App registration".
8. auth:PostLogoutRedirectUrl must be the full url of the "logout" page. 
9. auth:FriendlyName is used for labeling the secondary user id on the RMTrack user details page.
10. auth:NameClaimName is used to select the authentication provider claim that contains a user's identifier. Typically this is the user's email address, and the name of the claim varies by provider. Consult you authentication provider administrator for assistance.

IIS Settings

The application must have Anonymous access enabled, ASP.NET Impersonation disabled, Basic Authentication disabled, Forms Authentication disabled, and Windows authentication disabled.

References

Tutorial: Register an app with Microsoft Entra ID: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/walkthrough-register-app-azure-active-directory

Keywords: OAUTH OWIN OIDC AZURE AUTHENTICATION LOGIN ENTRA