Okta Single Sign-on (SSO) Setup Guide

okta sso setup guide this guide walks you through setting up single sign on (sso) with okta for your yogen organization prerequisites • active okta organization with admin access • organization admin role in getyogen • your organization’s domain registered with okta benefits of sso • simplified login users sign in once with their okta credentials • enhanced security centralized authentication and access control • automatic user sync employee count, user profiles, and team mem berships sync automatically from okta • team auto mapping automatically creates teams from okta groups and assigns users • profile synchronization keeps job titles, departments, locations, and managers up to date • optional enforcement require all users to use sso instead of pass words step 1 create okta application log in to your okta admin console navigate to applications → applications click “create app integration” select the following options • sign in method oidc openid connect • application type web application click “next” step 2 configure application settings general settings • app name getyogen sso • app logo (optional) upload your company logo sign in redirect uris add the following redirect uri based on your environment • production https //yourdomain com/oidc/callback https //yourdomain com/oidc/callback • development http //localhost 3000/oidc/callback http //localhost 3000/oidc/callback 1 sign out redirect uris leave empty for now assignments • select which user groups should have access to getyogen • you can assign everyone or specific groups save click “save” to create the application step 3 enable client credentials grant type to allow getyogen to validate your client secret during “test connection”, you need to enable the client credentials grant type on the application details page, scroll to general settings click “edit” under grant type, ensure the following are checked • ￿ authorization code (should already be checked) • ￿ client credentials (enable this) click “save” why is this needed? getyogen uses the client credentials grant type to verify that your client id and client secret are correct when you click “test connection” this ensures you catch credential errors before saving your sso configuration step 4 copy application credentials after creation, you’ll see the application details page copy the client id (visible on the “general” tab) click “show” next to “client secret” copy the client secret immediately • ￿ store this securely you won’t be able to view it again step 5 get oidc endpoints in okta admin console, go to security → api click on authorization servers click on the default authorization server find the issuer section on this page • it will show something like https //yourcompany okta com/oauth2/default https //yourcompany okta com/oauth2/default • note your okta domain from the issuer url (e g , yourcompany okta com) 2 important you are not entering these urls into okta you will construct them and enter them into getyogen in step 5 using your okta domain from the issuer, construct the following endpoint urls • authorization url https //{youroktadomain}/oauth2/default/v1/authorize • token url https //{youroktadomain}/oauth2/default/v1/token • jwks uri https //{youroktadomain}/oauth2/default/v1/keys example if your issuer shows https //acmecorp okta com/oauth2/default https //acmecorp okta com/oauth2/default , then authorization url https //acmecorp okta com/oauth2/default/v1/authorize https //acmecorp okta com/oauth2/default/v1/authorize token url https //acmecorp okta com/oauth2/default/v1/token https //acmecorp okta com/oauth2/default/v1/token jwks uri https //acmecorp okta com/oauth2/default/v1/keys https //acmecorp okta com/oauth2/default/v1/keys step 6 configure sso in getyogen log in to getyogen as an organization admin navigate to settings → single sign on click “set up sso” basic configuration tab enter the values you copied • client id (from step 3) • client secret (from step 3) • authorization url (from step 4) • token url (from step 4) • jwks uri (from step 4) • additional email domains (optional) enter additional email do mains for contractors or partners who use sso but have different email domains (e g , atbabers com, partner com) domain matching the system automatically allows sso for email do mains from your company website (settings → company info) email do mains from your org url (settings → org info) any additional domains you specify above example if your company is getyogen com but you have contractors with @atbabers com emails in your okta organization, add atbabers com to addi tional email domains optional check “enforce sso” if you want to disable password logins test the configuration click “test connection” verify you see a success message if you see errors, double check your urls and credentials 3 save click “save configuration” when ready step 7 (optional) enable advanced sync features to enable automatic synchronization of employee count, user profiles, and team mappings from okta create okta api token in okta admin console, go to security → api → tokens click “create token” name getyogen api click “create token” copy the token immediately (you won’t see it again) required permissions the api token needs read access to users (to count active employees and fetch profile data) groups (to auto create teams from okta groups) configure in getyogen go to settings → single sign on → advanced settings enter • okta api token (token from above) • okta domain company okta com (without https //) check “enable advanced sync (employee count, user profiles, team mapping)” click “save advanced settings” optionally click “sync now” to test what gets synced when advanced sync is enabled, the following data syncs automatically on user login organization data total count of active employees in okta user profile data job title department office location manager’s email address team memberships automatically creates teams from okta groups adds users to teams based on their group memberships excludes system groups (e g , “everyone”, “administrators”) note profile data only updates for fields originally synced from okta manual changes to user profiles are preserved 4 step 7 test sso login open a new incognito/private browser window go to getyogen login page enter an email address from your okta organization you should see “sso available for your organization” click “sign in with okta” you’ll be redirected to okta to authenticate after authentication, you’ll be redirected back to getyogen troubleshooting “invalid client credentials” cause client id or client secret is incorrect solution verify you copied the credentials correctly from okta check for extra spaces or characters regenerate the client secret if needed “redirect uri mismatch” cause the callback url doesn’t match what’s configured in okta solution ensure the redirect uri in okta exactly matches {yourdomain}/oidc/callback check for trailing slashes verify you’re using the correct protocol (https vs http) “sso is not configured for your organization” cause the configuration is not enabled or the email domain doesn’t match solution verify sso is enabled in getyogen settings check that the user’s email domain matches your okta organization users can’t sign in cause users aren’t assigned to the okta application solution in okta, go to applications → getyogen sso → assign ments verify the user or their group is assigned add assignments as needed employee count or user data not syncing cause api token is missing, invalid, or lacks permissions solution verify the okta api token is entered correctly check the okta domain is correct (without https //) ensure the api token has read permis sions for users and groups try creating a new api token with appropriate scopes check that “enable advanced sync” is checked in advanced settings 5 teams not being created from okta groups cause group data not accessible or sync disabled solution verify the api token has permission to read groups check that users are assigned to groups in okta system groups like “everyone” are in tentionally excluded look for team names with ” (okta)” suffix if there are naming conflicts check team creation in getyogen after a user from that group logs in email domain not recognized for sso cause email domain doesn’t match organization’s configured domains solution ensure your company website (settings → company info) con tains your primary domain ensure your org url (settings → org info) contains your primary domain for contractors/partners with different email domains, add them to additional email domains in the sso configuration (e g , atbabers com, partner com) domains are automatically extracted and normalized from urls example https //www getyogen com/ https //www getyogen com/ → matches user\@getyogen com mailto\ user\@getyogen com “client id format is invalid” cause the client id doesn’t match okta’s format requirements solution okta client ids are exactly 20 alphanumeric characters verify you copied the entire client id from okta check for extra spaces at the beginning or end don’t include any labels like “client id ” in the field “configuration urls must all be from the same okta domain” cause the authorization url, token url, and jwks uri are from different okta domains or tenants solution verify all three urls use the exact same okta domain exam ple all should use company okta com, not mixing company okta com and company dev okta com double check you constructed the urls correctly from your issuer url ensure you’re using the same authorization server (typ ically /oauth2/default/) “jwks endpoint did not return valid key data” cause the jwks uri is incorrect or the authorization server has no keys configured solution verify the jwks uri follows the pattern https //{yourdomain}/oauth2/default/v1/keys test the jwks uri in a browser it should return json with a “keys” array ensure you’re using the correct authorization server in okta check that the authorization server is active and has keys configured 6 “client credentials grant type is not enabled” cause the okta application doesn’t have client credentials grant type en abled solution 1 go to your okta application settings 2 navigate to general settings 3 click “edit” 4 under grant type, ensure both are checked authorization code client credentials 5 click “save” 6 return to getyogen and try “test connection” again why is this needed? getyogen validates your client id and secret are correct during “test connection” using the client credentials flow this catches credential errors before you save your configuration “invalid client id or client secret” cause the credentials you entered don’t match what’s configured in okta solution double check you copied the client id and client secret correctly in okta, regenerate the client secret if you’re unsure ensure there are no extra spaces or hidden characters try copying the credentials again from okta verify you’re looking at the correct okta application required scopes your okta application must have these scopes enabled • openid required for oidc • profile user profile information • email user email address • phone user phone number (optional but recommended) to verify scopes 1 go to applications → getyogen sso 2 click “okta api scopes” tab 3 ensure the above scopes are granted security best practices enforce sso once testing is complete, consider enforcing sso to disable password logins regular audits periodically review who has access to the getyogen app in okta api token security store your okta api token securely and rotate it regularly monitor logs review authentication logs in both okta and getyogen mfa enable multi factor authentication in okta for additional security 7 managing sso disabling sso go to settings → single sign on click the delete/disable button users will revert to password based login updating configuration go to settings → single sign on update any fields as needed click “test connection” to verify click “save configuration” viewing sso status the basic configuration tab shows whether sso is enabled when it was last updated whether sso is enforced the advanced settings tab shows advanced sync status (employee count, profiles, teams) last sync timestamp manual sync button for testing support if you encounter issues not covered in this guide check the getyogen application logs review okta system logs for authentication attempts contact getyogen support with • your organization id • timestamp of the error • screenshot of any error messages • steps to reproduce the issue additional resources • okta oidc documentation • openid connect specification • getyogen security documentation last updated 2025 11 22