Setting Up Microsoft Entra ID Sign-In (OIDC)

This guide shows how to let users sign in to GlobalForms with their Microsoft work or school account through Microsoft Entra ID (formerly Azure Active Directory), using OpenID Connect (OIDC).

Before you begin

You will need:

• An account that can register applications in the Microsoft Entra admin center (for example, the Application Administrator role).

• The public HTTPS address of your GlobalForms server, for example https://forms.example.com. See Configuring HTTPS.

• Access to config\local.json on the GlobalForms server, and permission to restart the GlobalForms service.

• A GlobalForms user resource whose records contain each user's Microsoft sign-in email address. Entra ID can only sign in people who already have a matching GlobalForms user record.

Part 1: Register GlobalForms in Microsoft Entra ID

1. Create the app registration

1. Sign in to the Microsoft Entra admin center.

2. Go to Identity → Applications → App registrations and select New registration.

3. Enter a Name, such as GlobalForms.

4. Under Supported account types, choose Accounts in this organizational directory only (Single tenant).

5. Under Redirect URI, select the Web platform and enter your GlobalForms callback address:

   https://forms.example.com/oidc/callback
   

6. Select Register.

2. Record the IDs

On the app's Overview page, copy:

• Application (client) ID: this is your clientId.

• Directory (tenant) ID: this goes in your issuer URL.

3. Create a client secret

1. Open Certificates & secrets → Client secrets and select New client secret.

2. Enter a description and choose an expiration period, then select Add.

3. Copy the secret's Value right away. Entra ID shows it only once. Do not copy the Secret ID, which is a different value.

4. Check API permissions

1. Open API permissions.

2. Make sure these Microsoft Graph delegated permissions are listed: openid, email and profile. Add any that are missing with Add a permission → Microsoft Graph → Delegated permissions.

3. If your organization doesn't let users consent to apps themselves, select Grant admin consent.

5. Add the email claim

Entra ID includes the user's email address in the sign-in token only when you ask for it:

1. Open Token configuration and select Add optional claim.

2. Choose token type ID, select email, then select Add.

3. If prompted, allow the Microsoft Graph email permission to be added.

6. Limit who can sign in (recommended)

By default, every user in your directory can sign in to the app. To allow only selected users or groups:

1. Go to Identity → Applications → Enterprise applications and open the GlobalForms app.

2. Under Properties, set Assignment required? to Yes and save.

3. Under Users and groups, add the users or groups that should have access.

Part 2: Configure GlobalForms

1. Open config\local.json in the GlobalForms install folder (C:\GlobalForms by default).

2. Add or update the oidc section, replacing the placeholders with your values:

   JSON

   "oidc": {
     "issuer": "https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0",
     "clientId": "<Application (client) ID>",
     "clientSecret": "<Client secret value>",
     "redirectUrl": "https://forms.example.com/oidc/callback"
   }
   

3. Save the file and restart the GlobalForms service.

For all oidc settings, see Single Sign-On with OpenID Connect.

Part 3: Add the sign-in button to the sign-in page

Add a button labeled Sign in with Microsoft to the User Login form (path user/login), which is the form on the GlobalForms sign-in page. In short:

• Button Action: Submit, with Button Custom Logic data.name="oidc"; data.password="oidc"; data.oidc=true

• Button Property Name (API tab): oidc

• OIDC Login action: your user resource, triggered only if the button Equals true

• Existing Login action: triggered only if the button Not Equal true

For the full steps, see Step 3 in Single Sign-On with OpenID Connect.

Part 4: Make sure users can be matched

After Entra ID confirms who the user is, GlobalForms looks in the selected user resources for a record whose usernameField (default email) matches the user's email from Entra ID. Upper and lower case are ignored.

• The email Entra ID sends comes from the user's Email (mail) property. Check that it is filled in for each user.

• If a user has no email, GlobalForms uses their Microsoft sign-in name (user principal name, such as jsmith@example.com) instead.

• If your users' sign-in names and email addresses differ, and your GlobalForms records store sign-in names, set "claimField": "preferred_username" so GlobalForms always matches on the sign-in name.

Part 5: Test the sign-in

1. Open the GlobalForms sign-in page in a private browser window.

2. Select Sign in with Microsoft.

3. Sign in with a Microsoft account that has a matching GlobalForms user record. The first time, you may be asked to accept the app's permissions.

4. Confirm you return to GlobalForms signed in as that user, and that name-and-password sign-in still works.

Renewing the client secret

1. Before the current secret expires, open the app registration's Certificates & secrets and create a new client secret.

2. Replace clientSecret in config\local.json with the new value and restart the GlobalForms service.

3. Test sign-in, then delete the old secret in Entra ID.

Troubleshooting

Microsoft error messages start with a code such as AADSTS50011.

For messages shown by GlobalForms, see the troubleshooting table in Single Sign-On with OpenID Connect.

Security notes

• Never run production workloads in GlobalForms without HTTPS. Sign-in tokens and user data travel between the browser and the server and can be intercepted without it. Entra ID accepts plain http redirect URIs only for localhost.

• Treat the client secret like a password. Don't email it or store it in shared documents.

• Turn on Assignment required so only the people who need GlobalForms can sign in.

• Conditional Access and multi-factor authentication policies in Entra ID apply to GlobalForms sign-in like any other app.

Related pages

• Single Sign-On with OpenID Connect

• User Management

• Configuring HTTPS

• Configuration Files