Guides

OKTA Single Sign On

Suggest Edits

This guide will walk you through configuring Single Sign-On (SSO) with Okta for the Incode Workforce Dashboard, streamlining user authentication and access. Once SSO is set up, users will no longer need to be manually added in the Incode Workforce Dashboard; access will be managed automatically through your organization’s Okta directory. By following these steps, you’ll ensure a seamless and secure login experience to Incode Workforce Dashboard, with role-based access controls to separate permissions for Admins and Helpdesk staff.

Before you begin

Before you begin, ensure you have the following:

  • An Admin account with access to the Incode Workforce Dashboard in your production environment.
  • Initial Workforce settings configured in the Incode Workforce Dashboard.
  • An Admin account with access to your organization’s Okta instance, along with permissions to create and manage applications.

Setup guide

Step 1: Okta SSO application creation

Login into your organization's Okta account to configure new application.

  1. Go to Applications.
  2. Choose Create App integration.
  3. Choose Sign in method OIDC (Token-based OAuth 2.0 authentication for Single Sign-On).
  4. Choose Application Type Web Application.
  5. Click 'Next'
  6. Type in an App integration name for example Incode Workforce Dashboard
  7. Optionally upload Incode logo so you can easily discover Incode Workforce Dashboard in you Okta Dashboard. Please find the Incode logo here.
  8. Select Grant type 'Authorization Code' and 'Refresh Token'.
  9. Under Controlled access, choose Limit access to selected groups.
  10. Select which groups can access workforce dashboard. Typically you would separate your users in two or more groups that map to different roles (Admin and Helpdesk). The same group names will be used in Workforce dashboard in Step 3.
  11. Click 'Save'.

Step 2: OKTA groups assignment

  1. Go to the Sign On tab for the application you just created and click Edit in the OpenID Connect ID Token section.
  2. In the Group claim type section, select Filter.
  3. In the Group claims filter section, leave the default name groups (or add it if the box is empty), and then add the appropriate filter.
  4. Select 'Matches regex' and enter .*.
  5. Click Save.
  6. Click the Back to applications link.
  7. From the More button dropdown menu, click Refresh Application Data.

Step 3: Authentication method configuration

Login into Workforce dashboard with your credentials and navigate to Admin User Management tab.

  1. Click on Authentication Method.
  2. Select Method: 'SSO(OIDC)' and identity provider: 'Okta'.
  3. In Client ID text field paste the Client ID from Okta application created in Step 1. Client ID can be found in General -> Client Credentials
  4. Select 'Client Secret' or 'Public/Private Key' option, depending on your application setup in Okta.
    1. If you chose 'Client secret' in Okta, paste it the secret value into the Incode Workforce Client Secret text field.
    2. If you chose 'Public key / Private key' in Okta, generate a new public key in Incode Workforce, copy it, and add the public key to your application in Okta.
  5. In Issuer URL text field, paste your Okta issuer URL. Typically it is https://yourcompanyname.okta.com
  6. The other endpoints can be usually found in https://yourcompanyname.okta.com/.well-known/oauth-authorization-server
    1. In Authorization URL text field, paste you Okta authorize endpoint URL.
    2. In Token URL text field, paste your Okta token endpoint URL.
    3. In JWKS URL text field, paste your Okta jwks endpoint URL. Example: https://yourcompanyname.okta.com/oauth2/v1/keys
    4. In Userinfo URL text field, paste you Okta userinfo endpoint URL.
  7. Map Workforce roles to your Okta groups.
    1. For Admin role, add one or more Okta group names that contain users who should be granted Admin role in workforce dashboard. Typically, those are groups that you have assigned to the Incode Workforce app in Step 1.
    2. For Helpdesk role, add one or more Okta group names that contain users who should be granted Helpdesk role in workforce dashboard. Typically, those are groups that you have assigned to the Incode Workforce app in Step 1.
      Note that in case the same user assigned in multiple groups that map to different roles, they will be logged in with the highest privilege role, in this case Admin.
  8. Once you've finished the SSO setup, click on Save Button. You will be prompted with generated Redirect URI that you should register in Okta. Copy it and paste it in your Okta application, under General -> General Settings-> Login-> Sign-in redirect URIs field.

🚧

When SSO is configured, users who were manually added in the Workforce Dashboard under the username/password method will no longer have access. Users are no longer managed directly in Incode Workforce but are instead managed entirely via Okta groups. Ensure that all necessary users are assigned to the appropriate groups in Okta with proper role mappings to maintain their access.

Step 4: Review your SSO configuration

  1. Carefully review and compare your SSO configuration in workforce dashboard against your application setup in Okta.
  2. Once you confirmed that configuration is correct, logout from workforce dashboard.
  3. Login with your Okta SSO.
  4. In case of any difficulties or misconfiguration, please contact support for help.

FAQs and Troubleshooting

Q1. What happens if I misconfigure SSO and can’t log in?

  • If you are unable to log in due to SSO misconfiguration, please reach out to Incode Support for assistance. They can help you regain access to your dashboard.

Q2. Can I set up a special user account that bypasses SSO?

  • Incode Workforce does not currently support special users who can bypass SSO. If you need such functionality, please contact Incode Support to explore alternative solutions.

Q3. Are users automatically added to Incode Workforce when they log in via SSO?

  • No, users are not auto-provisioned or added to the Incode Workforce user list through SSO. If maintaining a user list in the Workforce Dashboard is important for your workflow, you must manually add users in the Admin User Management tab.

Q4. What happens to the previous authentication configuration when switching between username/password and SSO?

  • Switching authentication methods (e.g., from username/password to SSO) will delete the previous configuration. Ensure your new configuration is fully tested and validated before making the switch.

Q5. What happens to users previously added when username/password authentication was used after switching to SSO?

  • When SSO is configured, users who were manually added in the Workforce Dashboard under the username/password method will no longer have access. Users are no longer managed directly in Incode Workforce but are instead managed entirely via Okta groups. Ensure that all necessary users are assigned to the appropriate groups in Okta with proper role mappings to maintain their access.

Q6. If I manually add a user but their role is not mapped in Okta, will they get access?

  • No, even if a user is manually added to the Workforce Dashboard, they must belong to a group in Okta that is mapped to a Workforce role (e.g., Admin or Helpdesk). Without a proper group-role mapping, the user will not be able to access the dashboard.

Q7. What happens if a user is not assigned to a group required for accessing the application during SSO setup?

  • If a user is not assigned to the appropriate group in your Okta, they will not be granted access to the application. During the SSO login process, the user's group membership is typically checked against the application's access requirements in OKTA and groups defined in Incode Workforce Dashboard. Review selected groups in both OKTA application setup and Incode Dashboard and make

Standard OIDC SSO errors

In case of any configuration or access errors, in the url there will be and error code. Common codes are listed below.

Authentication Errors

  1. invalid_request

    • The request is missing a required parameter, contains an unsupported parameter, repeats a parameter, or is otherwise malformed. Please review your OKTA application configuration and Incode Workforce setup.

  2. unauthorized_client

    • The client is not authorized to request an authorization code or token. Please review your OKTA application configuration and Incode Workforce setup.

  3. access_denied

    • The user denied the request, or the resource server is rejecting the access. User might not be in the group that is assigned to application.

  4. unsupported_response_type

    • The authorization server does not support obtaining an authorization code using this response type. Review your OKTA application configuration.

  5. invalid_scope

    • The requested scope is invalid, unknown, or malformed. Review your OKTA application configuration.

  6. server_error

    • The authorization server encountered an unexpected condition that prevented it from fulfilling the request. If the error persist contact Incode support.

  7. temporarily_unavailable

    • The authorization server is temporarily unavailable due to maintenance or overloading. If the error persist contact Incode support.

Token Errors

  1. invalid_grant

    • The token request is invalid or has expired. User should try authenticating again.

  2. invalid_client

    • The client authentication failed. Please verify your client credentials in Incode Workforce App and in OKTA application.

  3. invalid_token

    • The access token is invalid, expired, or revoked. User should try authenticating again.

  4. insufficient_scope

    • The access token does not have the necessary permissions for the requested resource.

Redirect URI Errors

  1. redirect_uri_mismatch
    • The redirect URI in the request does not match any of the registered URIs. Please review your OKTA application settings.

User Assignment/Access Errors

  1. account_selection_required

    • The user needs to select an account, but none was chosen or available.

  2. interaction_required

    • Interaction (e.g., consent or login) is required to complete the request.

  3. login_required

    • The user is not logged in or their session has expired. They would need to authenticate again

  4. consent_required

    • The user must provide consent for the application to access their data.

Updated 4 months ago