Skip to main content

OpenID Connect (Google Workspace, Okta and others)

Overview​

Any identity provider that speaks OpenID Connect can sign people in to a vastframe cloud organization: Google Workspace, Okta, Auth0, Keycloak and others. You register a web app at the provider, then enter its issuer URL, client ID and client secret in Admin › Sign-in.

Prerequisites​

  • Org Admin in vastframe.
  • Admin access to your identity provider.
  • People who will sign in are members of your organization, or you've verified your email domain and allowed anyone on it to join.
  • Your provider sends email_verified: true in the ID token. vastframe only matches a person by email, or lets them auto-join, when the address is verified; otherwise it matches on the provider's subject alone.

Permissions​

RequirementValue
Application typeWeb, confidential client (has a client secret)
Grant typeAuthorization code (vastframe also sends PKCE and a nonce)
Redirect URIhttps://auth.<your-org-domain>/callback (copy it from Admin › Sign-in)
Scopesopenid profile email
Discovery<issuer>/.well-known/openid-configuration must be reachable
EmailThe ID token must include email (or preferred_username set to the email)

vastframe checks the discovery document when you test and when you save. The issuer in that document must match the URL you enter exactly.

Setup steps​

  1. Open Admin › Sign-in and select Other OpenID Connect.
  2. Copy the redirect URI.
  3. Register a web app at your provider with that redirect URI (see the walkthroughs below).
  4. Back in vastframe, enter Issuer URL, Application (client) ID and Client secret.
  5. Select Test connection, then Save and turn on.

Walkthrough: Google Workspace​

  1. In the Google Cloud console, choose a project owned by your Workspace organization.
  2. Configure the OAuth consent screen (in Google Auth Platform) with the user type Internal, so only accounts in your Workspace can sign in.
  3. Go to APIs & Services › Credentials › Create credentials › OAuth client ID.
  4. Choose Web application. Under Authorized redirect URIs, paste the redirect URI from Admin › Sign-in.
  5. Create it and copy the client ID and client secret.
  6. In Admin › Sign-in, enter:
    • Issuer URL: https://accounts.google.com
    • Application (client) ID and Client secret from step 5.
  7. Test connection, then Save and turn on.
warning

Google's issuer is shared by every Google account. Use an Internal consent screen, and rely on vastframe's membership check (only people in Admin › People, or on your verified domains, get in) to keep outsiders out.

Walkthrough: Okta (OIDC)​

  1. In the Okta Admin Console, go to Applications › Applications › Create App Integration.
  2. Choose OIDC - OpenID Connect and Web Application.
  3. Under Sign-in redirect URIs, paste the redirect URI from Admin › Sign-in. Keep the Authorization Code grant type.
  4. Under Assignments, assign the people or groups who should have access.
  5. Save, and copy the client ID and client secret.
  6. Find your issuer URL. For the org authorization server it's https://<your-okta-domain>; for a custom authorization server it's like https://<your-okta-domain>/oauth2/default. Check it by opening <issuer>/.well-known/openid-configuration.
  7. In Admin › Sign-in, enter the issuer, client ID and secret, then Test connection and Save and turn on.
SAML instead?

If your Okta, Ping or ADFS setup is SAML-only, or you also want automatic user provisioning, use Enterprise SSO.

Verify​

  1. Sign in from a private window as a member. You land in the console.
  2. Sign in as a non-member. They see "Not a member yet".
  3. Check Admin › Audit log for sign-in.update.

Troubleshooting​

SymptomCauseFix
"… has no OpenID configuration (HTTP 404)"Wrong issuer URLUse the URL whose /.well-known/openid-configuration loads.
"The provider calls itself …, not …"The issuer doesn't match the discovery documentUse the issuer exactly as the error shows (watch trailing paths).
"An issuer URL (https://…) is required"Missing schemeInclude https://.
redirect_uri_mismatch at the providerThe redirect URI isn't registeredPaste the exact URI from Admin › Sign-in.
"Not a member yet"The person isn't a memberAdd them, or verify your domain and allow joining.
"Not a member yet" for someone who is in Admin › PeopleThe ID token has no email (or preferred_username) matching their addressAdd the email scope or claim at the provider.
Was this page helpful?