Skip to content

Configure the OIDC Identity Provider

SEAL Operator authenticates a user via the OAuth 2.0 and the OpenID Connect protocol. For this, an OIDC identity provider is required.

A preconfigured Keycloak identity provider is provided by SEAL Systems for test purposes. In practice, another OIDC identity provider already installed at the customer's is used for the user authentication and authorization.

Literature - OIDC identity provider

For more information about Keycloak and other OIDC identity providers used with the SEAL Systems products, refer to the SEAL Interfaces for OIDC documentation.

Using Keycloak

If you use the SEAL-specific Keycloak as OIDC identity provider, configure SEAL Operator as follows:

  1. Export the complete configuration of SEAL Operator from Consul to a YAML file. This ensures that you edit the current configuration.

    operator config export <filename>.yml --insecure

  2. Edit the exported file <filename>.yml.

  3. Go to the section for all SEAL Operator services. Change the value for AUTH_ISSUER_URL and ID_PROVIDER_NAME to the server name <id_provider_server> of the OIDC identity provider. Use the fully-qualified domain name (FQDN) of the OIDC identity provider server.

    env:
  service:
    any:
      tag:
        any:
          AUTH_ISSUER_URL: https://<id_provider_server>:32769/realms/SEAL
          BROKER_REJECT_UNAUTHORIZED: N
          BROKER_SERVERS: localhost:4222
          CONSUL_TOKEN: INSECURE_ACL_MASTER_TOKEN
          CONSUL_URL: https://localhost:8500
          ID_PROVIDER_NAME: https://<id_provider_server>:32769/realms/SEAL
          JWT_USERNAME: preferred_username

    Hint - changed URLs as of Keycloak 21.0.1

    As of SEAL-specific Keycloak version 21.0.1, the URLs needed for AUTH_ISSUER_URL and ID_PROVIDER_NAME have changed. For the old and new values, refer to the key descriptions.

  4. Save the <filename>.yml file.

  5. Re-import the file to Consul.

    operator config import <filename>.yml --insecure

  6. Check the imported value, for example for AUTH_ISSUER_URL:

    operator config get AUTH_ISSUER_URL --insecure

Using ADFS

For the prerequisites and the configuration on ADFS side, refer to the SEAL Interfaces for OIDC documentation.

On ADFS side, two server applications with Web API have to be configured, one for the Client Credential Flow between the services and one for the Code Flow used for the interactive logon. Each server application has an ID and a secret which have to be configured with SEAL Operator.

To use ADFS as OIDC Identity Provider, execute the following steps in SEAL Operator:

  1. Open a command prompt. On Windows, do not open it as administrator.

  2. Export the complete configuration of SEAL Operator from Consul to a YAML file. This ensures that you edit the current configuration.

    operator config export <filename>.yml --insecure

  3. Edit the exported file <filename>.yml.

  4. In the env section, specify the following keys for all services:

    • AUTH_CLIENT_SECRET: mandatory, secret generated when configuring the first server application in ADFS

    • AUTH_CLIENT_ID: mandatory, ID generated when configuring the first server application in ADFS

    • AUTH_TOKEN_ENDPOINT: URL of the token endpoint of the ADFS

    • AUTH_ISSUER_URL: mandatory, URL the services use for connecting to the ADFS provider

    • ID_PROVIDER_NAME: mandatory, name of the ADFS; hint: Even if configured to use the HTTPS protocol, the URL provided here comes without HTTPS protocol and uses HTTP protocol as URI!

    • ID_PROVIDER_CERT: optional, absolute path and file name of the certificate file exported from ADFS

    • TRUSTED_CLIENT: mandatory, client name configured in ADFS for granting access via access token. The information is contained in the token. This URI is used to check the token from the ADFS. It is a combination of two parts microsoft:identityserver:<client_identifier>.

      env:
    service:
      any:
        tag:
          any:
            ...
            AUTH_CLIENT_SECRET: <client_secret_1>
            AUTH_CLIENT_ID: <client_id_1>
            AUTH_TOKEN_ENDPOINT: https://<adfs_host>/adfs/oauth2/token
            AUTH_ISSUER_URL: https://<adfs_host>/adfs/
            ID_PROVIDER_NAME: http://<adfs_host>/adfs/services/trust
            ID_PROVIDER_CERT: <cert_dir>/export_token_signing.cer
            TRUSTED_CLIENT: microsoft:identityserver:<client_id_1>
            ...

  5. In the env section, specify the following keys for the seal-operator-ui service in the operator-ui section:

    • AUTH_CLIENT_SECRET: mandatory, secret generated when configuring the second server application in ADFS

    • AUTH_CLIENT_ID: mandatory, ID generated when configuring the second server application in ADFS

      env:
    service:
      ...
      operator-ui:
        tag:
          any:
            ...
            AUTH_CLIENT_SECRET: <client_secret_2>
            AUTH_CLIENT_ID: <client_id_2>
            ...

  6. Save the <filename>.yml file.

  7. Re-import the file to Consul.

    operator config import <filename>.yml --insecure

  8. Check the imported value, for example for AUTH_ISSUER_URL:

    operator config get AUTH_ISSUER_URL --insecure

Hint - content of a token

By means of https://jwt.io/, you can decode the token and see its content.

Using Another OIDC Identity Provider

If you use another OIDC identity provider, configure SEAL Operator as follows:

  1. Export the complete configuration of SEAL Operator from Consul to a YAML file. This ensures that you edit the current configuration.

    operator config export <filename>.yml --insecure

  2. Edit the exported file <filename>.yml.

  3. In the section for all SEAL Operator services, configure the following keys for the certificate and the client credentials grant:

    env:
  service:
    any:
      tag:
        any:
          AUTH_CLIENT_ID: <client_id_used_in_idp>
          AUTH_CLIENT_SECRET: <client_secret_generated_by_idp>
          AUTH_ISSUER_URL: <idp_url>
          AUTH_TOKEN_ENDPOINT: <token_endpoint_url_of_idp>
          ID_PROVIDER_CERT: <path_and_filename_of_idp_certificate>
          ID_PROVIDER_NAME: <iss_property_in_idp>
          ...

  4. In the operator-ui section for the seal-operator-ui service, configure the following key for the authorization code grant:

    • AUTH_CLIENT_ID: mandatory if the client name differs from seal-print-client, client name configured in the OIDC identity provider
    env:
  service:
    ...
    operator-ui:
      tag:
        any:
          AUTH_CLIENT_ID: <client_id_used_in_idp>
        ...

  5. Save the <filename>.yml file.

  6. Re-import the file to Consul.

    operator config import <filename>.yml --insecure

  7. Check the imported value, for example for AUTH_ISSUER_URL:

    operator config get AUTH_ISSUER_URL --insecure

  8. If you use SEAL OP-CLI with this OIDC identity provider, specify its client credentials and issuer URL on the computer running SEAL OP-CLI. For details, refer to Configure OIDC on Linux or Windows in the SEAL OP-CLI documentation.

Literature - keys

For further information about the keys, refer to the Key Reference.

Proxy Settings

If your OIDC identity provider is behind a proxy, specify the following key:

  • AUTH_PROXY: optional, proxy URL to access the OIDC provider

Configure Roles (Optional)

In the OIDC identity provider, roles are configured to which the users are assigned. In the configuration of the seal-operator-server and seal-operator-fileupload services, the permissions for the database entities are mapped to these roles. The specific permissions depend on the OIDC client.

The following OIDC clients are available in connection with SEAL Operator:

  • seal-print-client for SEAL Print Client

  • seal-opcli for SEAL OP-CLI

  • seal-webportal for SEAL Web Portal

For example, in the preconfigured Keycloak from SEAL Systems, seal-print-client-user, techuser and service-account are available as roles.

The mapping of the permissions and the roles is specified as JSON object with the following key:

  • ALLOWED_OIDC_CLIENTS: mandatory, mapping of permissions to roles specified in the OIDC identity provider

Hint - maintainability

Although the key is available for several services and can be added for each of them, it is advised to consolidate all permissions in one entry at dc/home/env/service/any/tag/any/ALLOWED_OIDC_CLIENTS.

Hint - usage of Consul

Due to the possible complexity of the JSON string for ALLOWED_OIDC_CLIENTS it is advised to add or change its value via Consul (https://localhost:8500), which has an inbuilt JSON format validation. In Consul, the key is specified here: dc/home/env/service/any/tag/any/ALLOWED_OIDC_CLIENTS.

Hint - template for ALLOWED_OIDC_CLIENTS

SEAL Operator CLI has functionality to generate a template for this key.

operator config template ALLOWED_OIDC_CLIENTS --file template.json

The template does not take the current value of this key into account. For further information, refer to Administrate Configuration.

Available Keys and Values

This section explains the available keys and values of the json object for ALLOWED_OIDC_CLIENTS.

{
  "<oidc-client>": {
    "roles": {
      "<role-specified-in-oidc>": {
        "areas": {
          "documents": {
            "set-<name>": {
              "views": [<selection of items>],
              "permissions": [<permissions>]
            }
          },
          "tasks": {
            "set-<name>": {
              "views": [<selection of items>],
              "permissions": [<permissions>]
            }
          },
          ...
        }
      }
    }
  }
}

  • <oidc-client>: On the top level of the JSON object, you specify the OIDC client as specified in your OIDC. Available values: seal-print-client, seal-opcli and seal-webportal.

    Hint - client names in the OIDC identity provider

    It is advised to use these exact client names in your OIDC. If that is not possible you have to specify the client name in AUTH_CLIENT_ID for the respective service.

  • <role-specified-in-oidc>: Within roles, you specify the names of the roles specified in the OIDC identity provider. Available values in the preconfigured Keycloak from SEAL Systems are: seal-print-client-user, techuser and service-account.

  • areas: Available values: documents, lists, panels, shares, tasks

  • set-<name>: Freely choosable name for readability purposes only.

  • <selection of items>: Within views, you specify the selection of items to which the permissions specified apply. Available values: ["ALL"] stands for all items, [] stands for none of them. You can also limit the selection by combining the struct, value, and operator keys. Available operators are eq for an exact matching between value and struct, and wildcard for a wildcard matching between value and struct. For this, value may contain *.

  • <permissions>: Available values: impersonate

Examples

Example - configuration to enable the creation of documents, tasks, panels and Web Portal shares by a technical user on behalf of a real user

A typical use case is a PLOSSYS 4 Web Portal printer.

{
  "seal-print-client": {
    "roles": {
      "seal-print-client-user": {},
      "techuser": {
        "areas": {
          "documents": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "tasks": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "panels": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          }
        }
      }
    }
  },
  "seal-opcli": {
    "roles": {
      "seal-print-client-user": {},
      "techuser": {
        "areas": {
          "documents": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "tasks": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "panels": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "shares": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          }
        }
      }
    }
  },
  "seal-webportal": {
    "roles": {
      "service-account": {}
    }
  }
}

Example - techuser role with right for impersonation on documents, lists, tasks, and panels

{
  "seal-print-client": {
    "roles": {
      "seal-print-client-user": {},
      "techuser": {
        "areas": {
          "documents": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "lists": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "tasks": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          },
          "panels": {
            "set-impersonate": {
              "views": ["ALL"],
              "permissions": ["impersonate"]
            }
          }
        }
      }
    }
  }
}

Next Step

Continue with: Configure the Fileupload Connector

Back to top