Okta

An Identity Provider (IdP) vouches for the identity of a person through the use of an authentication token. Virtual Appliance uses IdP for several things, including logging in to the Admin Console and portals, deploying printers, releasing print jobs, and more.

If you use an IdP, the Control Panel Application (CPA) only supports badge and PIN authentication.

These steps follow Okta's classic user interface rather than the Developer Console user interface.

SCIM Requirements

  • Virtual Appliance must be accessible to the web over port 443.
  • A Public CA is required.
  • Public DNS resolution for the Virtual Appliance.

JIT (Just In Time) Provisioning does not require the Virtual Appliance to be accessible via 443, a Public CA, or Public DNS resolution.

Configure Connection

To add and configure enterprise app properties for the Virtual Appliance connection do the following:

  1. Create Okta App.
  2. Add IdP Template.
  3. Configure Single Sign On.
  4. Add the X-509 Certificate.
  5. Complete IdP Settings.
  6. Configure Provisioning.
  7. Add Virtual Appliance Admins.

1. Create Okta App

  1. Log into your Okta Admin Portal.

  2. In the left-side menu, expand Applications and select the Applications option.

    Okta Applications menu expanded to show the sub-option for Applications.

  3. Select Create App Integration.

  4. Select the SAML 2.0 option, then select Next.

    Create a new app integration window showing three options and the middle SAML 2.0 option selected.

  5. Add a name in the App Name field, a logo if desired, then select Next.

Create SAML Integration window showing the App Name and Logo fields highlighted, and the blue Next button is visible in the lower right corner.

Leave the current browser open to the new app page. To continue the app configuration, you need to open another browser and open the and access the service provider information.

If the IdP Settings page does not look like the image shown below, you may not be using the latest version and should contact Product Support to upgrade your IdP settings.

2. Add IdP Template

  1. In a separate browser tab, open your Virtual Appliance Admin Console and sign in.
  2. Select Tools then Settings then General, and scroll down to the Identity Provider Settings section.
  3. Select IdP, and then select Add.
  4. Select the identity provider you want to configure in the IdP Template drop-down.
  5. Select SAML2 in the Authentication Protocol section.

  6. For Provisioning it is assumed that JIT will be used for most Virtual Appliance applications. Check the box for JIT provisioning.

    When you consider how to set up your IdP configuration be aware that SCIM provisioning requires an open connection from the IdP provider into the Virtual Appliance instance gateway container. We recommend JIT provisioning when setting up your IdP connection.

  7. In the Name field, enter the name you want displayed on the login button for users, e.g. My Company, Login, Acme Corp, etc.
  8. Scroll down and select the desired enable setting(s).
    • Enable for End Users Login — Allows end users to login using this IdP. (Self-service Portal)
    • Enable for Admin Login — Allows Admin users to login using this IdP. (Admin Console)
    • Both boxes can be checked when using a single IdP, or if the admin and end users use the same IdP to log in.

Keep the IdP Settings screen open so that the Service Provider Information at the bottom is available for the following steps.

IdP Settings window showing the different fields and the Service provider information section.

3. Configure Single Sign On

  1. In the Virtual Appliance Admin Console IdP Settings Service Provider Information section, copy the Identifier (Entity Id) and paste it into the Okta SP Entity ID field.
  2. Copy the Admin Console Reply Url (ACS) and paste it into the Okta Single Sign on URL field.
  3. Copy the Admin Console Relay State URL and paste it into the Okta Default Relay State field.
  4. In Okta, scroll down to the Attributes Statements section and enter the following:
    1. Name: FirstName, Name format: Unspecified, Value: user.firstName.
    2. Name: LastName, Name format: Unspecified, Value: user.lastName.
    3. Name: Email, Name format: Unspecified, Value: user.email.
    4. Name: Login, Name format: Unspecified, Value: user.login.
  5. Scroll to the bottom of the screen and select Next.
  6. Check the boxes for I'm an Okta customer adding an internal app and This is an internal app that we have created.
  7. Select Finish.

  8. Select View SAML Setup Instructions. A new window displays with the information to copy and paste into the Admin Console.

    Sign On tab showing the View SAML setup instructions button on the right.

  9. Copy the Okta Identity Provider Single Sign-On URL and paste it into the Admin Console SSO URL field.

    SAML Setup instructions window showing the Identity Provider Single Sign-on URL field highlighted at the top.

  10. Press Tab to auto-populate the Issuer URL and Issuer ID fields.

Attribute Statements window showing the listed attributes that have been added.

4. Add the X-509 Certificate

  1. Return to Okta's View Setup Instructions window and copy the main body of the X-509 Certificate in PEM Text Format.

  2. Paste it into the Admin Console X-509 Certificate field.

    How to configure SAML window showing the X-509 certificate highlighted in the middle.

  3. Select Apply.

  4. Select Save

    The Admin Group Name field will be left blank unless you are using an Attribute Statement for additional security. Steps to configure that are found in Additional Admin Console Security , and can be setup after the initial IdP configuration.

IdP Settings template showing the X509 cert and other fields configured.

5. Complete IdP Settings

  1. On the Admin Console General page, navigate back to the Identity Provider Settings section.

  2. To have Virtual Appliance prompt your users to authenticate through the IdP when performing any function requiring authorization, such as installing a printer, select the Automatically Open Browser to Login on Desktop Client option.

    If this option is not selected, the user must manually navigate to the IdP login screen to sign in.

  3. We recommend enabling the Use Loopback with SAML2 option. The IdP needs to provide an authentication token to the desktop clients whenever authentication happens. This option allows the client to handle the token and automatically log in without interaction from end users.

    General tab's Identity Provider Settings section with the IdP option selected and two additonal options selected below the IdP.

  4. The option to Use Domain User (Windows only) will automatically authorize domain-joined Windows users and not require login via the configured IdPs.
  5. Select Save in the top-right corner of the General page.

6. Configure Provisioning

The provisioning steps vary depending on whether you are using SCIM or JIT provisioning. Please choose the appropriate option below to view the corresponding steps for the method you are using.

SCIM Provisioning

Enable SCIM Provisioning

  1. In the Okta left-side menu, expand Applications and select the Applications option.

    Okta Applications menu expanded to show the sub-option for Applications.

  2. Select Browse App Catalog button.
  3. In the Search field, search for and select SCIM 2.0 Test App (OAuth Bearer Token).
  4. Select the Add button.
  5. Give your application a name, then select Done.
  6. Select the app's Provisioning tab, then select Configure API Integration.
  7. Select Enable API Integration and leave the screen open for use in the next step.

App's Provisioning tab with the tab name highlighted and the Configure API Integration button in the lower middle.

Generate / Apply SCIM Token

  1. In the Virtual ApplianceGeneral settings, select the SCIM option in the Identity Provider Settings section.
  2. Select your IdP configuration in the drop-down menu.

  3. Select Generate SCIM Token.

    SCIM section showing the IdP selected in the drop-down, and the Generate SCIM Token button to the right.

    Generating a SCIM token invalidates any previous tokens for that IdP.

  4. Select Proceed.
  5. Copy the token, close the modal, and select Save at the top-right corner of General settings.
  6. Paste the token into the Okta app's OAuth Bearer Token field.
  7. In the Admin Console Identity Provider Setting section, select IdP, then select your IdP and select Modify.
  8. Copy the SCIM Tenant URL and paste it into Okta's SCIM 2.0 Base Url field.
  9. Select Test API Credentials. A notification displays if the token was verified successfully.
  10. Select Save

App's Provisioning tab showing the SCIM 2.0 Base URL field highlighted and the value pasted in, and the Test API Credentials button is visible below the fields.

Enable the To App Settings

  1. Select To App in the left-side Settings menu.
  2. Select the Edit link to the right.
  3. Check the Enable box for the following.
    1. Create Users.
    2. Update Users.
    3. Deactivate Users.
  4. Select Save in the lower-right.

Provisioning To App tab withthe enable checkboxes for Create Users, Update User Attributes, Deactivate Users, and the Save button is visible in the bottom right corner.

Assign Users / Groups

Please note that Okta does not support assigning the same groups on the Assignments and Push Groups tabs. For example, if you assign "Group A" on the Assignments tab you should not assign "Group A" on the Push Group tab.

The recommended best practice is to create an Okta group that includes all users who will need access to the Virtual Appliance application, which should consist of admin users who require access to the Virtual Appliance Admin Console as well as end users who only need access to the Self-service Portal. Assign this group on the "Assignments" tab in Okta, which will provision all the necessary user records into the instance without any group membership data. You can then assign your role-specific groups (Admin, Help Desk, etc.) on the "Push Group" tab, which will provision the group membership data needed for RBAC, Portal Security, and Deployment rules.

For reference, see the official Okta documentation on the Push Group tab.

Assignments Tab: Assign Users / Groups

  1. Select the Okta app's Assignments tab.

  2. Select the Assign drop-down.

    App's Assignments tab the left-side Assign menu expanded to show the two sub-options for Assign to People and Assign to Groups.

  3. To grant access for individual users, select Assign to People. To grant access for groups select Assign to Groups.
  4. Search for the desired users / groups and select Assign.
  5. Select Done.
  6. Repeat these steps for any additional users / groups.

Assign app to people/groups pop-up showing a search field and results for the PrinterLogic Admin Portal group, the Assign button to the right of the group, and the Done button in the bottom right.

Push Groups Tab: Assign Groups

If you need to provision group membership information into Virtual Appliance.

  1. Select the Okta app's Push Groups tab.
  2. Select + Push Group.

  3. Select Find groups by name.

    Push Groups tab with the Push Groups button expanded to show the sub-options.

  4. Search for and select the desired group(s).

    Ensure that the groups selected on this tab are NOT the same group/s assigned on the "Assignments" tab.

  5. Under the Match result & push action section verify that + Create Group is selected.

    Push Groups tab showing the selected group and the Create Group option on the right.

  6. Select Save.
  7. Under Push Status, verify that the status changes from Pushing to Active.
  8. Exit Okta.

Push Groups tab showing the pushed groups with the Push Status column value of Active on the far right of the group.

JIT Provisioning

Assign Users

NOTE: When using JIT, the provisioning of group membership associations is not supported. This means you will not be able to configure RBAC roles, printer deployments or portal security roles to groups in Virtual Appliance. All assignments will have to be done to users individually.

  1. Select the Assignments tab.

  2. Select the Assign drop-down.

    App's Assignments tab the left-side Assign menu expanded to show the two sub-options for Assign to People and Assign to Groups.

  3. Select Assign to People to assign individual users.
  4. Search for the desired users the select Assign.
  5. Select Done.
  6. Repeat these steps for any additional users / groups.
  7. Exit Okta.

Assign app to people window showing the Assign and Done buttons.

User Creation

If you wish to use JIT Provisioning, make sure the JIT option in the IdP Settings modal is checked and do not enable SCIM. Doing so will create duplicate users and impact login and user authentication.

JIT does not support the provisioning of group membership associations, so you cannot apply RBAC roles, printer deployments or portal security roles to groups. All assignments have to be done individually for each user.

When using JIT Provisioning, the application creates users during the first sign-in attempt.

  1. Access your Virtual Appliance instance and select Sign in with <IdP Name>.
  2. Attempt to login with your IdP credentials.

  3. This login attempt will fail and return you to the login page.

    This is expected. With JIT, this action triggers the user creation in the instance.

  4. The following login attempt with valid credentials initiates a typical login sequence.

Administrators who need access to the Admin Console still need to be added to the Tools then Users page using the steps in Admin Console Users.

7. Add Virtual Appliance Admins

For steps on assigning users and roles to the Virtual Appliance Admin Console reference Admin Console Users.