Setting Up Okta Sign-In (OIDC) | GlobalForms 10 Administration

This guide shows how to let users sign in to GlobalForms with their Okta account, using OpenID Connect (OIDC).

This feature requires GlobalForms version 10.17.1 or greater.

Before you begin

You will need:

Administrator access to your Okta Admin Console.
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 Okta email address. Okta can only sign in people who already have a matching GlobalForms user record.

Part 1: Create the app integration in Okta

1. Create the integration

In the Okta Admin Console, go to Applications → Applications and select Create App Integration.
Choose OIDC - OpenID Connect as the sign-in method and Web Application as the application type, then select Next.

2. Configure the integration

Setting	Value
App integration name	For example, `GlobalForms`
Grant type	Authorization Code (selected by default). Other grant types are not needed.
Sign-in redirect URIs	Replace the example with your GlobalForms callback address, for example `https://forms.example.com/oidc/callback`
Sign-out redirect URIs	Remove the example entry. It isn't used.
Controlled access	Limit access to selected groups (recommended), then choose the groups that should use GlobalForms. Or choose Allow everyone in your organization to access.

Select Save.

The sign-in redirect URI must exactly match redirectUrl in the GlobalForms configuration (Part 2), including https, host name, port and path.

3. Record your credentials

On the app's General tab, under Client Credentials, copy the Client ID and the Client secret. Treat the secret like a password: don't email it or store it in shared documents.

4. Find your issuer URL

The issuer depends on which Okta authorization server you use:

Authorization server	Issuer URL
Default custom authorization server	`https://<your-okta-domain>/oauth2/default`
Another custom authorization server	The Issuer URI shown under Security → API → Authorization Servers
Org authorization server (if your Okta plan has no custom authorization servers)	`https://<your-okta-domain>`

Your Okta domain is shown in the upper-right menu of the Admin Console, for example example.okta.com. If you use a custom domain for Okta sign-in, use that domain instead.

If you use a custom authorization server, open it under Security → API → Authorization Servers → Access Policies and make sure a policy and rule apply to the GlobalForms app and allow the Authorization Code grant. The default server's Default Policy allows all apps unless it has been changed.

Part 2: Configure GlobalForms

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

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

JSON

"oidc": {
  "issuer": "https://example.okta.com/oauth2/default",
  "clientId": "<Client ID from Okta>",
  "clientSecret": "<Client secret from Okta>",
  "redirectUrl": "https://forms.example.com/oidc/callback"
}

Save the file and restart the GlobalForms service.

Setting	What to enter
`issuer`	The issuer URL from Part 1, step 4. Don't add a trailing slash.
`clientId`	The Client ID from Okta
`clientSecret`	The Client secret from Okta
`redirectUrl`	The exact sign-in redirect URI you registered in Part 1
`prompt`	Optional. `login` makes Okta ask for credentials every time, even if the user already has an Okta session.

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

Add a button labeled Sign in with Okta 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 Okta confirms who the user is, GlobalForms looks in the selected user resources for a record whose usernameField (default email) matches the Primary email on the user's Okta profile. Upper and lower case are ignored.

Check that each user's primary email in Okta matches the email in their GlobalForms user record.
If your GlobalForms records store Okta usernames instead of email addresses, set "claimField": "preferred_username" so GlobalForms matches on the Okta username.

Single sign-on does not create GlobalForms accounts. Create or update the user records before asking people to sign in. Assigning a user to the app in Okta doesn't add them to GlobalForms.

Make sure your test user is assigned to the app in Okta, directly or through a group.
Open the GlobalForms sign-in page in a private browser window.
Select Sign in with Okta and sign in, including any multi-factor prompt your Okta policies require.
Confirm you return to GlobalForms signed in as the matching user, and that name-and-password sign-in still works.

Troubleshooting

Message or symptom	Cause and fix
Okta says the `redirect_uri` must be a sign-in redirect URI in the client app settings	The sign-in redirect URI in Okta doesn't exactly match `redirectUrl`. Compare protocol, host name, port and path.
Okta says the user is not assigned to the client application	Assign the user, or a group they belong to, on the app's Assignments tab.
`invalid_client`	The Client ID or Client secret is wrong or has extra spaces. Copy both again from the app's General tab.
Okta says policy evaluation failed, or `no_matching_policy`	The custom authorization server has no access policy rule for this app. Add one under Security → API → Authorization Servers → Access Policies.
GlobalForms shows an error right after you select the sign-in button	GlobalForms couldn't reach the issuer. Check the `issuer` URL (no trailing slash, correct authorization server) and that the server can reach your Okta domain over HTTPS.
`Unable to complete OIDC login. User not found: …`	No GlobalForms user record matches the value shown. Check the user's primary email in Okta and in GlobalForms, or see Part 4.

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 access to the groups that need GlobalForms, rather than everyone in your organization.
Okta sign-on and multi-factor policies apply to GlobalForms sign-in like any other app.
If the client secret is ever exposed, generate a new one on the app's General tab, update clientSecret and restart GlobalForms.