Mac sign-in

People can sign in to their Macs with the email address and password they use for VeraID. VeraID stays the source of truth: create, suspend and reset users in VeraID, and their Macs follow.

macOS needs an agent at the login window to talk to an identity provider. VeraID works with agents that accept any OpenID Connect provider, such as XCreds and Jamf Connect. VeraID does not ship its own Mac agent, and Windows sign-in is not available yet.

How it works

1. The first sign-in happens in a browser. The agent shows VeraID’s sign-in page at the login window (the authorization code flow). MFA and Conditional Access apply exactly as they do for any other application. The agent creates the local account from the ID token, using email, name, given_name and family_name.

2. Passwords are checked with the password grant. When the agent needs to check a password without a browser, for example after the user changed it in VeraID, it sends it to the token endpoint with grant_type=password. Only a confidential client with Computer sign-in: allow password verification turned on may do that, and it authenticates with its client secret first. The answer carries a refresh token only when the request names the offline_access scope. A request that names no scope gets the client’s scopes without offline_access.

3. Users who must use MFA never get tokens from a password alone. For a user who has MFA, whose organization or team requires it, or whom a Conditional Access policy asks for it, a correct password is answered with:

   { "error": "invalid_grant", "error_description": "multi-factor authentication required; sign in through the browser" }

   A wrong password gets {"error": "invalid_grant", "error_description": "grant request is invalid"}, the same answer as an unknown user, a locked account or a suspended one. A Conditional Access policy that denies the sign-in gets "sign-in denied by security policy".

Create the client in VeraID

1. Go to Settings > OIDC Clients and click Register New OIDC Client.
2. Click Mac sign-in preset. It fills in:
   • Client type Confidential and application type Web.
   • Redirect URIs https://127.0.0.1/xcreds and https://127.0.0.1/jamfconnect. The agent catches this redirect inside its login window, so nothing listens there. Keep the one your agent is configured with, or replace it with your own.
   • Scopes openid, profile, email and offline_access.
   • Consent turned off.
   • Computer sign-in: allow password verification turned on, with the authorization code and refresh token grants.
3. Create the client and copy the client secret. It is shown once.

The redirect has to be a Web client: the provider refuses an https://127.0.0.1 redirect on a native one.

Password verification needs a Confidential client. VeraID refuses it on a public client, which would let anyone who learns the client ID check passwords. The client secret goes into the agent’s settings on every Mac, so anyone with a managed Mac can read it. Treat it as identifying the client rather than as a strong secret, and rotate it if a Mac’s settings leak. Against someone who has it, the protections are per-user lockout and the per-address limits below.

Values for the agent

Setting	Value
Discovery URL	https://app.veraid.io/api/oidc/{orgId}/.well-known/openid-configuration
Client ID	The client ID shown in Settings > OIDC Clients
Client secret	The secret copied when you created the client
Redirect URI	The redirect URI registered on the client, exactly
Scopes	openid profile email offline_access
Password verification client ID	The same client ID
Username	The user’s email address in VeraID

XCreds

In XCreds’ settings profile, set discoveryURL, clientID, clientSecret and redirectURI to the values above, and scopes to the scopes above. To have XCreds check password changes with the password grant, set shouldUseROPGForPasswordChangeChecking to true. See Twocanoes’ identity provider integration guide for the full list of keys.

Jamf Connect

Set the identity provider to Custom, and set the discovery URL (OIDCDiscoveryURL in the com.jamf.connect.login domain), the client ID, the redirect URI and the password verification client ID (OIDCROPGID) to the values above. See Jamf’s custom identity provider guide.

Check how your agent treats the MFA answer above before rolling out to users who use MFA: VeraID tells it the password was right and that the user must sign in through the browser.

Limits and protections

• Lockout. Wrong passwords count toward the same per-user lockout as the web sign-in page.
• Spraying. Failed password checks are also counted per caller address. A caller with 20 failures within 15 minutes in one organization receives 429 with error=temporarily_unavailable and a Retry-After header until the window ends. Separately, one address may make 300 password checks of any outcome within 15 minutes per organization. Macs that share one public address, such as an office behind NAT, share both counts.
• Load. Password checks are deliberately expensive. When too many arrive at once, the token endpoint answers 503 with error=temporarily_unavailable, and the agent should retry shortly.
• Encoding. A password check must be sent as UTF-8 (or ASCII), so a password with non-ASCII characters arrives intact. One declaring another charset is refused with 400 before the password is checked. Other token requests may also use an ASCII-compatible charset such as ISO-8859-1.
• Your organization only. A client only checks passwords of users in the organization it belongs to.
• Suspended and deactivated users are refused, and their refresh tokens stop working. Deactivating a user also deletes their access tokens. A suspended user’s access tokens from this grant last until they expire, so keep the client’s access token lifetime short.
• Tokens say how the user signed in. The ID token from the password grant carries amr: ["pwd"] and acr: "urn:veraid:ac:pwd". ID tokens from later refreshes do not repeat them.
• Conditional Access policies apply, including policies that target this application.

What is not covered yet

• Windows sign-in.
• Enrolling or tracking the computers themselves. VeraID does not keep a list of the Macs a user signs in to.
• Offline sign-in. That is the agent’s: it keeps the local account, so a Mac without network access signs in with the last password it saw.

OIDC Provider

Grant types, scopes, claims and endpoints. OIDC Provider

Conditional Access

Policies that apply to every sign-in, including the Mac’s. Conditional Access