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 will be 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

  1. Export the complete configuration of SEAL Operator from Consul to a YAML file. So you're making sure the current configuration settings are being used.

    operator config export <filename>.yml --insecure
    
  2. Edit the exported file <filename>.yml.

  3. In the section for all SEAL Operator services, change the value for ID_PROVIDER_NAME and AUTH_ISSUER_URL 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:
              ...
              ID_PROVIDER_NAME: https://<id_provider_server>:32769/realms/SEAL
              AUTH_ISSUER_URL: https://<id_provider_server>:32769/realms/SEAL
              ...
    

    Hint - changed URLs as of Keycloak 21.0.1

    As of SEAL-specific Keycloak version 21.0.1, the URL needed for AUTH_ISSUER_URL and ID_PROVIDER_NAME has changed.

    • old value: https://<hostname>:32769/auth/realms/SEAL

    • new value: https:/<hostname>:32769/realms/SEAL

  4. Save the <filename>.yml file.

  5. Re-import it to Consul.

    operator config import <filename>.yml --insecure
    

Using Another OIDC Identity Provider

  1. Export the complete configuration of SEAL Operator from Consul to a YAML file with the following command. So you're making sure that the current configuration settings are being used.

    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:
              ...
              ID_PROVIDER_NAME: <iss_property_in_idp>
              ID_PROVIDER_CERT: <path_and_filename_of_idp_certificate>
              AUTH_CLIENT_ID: <client_id_used_in_idp> (Default: operator)
              AUTH_CLIENT_SECRET: <client_secret_generated_by_idp>
              AUTH_TOKEN_ENDPOINT: <token_endpoint_url_of_idp>
              AUTH_ISSUER_URL: <idp_url>
              ...
    
  4. In the section for the operator-ui service, configure the following keys for the authorization code grant:

    env:
      service:
        ...
        operator-ui:
          tag:
            any:
            ...
              AUTH_CLIENT_ID: <client_id_used_in_idp> (Default: seal-print-client)
            ...
    
  5. Save the file <filename>.yml.

  6. Re-import it to Consul.

    operator config import <filename>.yml --insecure
    
  7. The following keys have to be set for calling SEAL Operator CLI unless the respective default applies:

Literature - keys

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


Configure Roles (Optional)

In the OIDC identity provider, roles are configured to which the users will be 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


In the OIDC identity provider, roles are configured to which the users will be assigned. 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:

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, 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

Please note, that the template doesn't 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

    It's adviced to use these exact client names in your OIDC. If that isn't 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 readablity 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 (for example via a PLOSSYS 4 Webportal 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 all entities

{
  "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