OpenID Connect (OIDC)

CirrusPrint can be configured to use an OIDC service in place of its normal login for the admin browser interface.  It supports the "Authorization Code Flow" provided by third-party providers such as Okta and Auth0, delegating the authentication of CirrusPrint site users to the third party.

Configuration

Configuration of an OIDC integration requires three items that are maintained via a cp30c command line:

•Provider, a URL from which CirrusPrint can obtain references to provider endpoints using the /.well-known/openid-configuration path

•Client ID, part of an application registered at the provider

•Client Secret, part of the application and used as a password

These entries are provided to CirrusPrint using the command line API, since they affect the operation of the internal HTTP server itself and cannot be edited within the browser as it is accessing the HTTP server.  These values are stored in encrypted form in the installation's data path, so are centrally configured in high availability sites.

These commands require admin/super user permission.  To update these values:

cp30s -put oidc -provider "url" -clientid "client-id" -clientsecret "client-secret"

Any option provided (provider, client id, client secret) will update the configuration and cause the service to reload it.  Missing options are not affected.  To turn off the OpenID Connect integration, use -provider "" to set the provider to no value, and revert authentication to standard CirrusPrint login screens.  This can be helpful during testing, or if the provider becomes unavailable.

The url of the provider is the domain hosted by provider for your account with them.  CirrusPrint will prefix this value with "https://" if needed.  Under that domain, CirrusPrint must find a /.well-known/openid-configuration" page to be considered valid.

The client-id and client-secret values are generated by the provider when  you configure a web application for CirrusPrint to connect to.

To view these values:

cp30s -get oidc -pretty

The configuration is provided as a JSON value.  If -pretty is included, the JSON structure is formatted to be more human-readable.

Usage

When configured, logins to the CirrusPrint administration browser interface require authentication of a user by the OIDC provider.  The provider directs the user's browser to provide CirrusPrint with a code that is exchanged for a signed token.  This token is validated, then used to identify the CirrusPrint site user, which grants the user full administrative permission or company-specific permission.  Note this means a user must be defined in both the OIDC provider's user database and in CirrusPrint.  If this user population if hard to maintain, using APIs can help automate this process.

CirrusPrint users have an OIDC User ID field that can be maintained manually or by API.  This value provides a link to the standard OIDC subject value.  When a login is complete and directed back to CirrusPrint, the data that is provided includes a subject value.  If a CirrusPrint user is found with an OIDC User ID that matches that value, that is the user assigned to the session.  If no match is found, a second attempt to match is performed, using the Email claim from the provider (if present) and the user's primary email address.  If no match is found using either method, a message is displayed and the user is returned to the provider login screen.  It is critical that the provider's user database is in sync with the CirrusPrint site user list using OIDC User ID or email values.

Details and comments:

•Session length of OIDC sessions are determined by the provider rather than the session duration parameter in CirrusPrint

•MFA settings for CirrusPrint users are ignored when OIDC is enabled, as it is assumed that the provider will perform all authentication

•It is recommended to maintain strong passwords and MFA in the CirrusPrint user population in case it is necessary to turn off OIDC at any point