About

When OpenID Connect (OIDC) integration is enabled, user authentication requests to the Management Interface or end user interface are redirected to an external Identity Provider server URL. After a user authenticates at the external Identity Provider, they are redirected back to the application for the authentication session to be verified.

OIDC is a standard protocol for web browser Single Sign-On (SSO) using secure tokens. OIDC eliminates all local application passwords and instead uses standard cryptography and digital signatures to pass a secure sign-in token from an identity provider to a SaaS application.

See OpenID Connect documentation for more information about its principles.

Currently supported identity providers:

• Keycloak
• Microsoft Azure

OIDC with user import versus OIDC without user import

When configuring the OIDC integration, you will have a choice between two modes of user management:

• OIDC with user import
• OIDC without user import

See the User import setting section of this document for details of where this setting (openIdConnectImportUsers) is located. Each of these two modes is targeted at a different use case.

Be aware that in both modes, the usernames in Dispatcher Paragon must be in the UPN format (in most cases this would be the user's email address).In the case of OIDC with user import, the consequence of this is that users can print only via Dispatcher Paragon Mobile Integration Gateway.In the case of OIDC without user import, your print queues may not need any changes if you set the user aliases correctly because aliases will solve user matching to SAMAccountName (or another attribute you are using).

OIDC without user import (internal users, LDAP users)

This mode is intended for Dispatcher Paragon on-premise customers who:

• are only looking for Single Sign-On functionality.
• already have a way of replicating/managing their users, such as LDAP replication, CSV import, or one of our customizations (SWC-100 being the most common). 

OIDC in this mode is comparable to other Single Sign-On possibilities in Dispatcher Paragon, such as SAML or Windows Integrated Login.

This mode, unlike the second one below, has only minor limitations. You can keep the way your Dispatcher Paragon is set up, all of your Dispatcher Paragon components (FlexiSpooler, End User Interface, and others), and even keep using passwords if you wish (for example, to log in to MFDs).

The added benefit is that login to the Management interface is:

• Simpler – users don't have to enter their username and password when they are already logged at your external Identity Provider.
• More secure – the external Identity Provider may employ Multi-Factor Authentication, password policies, etc.

In this mode, user accounts have the following characteristics:

• Users remain managed by Dispatcher Paragon Management Server. Users of the management interface can use OIDC as a way of logging in without a Dispatcher Paragon password, but their profiles are not updated from the external IdP.
• New users are not imported from the external IdP automatically – the administrator must first create their user accounts in the Management interface and then they can start logging in via OIDC.
• The user accounts remain editable in the Management interface even after OIDC login.
• This mode is fully compatible with LDAP replication.

OIDC with user import (OIDC, OAuth)

This mode is primarily used in Konica Minolta's cloud products and is not recommended for on-premise deployments.However, you may find it useful if you host your Dispatcher Paragon in a public cloud yourself (for example, in Microsoft Azure).

The benefits of integrated login:

• Simpler – users don't have to enter their username and password when they are already logged at your external Identity Provider.
• More secure – the Identity Provider may employ Multi-Factor Authentication, password policies, etc. In addition, passwords are not stored anywhere in Dispatcher Paragon.
• Users only need to be managed in one place – your external Identity Provider. Changes are replicated to Dispatcher Paragon at every login.

In this mode, user accounts have the following characteristics:

• Users are fully managed by the external IdP. When a newly created user logs in to the Management interface for the first time, their profile is automatically created in the Management database using the information supplied by the external IdP. Likewise, a returning user's profile is updated from the external IdP every time they log in.
• OIDC users cannot be edited from the Management interface, because any changes would be overwritten on the next login.
• You may still create internal users (i.e. manually created users, or imported from CSV or from LDAP), and they can use the system and coexist with users imported via OIDC, but the first time the internal users use OpenID Connect to log in, their profile converts to being managed from external IdP via OIDC.

Reference:

• https://openid.net/connect/faq/
• https://docs.microsoft.com/en-us/azure/active-directory/
• https://www.keycloak.org

Setting up the OIDC integration

To enable the integration, you must:

• Configure the OIDC client in your external Identity Provider.
• Configure the Management Service / end user interface to act as the client.
• The secured communication for all communication lines is strongly recommended, see Setting secured communication with Spooler Controller and Configuring SSL/TLS for Dispatcher Paragon Management Service.

Configuring your external Identity provider

You can use Keycloak or Microsoft Azure as your external Identity providers. Keycloak is necessary only if you need to use more than one Identity Provider.

Configuring OIDC integration with Microsoft Azure AD

1. Log in to Microsoft Azure portal.
2. In Azure Active Directory, click App registrations > New registration.
   
   
   
3. Choose the account type which suits your deployment the most. Note that you can leave the redirect URI empty and fill it in later.
   
   
   
4. Click Register.

5. On the Authentication tab, click Add platform > Web and fill in redirect URLs, e.g. https://management.company.net/login/oauth2/code/oidc.
   
   
   

   OIDC with Client v3

   Environments using Client v3 need additional redirect URLs, one for each Job Service. Each one will be the URL of a given Job Service followed by /signin-oidc, e.g. https://job-service.example.com:5000/signin-oidc.

6. On the Certificates & secrets tab create a client secret and note it down. After you leave this page, you can no longer access the secret.
   
   
   
7. After the configuration, check whether the endpoint https://login.microsoftonline.com/<directory-tenant-id>/v2.0/.well-known/openid-configuration works in your web browser and shows content with the configuration of other endpoints. (The directory tenant identifier could be found on the Overview tab as Directory (tenant) ID)

Configuring OIDC integration with Keycloak

For Keycloak, configure the OIDC client according to Keycloak documentation.

1. Make sure that the client Access Type is confidential and the secrets are filled in on the Credentials tab.
2. Make sure that Valid Redirect URIs contains the URL of the management interface, end user interface & Client v3:
   1. Management Interface
      1. For login add https://<MANAGEMENT HOST>/login/oauth2/code/oidc (e.g. https://management.company.net/login/oauth2/code/oidc)
      2. For logout add https://<MANAGEMENT HOST>/login/<tenant domain>?logout (e.g. https://management.company.net/login/tenant_1?logout)
   2. For end user UI 
      1. For login add https://<SPOC HOST>:9443/end-user/ui/login/oauth2/code/oidc (e.g. https://spoc.company.net:9443/end-user/ui/login/oauth2/code/oidc)
      2. For logout add https://<SPOC HOST>:9443/end-user/ui/login (e.g. https://spoc.company.net:9443/end-user/ui/login)
   3. For each Job Service
      1. For login add <URL of Job Service>/signin-oidc
      2. Logout is not yet supported.
         
         
         
3. After the configuration, check whether the endpoint https://<keycloak-url>/auth/realms/<realm-name>/.well-known/openid-configuration works in your web browser and shows content with the configuration of other endpoints.

Configuring Dispatcher Paragon Management Interface

1. Make sure that the Identity provider certificate authority is included in Management Service trusted authorities.
2. Log in to the management interface.
3. Go to System and configure these options:
   • webAuthenticationMethod – set to value OpenID Connect to enable the feature.
   • openIdConnectClientId – enter the client ID obtained during client registration at your external Identity Provider.
   • openIdConnectClientSecret – enter the client secret value obtained during client registration at your external Identity Provider.

   • jobServiceOpenIdConnectClientSecret – enter the client secret obtained during client registration at your external Identity Provider. This secret is used by Client v3 users to log in. The value can be the same as or different from the openIdConnectClientSecret property.
     

     Optional: Configure this option if the OIDC login for Client v3 is being configured and used.

     Warning

     For increased security, create a second client secret, different from openIdConnectClientSecret.

   • openIdConnectAdditionalScopes – the Management Service automatically determines the necessary client scopes ("openid", "profile", "email" and "offline_access") but you can add extra scopes. The value of this configuration property should be a comma-separated list of additional scopes.
   • openIdConnectIssuerLocation – enter the URL of the OpenID provider issuer that will be used for obtaining OpenID provider configuration information. The issuer address should not contain "/.well-known" part as this is added automatically. For example openIdConnectIssuerLocation with value "https://sso.company.net/auth/realms/realmName" will be resolved to "https://sso.company.net/auth/realms/realmName/.well-known/openid-configuration".
     • For Keycloak, use this pattern: https://<keycloak-url>/auth/realms/<realm-name>

     • For Microsoft: https://login.microsoftonline.com/<directory-tenant-id>/v2.0
       

       If you wish to allow users from multiple tenants, you can use "organizations" instead of tenant ID. See https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc#fetch-the-openid-connect-metadata-document for more details.

       
       

   • openIdConnectDirectlyRedirectToProviderLoginPage – When this option is enabled and an unauthenticated user visits a page that requires authentication, the Management interface login screen is omitted and the user is redirected directly to the authorization server login. The Management Service default login page on URL "/login" is still available.
   • openIdConnectTenantIdentificationClaim – Name of the claim that must be present in the access token to determine the tenant space user is authenticated to. Note that the value is ignored if the Management Service does not support multi-tenancy.
   • openIdConnectImportUsers – With this setting enabled, users are managed by the external IdP via OIDC (OIDC with user import mode). With this setting disabled (OIDC without user import mode) users remain internal (or imported from another source, such as CSV or LDAP, if your Dispatcher Paragon is set up in this way).
4. Restart necessary services.

Configuring Dispatcher Paragon End User Interface

1. Make sure that the Identity provider certificate authority is included in end user interface trusted authorities.
2. Log in to the Management interface.
3. Go to System and configure these options:
   • webAuthenticationMethodEUI – set to value OpenID Connect to enable the feature.
   • openIdConnectIssuerLocation – enter the URL of the OpenID provider issuer that will be used for obtaining OpenID provider configuration information. The value is shared with Management Interface, see the previous section for details.
   • euiOpenIdConnectClientId – enter the client ID obtained during client registration at your external Identity Provider.
   • euiOpenIdConnectClientSecret – enter the client secret obtained during client registration at your external Identity Provider.
   • euiOpenIdConnectAdditionalScopes – the end user interface automatically determines the necessary client scopes ("openid", "profile", and "email") but you can add extra scopes. The value of this configuration property should be a comma-separated list of additional scopes.
   • euiOpenIdConnectFailedLoginPromptHint – the value specifies the behavior of the Single Sign on login button after failed user login, typically when the user can't be verified by Dispatcher Paragon. When the user logs in via Identity provider, the session in Identity Provider is usually created so when the user clicks on Single Sign On button in end user interface again, the session on Identity Provider is reused and the user doesn't have to log in again. This behavior could be unwanted when the user wants to log in to Identity Provider as a different person. So the configuration option euiOpenIdConnectFailedLoginPromptHint alters behavior of login in Identity Provider. See the documentation of Identity Provider:
     • For Keycloak search for "prompt" values in Securing Apps documentation.
     • For Microsoft search for "prompt" values in Microsoft identity platform and OpenID Connect protocol documentation.
4. Restart necessary services.

Additional information

Revoking access to OneDrive for Dispatcher Paragon

For detailed instructions login to Azure Portal and go toAzure Active Directory > Enterprise applications > Cloud Print Management > Permissions > Review permissions > This application has more permissions than I want.

Creating client secret with a long expiration date

The option to create a client secret with no expiry date no longer exists in Azure Portal UI. However, client secrets with long expiration dates can be still created using Azure Command Line Interface (CLI). You can read more about Azure CLI in the official Microsoft documentation https://docs.microsoft.com/en-us/cli/azure/.

1. In the Overview of your application in the Azure Portal, note down your Application (client) ID. You will need the ID to set the expiration date of the token in the Azure CLI. After that, go to Manifest. 
   
   
   

2. Set the value of signInAudience to AzureADMyOrg and save the changes. Due to the limitation, existing credentials can be updated only for single-tenant applications. We recommend reverting SignInAudience to the original value after you update the expiration date of the token.

   For all the supported values of signInAudience see https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-app-manifest#signinaudience-attribute

   
   
   

3. Create a new client secret with a long expiration date or update the existing client secret.
   
   1. Creating a new client secret with a long expiration date 
      Existing client secrets will remain unmodified for the application. New client secret will be added to the list of existing client secrets.
      

      1. Sign in with Azure CLI. You can select a tenant to sign in under with the --tenant argument. The value of this argument can be either a domain or the Azure object ID for the tenant.

         az login --tenant <tenant>

      2. Create a new client secret with long expiration

         az ad app credential reset --id <Application (client) ID> --end-date 2299-12-31 --credential-description "<description max 15 characters>" --append

         Example: New client secret is available in the output. Note, that after you close the command prompt, you can no longer obtain the secret and you have to create a new one.

         az ad app credential reset --id f6ab219c-5655-4e02-ac75-73a61db02c6d --end-date 2299-12-31 --credential-description "App secret" --append

         
         
         

   2. Updating the existing client secret

      You can update the expiration date only for one existing Client secret. The rest of the Application client secrets will be completely removed.

      1. Prepare the Value of the client secret for which you want to update the expiration date. At the time of the creation of the secret, this value was visible on the Client secrets tab.
         
         
         

      2. Sign in with Azure CLI. You can select a tenant to sign in under with the --tenant argument. The value of this argument can be either a domain or the Azure object ID for the tenant.

         az login --tenant <tenant>

      3. Reset client secrets for the application

         az ad app credential reset --id <Application (client) ID> --password "<Client secret value>" --end-date 2299-12-31 --credential-description "<description max 15 characters>"

         Example:

         az ad app credential reset --id f6ab219c-5655-4e02-ac75-73a61db02c6d --password "Hn_7Q~39NtRCtcsUvFxfsuNqTB2-8IkOH-U~5" --end-date 2299-12-31 --credential-description "App secret"

         
         
         

4. Revert signInAudience to the original value in the Manifest file.

Troubleshooting

User cannot log in, error "Response: 401 Unauthorized" in logs

Behavior

The error on the Management interface side occurs after the user logs in to the OIDC authorization server. The Management Service logs contain an error message:

Cause and Solution

Management Service cannot obtain user access token because the Management Service OIDC client cannot authenticate to the authorization server. Check client secret registration on the side of your external IdP and use it in the configuration option openIdConnectClientSecret in the Management interface.

User cannot log in, error "The reply URL specified in the request does not match the reply URLs configured for the application"

Behavior

• The error occurs after the user logs in to the OIDC authorization server.
• Microsoft shows an error message "Sorry, but we're having trouble signing you in."
• The user is not redirected back to the Management interface.

Cause and Solution

You are accessing the Management interface using a different URL than the one registered in a redirect URI. For example, if you register https://management.company.net/login/oauth2/code/oidc, you must access the Management interface via https://management.company.net URL. This is because the same URL that you use to access the Management interface is provided in the request to the Identity Provider. A common source of this problem is using HTTP when HTTPS is registered.