Create Web Portal Shares with Subfolders¶
Via REST API¶
Workflow¶
You can use the API to create Web Portal shares. When outputting order data from SAP it might be required to automatically create subfolders within the share.
The workflow follows these steps:
- Discover the token endpoint from the identity provider (IDP), then request an access token via the password grant. Send the token as
Authorization: Bearer <token>header on every following call. - Create the share with a
POSTto therepoendpoint. The responselinks.self.hrefis the share's address for the next steps. - Create a subfolder inside the share with a
POSTto the share'shref, body{"name":"<name>","type":"collection"}. - Create a document inside the subfolder with a
POSTto the subfolder'shref, body{"name":"<name>","type":"document"}. - Upload the file content with a
PUTto the document'shrefplus/content.
Repeat steps 3 to 5 for each subfolder or document to add.
Authenticate via Client Credentials for MFA-Enforced Identity Providers¶
The steps above use the password grant to retrieve the access token. Some identity providers reject the password grant when multi-factor authentication (MFA) is enforced for the whole tenant. Azure AD (Microsoft Entra ID) returns error AADSTS50158: External security challenge not satisfied (error code 50158) in that case.
For such tenants, use the client credentials grant instead of the password grant. Request the token from the same token endpoint, with grant_type=client_credentials, client_id, and client_secret instead of the user name and password.
The client credentials grant returns an access token for the OIDC client itself, not for a specific user. To create the share for a specific user, send the claims of this user in the x-user-auth header with every following call:
-
Create a JSON object with the claims of the user, for example:
{"sub":"<user-id>","name":"<name>","preferred_username":"<user-name>"} -
Encode the JSON object with Base64.
-
Send the result as
x-user-auth: <encoded_claims>header in addition to theAuthorizationheader.
SEAL Operator merges these claims into the access token. The request then runs on behalf of this user.
Caution - client must be the trusted client
SEAL Operator evaluates x-user-auth only if the access token was issued for the client configured in TRUSTED_CLIENT for seal-operator-webportal. Use this client as client_id. Otherwise, SEAL Operator ignores the header without an error message, and the share is not created for this user.
Caution - trusted client has full permissions
Every access token issued for the trusted client gets full permissions in SEAL Operator, also without x-user-auth. Protect the client secret of the trusted client accordingly.
Hint - seal-dpf-workingunit-webportal
The DPF working unit seal-dpf-workingunit-webportal implements this flow through its own input parameters WEBPORTAL_AUTH_GRANT_TYPE, WEBPORTAL_X_USER_AUTH, and WEBPORTAL_X_USER_AUTH_FILE. These are parameters of the working unit, not of SEAL Operator. For their usage, refer to Connect SEAL Operator/Web Portal in the PLOSSYS Distribution Engine documentation.