OIDC

creating an authorization source obtain the client id and client secret from your third party system these credentials must be created based on the url of your ui these values will be needed in later steps from the main dashboard, click system on the left menu from the left menu, click auth sources from the left menu, click new name a name to identify this authorization source this name will appear on the sign on button on the ui login page select the driver from the list of available options the open id setting provides a generic option that could work for any open id source, while specific options, such as google, okta, and entra id, provide wrappers with configuration forms that are specialized for that particular implementation redirect uri automatically populated with the address of the ui and normally shouldn't be changed this address must be a public address or otherwise accessible by the remote oauth source client id and client secret values generated on the remote oauth source, based on your ui url remote user fields define one or more fields that can be used for locating users in the oauth source the field is auto populated with a default list of common fields that work across various common oauth implementations for security reasons, it's good practice to only use fields that end users can't change additional configuration recommende recommende d fields update remote user updates the remote username field of the user to the unique id from the oauth source enabling this option allows for initially locating the user based on more friendly fields (defined in remote user fields , above) but subsequently changing the remote username field to match a unique id from the source system this ensures the user record remains constant even as extraneous fields such as email address or friendly username may change over time update user email address updates email address field based on email address from the oauth source update user display name updates user display name based on display name from the oauth source optional fields optional fields scope varies with different implementations; consult source oauth2 documentation, where appropriate for more information in most cases the default "openid profile email" will work group scope varies with different implementations; consult source oauth2 documentation for more information in most cases, the group scope can be set to the word "groups" group scope is required when using the update group membership option require verified email address (for oauth2 implementations that support verifying user email address) only allow authentication of users with the verified email address flag enabled/true in the source update group membership update user's group membership (each time user logs in) to correspond with group membership from the oauth source show in a menu changes the display to show a drop down menu instead of a list debug mode turns on verbose logging for the authorization source this should only be enabled when troubleshooting leaving this on can potentially impact the performance of your vdc user creation auto create users users are created automatically (on demand, upon initial login) corresponding to users in the oauth source use a single asterisk to apply to all users auto create users in group only users within specified oauth2 source groups are created automatically, on demand, upon initial login a specific group name can be entered or a regular expression to include groups with a matching pattern in order to auto create users based on group(s), the auto create users field should be blank users that will use an external authorization source can optionally be created manually in the ui; when creating the new user select the appropriate authorization source in the dropdown list set remote username to match one of the fields defined in remote user fields (fields that are used to find the user in the external authorization source) typically, it is best to use the user's login name or unique user id login styling login styling defines the appearance of the sign in button on the login page sign in button background color background color for the sign in button sign in button text color text color of the sign in button sign in button font awesome icon specifies an alternate icon for the sign in button; a listing of available font awesome icons can be found https //fontawesome com/v4/cheatsheet/ sign in button font awesome icon color specifies an alternate color for the sign in button; use standard hex codes (e g #ff5733) configuration configuring a central identity provider involves the following steps create an upstream authorization source (e g google, entra id, okta, etc ) on the system that will act as the identity provider set up the platform as an /#oidc provider configure the ui as an /#oidc client oidc provider prerequisites prerequisites administrative access to your tenant valid ssl certificate installed on the tenant basic understanding of oidc concepts urls of client tenants that will use this authentication configuration configuration access oidc settings from the top menu , click system > oidc applications from the left menu, click new configure basic settings enter a descriptive name for the application make sure the enabled checkbox is checked add an optional description set up redirect uris redirect uri enter the callback url(s) where users will be redirected after authentication using the format https //corpname example com multiple uri's can be added for different client systems you can use wildcards in redirect uris for multiple systems, use https //corpname site example com for multiple subdomains, use https //systemname example com configure authentication options force authrorization source optionally select a third party provider map user choose if all verified users should map to a specific account scope settings profile , email , groups can be toggled for access restrictions if needed save configuration click submit the system will then generate a client id and client secret retrieving client credentials from the main dashboard, click system from the left menu, click oidc applications double click your oidc application your client id , client secret , and well known configuration url will be displayed best practices create separate oidc applications for different client groups regularly review and update access restrictions use specific redirect uris instead of wildcards when possible document which systems are using each oidc application troubleshooting authentication fails verify ssl certificate is valid and not expired check redirect uri matches exactly ensure client id and secret are correctly copied scope access denied verify required scopes are enabled check user permissions in restriction settings redirect problems confirm url format matches redirect uri verify wildcard patterns if used check for ssl certificate issues oidc client prerequisites prerequisites access to the tenant's oidc provider well known configuration url from the provider client id and client secret from the provider administrative access to the client's tenant system full url of the client's tenant configuration configuration access authorization settings from the top menu , click system > auth sources from the left menu, click new configure basic settings name enter an identifier for this auth source (appears on login button) driver select openid (well known config) well known url enter the well known configuration url redirect uri enter the full url of this vergeos system client id paste the client id from the provider client secret paste the client secret from the provider configure authentication parameters default values typically work best for these settings token hint parameter leave as post logout redirect uri redirect parameter leave as post logout redirect uri scope leave as openid profile email groups group scope leave as groups enable recommended options check the following boxes for optimal functionality decode id token update remote user update user email address update user display name update group membership configure user creation choose your prefreeed user creation method auto create users enter to create all users automatically auto create users in group specify groups for restricted auto creation save configuration click submit best practices test authentication with a test user before rolling out to production keep debug mode disabled unless troubleshooting document your configuration choices for future reference regularly verify user synchronization is working as expected troubleshooting authentication fails verify client id and secret are correct check well known configuration url ensure redirect uri matches exactly user sync issues verify group scope is enabled check group membership settings enable debug mode temporarily login button missing verify authorization source is enabled check login styling settings clear browser cache