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¶

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
```
Edit the exported file <filename>.yml.
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
Save the <filename>.yml file.

Re-import it to Consul.

operator config import <filename>.yml --insecure

Using Another OIDC Identity Provider¶

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
```
Edit the exported file <filename>.yml.

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

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)
        ...

Save the file <filename>.yml.

Re-import it to Consul.

operator config import <filename>.yml --insecure

The following keys have to be set for calling SEAL Operator CLI unless the respective default applies:
- AUTH_CLIENT_ID: Client name configured in the OIDC identity provider for retrieving the access token
- AUTH_CLIENT_SECRET: Client secret for retrieving the OIDC identity provider's access token
- AUTH_ISSUER_URL: OIDC issuer URL

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:

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