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 with the following command. 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. 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 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 AD FS

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

On AD FS 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 AD FS as OIDC Identidy Provider, execute the following steps in SEAL Operator:

  1. Open a Command Prompt or PowerShell (not as Administrator).

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

    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: Secret generated when configuring the first server application in AD FS above

    • AUTH_CLIENT_ID: ID generated when configuring the first server application in AD FS above

    • AUTH_ISSUER_URL: This URL is used by the services for connecting to the AD FS provider.

    • ID_PROVIDER_NAME: Name of the AD FS; hint: Even configured to use the HTTPS protocol, the URL provided here comes without HTTPS protocol and uses HTTP protocol as URI!

    • ID_PROVIDER_CERT: Absolute path and file name to the certificate file exported above (optional)

    • TRUSTED_CLIENT: Client name configured in AD FS for granting access via access token; the information is contained in the token. This URI is used to check the token from the AD FS. It is a combination of two parts microsoft:identityserver:<client_identifier>.

      env:
    service:
      any:
        tag:
          any:
            ...
            AUTH_CLIENT_SECRET: ZveeFKncasjTvkCVul7jS_d_SdlltJLgFeW2-4IU
            AUTH_CLIENT_ID: f20d7f7b-6e78-4259-a796-85946aeaaa27
            AUTH_TOKEN_ENDPOINT: https://oictest.de/adfs/oauth2/token
            AUTH_ISSUER_URL: https://oictest.de/adfs/
            ID_PROVIDER_NAME: http://oictest.de/adfs/services/trust
            ID_PROVIDER_CERT: c:\cert\export_token_signing.cer
            TRUSTED_CLIENT: microsoft:identityserver:f20d7f7b-6e78-4259-a796-85946aeaaa27
            ...

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

    • AUTH_CLIENT_SECRET: Secret generated when configuring the second server application in AD FS above

    • AUTH_CLIENT_ID: ID generated when configuring the second server application in AD FS above

      env:
    service:
      ...
        operator-ui:
          tag:
            any:
              ...
              AUTH_CLIENT_SECRET: TJ79W3mMnvPDJ6Ax0kGt8YFz-0ooF3HNdRUpy6as
              AUTH_CLIENT_ID: ab762716-544d-4aeb-a526-687b73838a33
              ...

  6. Save the file <filename>.yml

  7. Re-import it to Consul.

    operator config import <filename>.yml --insecure

Literature - keys

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

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

  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:
          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 section for the operator-ui service, configure the following key for the authorization code grant:

    • [AUTH_CLIENT_ID]: Client name configured in the OIDC identity provider. Default: seal-print-client
    env:
  service:
    ...
    operator-ui:
      tag:
        any:
          AUTH_CLIENT_ID: <client_id_used_in_idp>
        ...

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

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