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¶
-
Open a Command Prompt or PowerShell.
-
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 -
Edit the exported file
<filename>.yml. -
Go to the section for all SEAL Operator services. Change the values for
ID_PROVIDER_NAMEandAUTH_ISSUER_URLto 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_URLandID_PROVIDER_NAMEhas changed.-
old value:
https://<hostname>:32769/auth/realms/SEAL -
new value:
https:/<hostname>:32769/realms/SEAL
-
-
Save the
<filename>.ymlfile. -
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:
-
Open a Command Prompt or PowerShell (not as Administrator).
-
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 -
Edit the exported file
<filename>.yml. -
In the
envsection, 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 partsmicrosoft: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 ... -
-
In the
envsection, specify the following keys for theoperator-uiservice:-
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 ... -
-
Save the file
<filename>.yml -
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¶
-
Open a Command Prompt or PowerShell.
-
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 -
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-uiservice, 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:
AUTH_CLIENT_ID: Client name configured in the OIDC identity provider for retrieving the access tokenAUTH_CLIENT_SECRET: Client secret for retrieving the OIDC identity provider's access tokenAUTH_ISSUER_URL: OIDC issuer URL
Literature - keys
For more information, 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-clientfor SEAL Print Client -
seal-opclifor SEAL OP-CLI -
seal-webportalfor 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-opcliandseal-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_IDfor the respective service. -
<role-specified-in-oidc>: Withinroles, 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,techuserandservice-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