Setting Up Duo Sign-In (OIDC)

This guide shows how to let users sign in to GlobalForms through Duo Single Sign-On, using OpenID Connect (OIDC). Users sign in with their existing directory credentials and complete Duo two-factor authentication before reaching GlobalForms.

Before you begin

You will need:

• An account with the Owner or Administrator role in the Duo Admin Panel.

• Duo Single Sign-On already set up, with an authentication source (such as Active Directory or a SAML identity provider) that provides each user's email address. See Duo's documentation for Duo Single Sign-On.

• 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 email address. Duo can only sign in people who already have a matching GlobalForms user record.

Part 1: Add GlobalForms to Duo

1. Create the application

1. Sign in to the Duo Admin Panel and go to Applications → Protect an Application.

2. Search for Generic OIDC Relying Party and select Protect.

2. Configure the relying party

On the application's page, under Relying Party:

3. Name the application and choose who can use it

1. Under Settings, enter a Name such as GlobalForms. Users see this name in the Duo Prompt.

2. Under User access, choose the groups that may use GlobalForms (recommended), or allow access to all users.

3. Assign a policy if GlobalForms needs different two-factor rules from your global policy.

4. Select Save.

4. Record your credentials

In the application's Metadata section, copy:

• Client ID

• Client Secret. Treat it like a password: don't email it or store it in shared documents.

• Issuer. It looks like https://sso-<id>.sso.duosecurity.com/oidc/<client ID>.

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": "<Issuer from the Duo Metadata section>",
     "clientId": "<Client ID from Duo>",
     "clientSecret": "<Client Secret from Duo>",
     "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, for example, Sign in with Duo or Sign in with your company account 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 Duo confirms who the user is, GlobalForms looks in the selected user resources for a record whose usernameField (default email) matches the email address Duo sends. Upper and lower case are ignored.

• The email comes from your Duo Single Sign-On authentication source, through the claim mapping in Part 1. Check that the attribute is filled in for each user.

• If the email claim is missing, GlobalForms falls back to the user's Duo username, which usually won't match an email address. Fix the claim mapping rather than changing GlobalForms.

Part 5: Test the sign-in

1. Make sure your test user is enrolled in Duo and is in a group allowed to use the application.

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

3. Select the sign-in button, sign in with your directory credentials, and approve the Duo two-factor prompt.

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

Troubleshooting

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.

• Limit User access to the groups that need GlobalForms.

• Duo policies, such as device health or location rules, apply to GlobalForms sign-in like any other application.

• If the client secret is ever exposed, reset it in the Duo Admin Panel, update clientSecret and restart GlobalForms.

Related pages

• Single Sign-On with OpenID Connect

• User Management

• Configuring HTTPS

• Configuration Files