PxUser-Frontend Documentation

Table of Contents

  1. Prerequisites
  2. Class Config
  3. Widgets-Types
    1. Password Forgot + Resend Activation Mail
    2. Password Set
    3. Activate User
    4. Login
    5. Activate user With Activation Code
    6. Activate User and Login
    7. Password set by forgot password code
    8. Password set by forgot password code and login
    9. Confirm New Email
    10. Configure an External Identity Provider
    11. Single Sign-On
    12. Open ID Connect
    13. Standalone Single Sign-On
    14. Account Linking
    15. MFA Setup

How to embed PxUser widgets into a website

Prerequisites

  1. Embed <script src="https://user-frontend.api.pl-x.cloud/js/widget.js"></script> in any page you want to use these widgets.
  2. Add HTML-Elements with unique IDs for each widget. (e.g. <div id="pxUserPasswordForgot"></div>)

Class Config

Our config consists of two parts. There is the main class which contains general settings for a product, and then there are individual methods for each widget which accept additional config.

let pxUserFrontend = new PxModUser({
    stage: 'prod',
    domain: 'px-user-frontend-preview',
    tenant: 'demo',
    cssUrl: 'https://www.example.com/styles.css',
    language: 'de'
});
Parameter Description
stage required
The stage your site runs on. Defines wether widgets should be served from testing or production environment.
Available values: preprod / prod.
domain required
Domain code which is provided by VNR for every product (e.g. px-user-frontend-preview).
tenant required
Tenant code which is provided by VNR for every product (e.g. demo).
cssUrl Absolute path to a CSS file to add custom styling to all widgets.
language Default language for messages and labels.
Available values: en / de.

This applies to all widgets

After clicking a submit button, the button will automatically be disabled as well as the class .loading is added for individual styling. It will be removed once the server sends a response.

Widgets-Types

Password Forgot + Resend Activation Mail

Click to expand 
pxUserFrontend.showPasswordForgotForm({
    containerElement: 'pxUserPasswordForgot',
    fallbackTargetUrl: 'https://www.example.com/password-forgot',
    fallbackButtonText: 'Send password reset email!',
    labels: {
        buttonText: 'Send password reset email!',
        email: 'Email-address'
    },
    products: ['sap', 'dam', 'vid'],
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
containerElement required
HTML-Element where this widget will be rendered in.
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button .
labels optional Labels for button and form elements.
Default: { buttonText: 'Send link', email: 'Email address' }
products optional
An array of products for which the password reset is requested.
Default: null
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "OK", response: {} }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { success: false, code: 403, http_code: 403, message: "CSRF token mismatch." }

Password Set

Click to expand 
pxUserFrontend.showPasswordSetForm({
    token: 'abc123',
    containerElement: 'pxUserPasswordSet',
    showPasswordRules: false,
    fallbackTargetUrl: 'https://www.example.com/password-set',
    fallbackButtonText: 'Reset Password!',
    labels: {
        buttonText: 'Reset Password!',
        passwordOne: 'Password',
        passwordTwo: 'Password again'
    },
    icons: {
        togglePassword: {
            passwordOne: true,
            passwordTwo: true
        }
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
token required
Security-Token from URL.
containerElement required
HTML-Element where this widget will be rendered in.
showPasswordRules optional
Show password rules under the password field directly by typing.
Default: false
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Set new password', passwordOne: 'Password', passwordTwo: 'Password again' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {passwordOne: true, passwordTwo: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {passwordOne: 'bi bi-eyeglasses', passwordTwo: true}
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "Success", response: { passed: true } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Activate User

Click to expand 
pxUserFrontend.showActivateUserForm({
    token: 'abc123',
    containerElement: 'pxUserActivateUser',
    showPasswordRules: false,
    fallbackTargetUrl: 'https://www.example.com/user-activate',
    fallbackButtonText: 'Set Password!',
    labels: {
        buttonText: 'Set Password!',
        passwordOne: 'Password',
        passwordTwo: 'Activate user'
    },
    icons: {
        togglePassword: {
            passwordOne: true,
            passwordTwo: true
        }
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
token required
Security-Token from URL.
containerElement required
HTML-Element where this widget will be rendered in.
showPasswordRules optional
Show password rules under the password field directly by typing.
Default: false
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Activate user', passwordOne: 'Password', passwordTwo: 'Password again' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {passwordOne: true, passwordTwo: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {passwordOne: 'bi bi-eyeglasses', passwordTwo: true}
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "Success", response: { passed: true } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Login

Click to expand 
pxUserFrontend.showLoginForm({
    containerElement: 'pxUserLogin',
    fallbackTargetUrl: 'https://www.example.com/login',
    fallbackButtonText: 'Login!',
    showLoginWithEip: true,
    state: '7YiroLzzn2tmYdF58XlA6UVLjTbFJQRO',
    labels: {
        buttonText: 'Login!',
        username: 'Email-Address',
        password: 'Password',
        loginWithEntraId: 'Or login with your company\'s Microsoft login',
        emailOrUsername: 'Email/Username',
        continue: 'Continue',
        or: 'Or',
        back: 'Back',
        loginWithMicrosoft: 'Sign in with Microsoft',
    },
    icons: {
        togglePassword: {
            password: true
        }
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
token required
Security-Token from URL.
containerElement required
HTML-Element where this widget will be rendered in.
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Login', username: 'Username', password: 'Password' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {password: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {password: 'bi bi-eyeglasses'}
showLoginWithEip optional Show login with EIP form.
Default: false
eipLoginRedirectUri optional (with showLoginWithEip) EIP redirect URI (URL to which the user is redirected after successful login). If not set, we current url will be used. It must match one of the URLs configured in the EIP.
Default: null
state optional (with showLoginWithEip) A state which is sent back to the eipLoginRedirectUri to verify the login's source.
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "OK", response: { access_token: 'abc', access_token_lifetime_minutes: 120, access_token_expiration_utc: '2021-10-07T13:15:39.120677Z', refresh_token: 'xyz', refresh_token_lifetime_minutes: 43200, refresh_token_expiration_utc: '2021-11-06T11:15:39.121160Z' } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Activate User With Activation Code

Click to expand 
pxUserFrontend.showActivateUserByActivationCodeForm({
    containerElement: 'pxUserActivateUserByActivationCode',
    showPasswordRules: false,
    showUsernameRules: false,
    labels: {
        activationCode: 'Activation code',
        buttonTextActivationCode: 'Next',
        username: 'Username',
        passwordOne: 'Password',
        passwordTwo: 'Password again',
        buttonText: 'Activate',
    },
    icons: {
        togglePassword: {
            passwordOne: true,
            passwordTwo: true
        }
    },
    fallbackTargetUrl: 'https://www.example.com/activate-user-by-activation-code',
    fallbackButtonText: 'Activate User',
    onSuccessActivationCode: (data) => {
        doSomethingWith(data)
    },
    onErrorActivationCode: (error) => {
        doSomethingWith(error)
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
containerElement required
HTML-Element where this widget will be rendered in.
showPasswordRules optional
Show password rules under the password field directly by typing.
Default: false
showUsernameRules optional
Show username rules under the username field directly by typing. If not defined, the value of showPasswordRules will be used.
Default: false
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Activate user', activationCode: 'Activation code', username: 'Username', passwordOne: 'Password', passwordTwo: 'Password again' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {passwordOne: true, passwordTwo: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {passwordOne: 'bi bi-eyeglasses', passwordTwo: true}
onSuccessActivationCode Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "Success", response: { passed: true } }
onErrorActivationCode Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "Success", response: { passed: true } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Activate User and Login

Click to expand 
pxUserFrontend.showActivateUserLoginForm({
    token: 'abc123',
    containerElement: 'pxUserActivateUserLogin',
    showPasswordRules: false,
    fallbackTargetUrl: 'https://www.example.com/user-activate',
    fallbackButtonText: 'Activate user and login!',
    labels: {
        buttonText: 'Activate user and login!',
        passwordOne: 'Password',
        passwordTwo: 'Password again'
    },
    icons: {
        togglePassword: {
            passwordOne: true,
            passwordTwo: true
        }
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
token required
Security-Token from URL.
containerElement required
HTML-Element where this widget will be rendered in.
showPasswordRules optional
Show password rules under the password field directly by typing.
Default: false
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Activate user', passwordOne: 'Password', passwordTwo: 'Password again' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {passwordOne: true, passwordTwo: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {passwordOne: 'bi bi-eyeglasses', passwordTwo: true}
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "OK", response: { access_token: 'abc', access_token_lifetime_minutes: 120, access_token_expiration_utc: '2021-10-07T13:15:39.120677Z', refresh_token: 'xyz', refresh_token_lifetime_minutes: 43200, refresh_token_expiration_utc: '2021-11-06T11:15:39.121160Z' } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Password set by forgot password code

Click to expand 
pxUserFrontend.showPasswordSetByForgotPasswordCodeForm({
    containerElement: 'pxUserPasswordSetByForgotPasswordCode',
    showPasswordRules: false,
    labels: {
        username: 'Username',
        forgotPasswordCode: 'Forgot password code',
        passwordOne: 'Password',
        passwordTwo: 'Password again',
        buttonText: 'Set password',
    },
    icons: {
        togglePassword: {
            passwordOne: true,
            passwordTwo: true
        }
    },
    fallbackTargetUrl: 'https://www.example.com/password-set-by-forgot-password-code',
    fallbackButtonText: 'Set password',
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
containerElement required
HTML-Element where this widget will be rendered in.
showPasswordRules optional
Show password rules under the password field directly by typing.
Default: false
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Password set', username: 'Username', forgotPasswordCode: 'Forgot password code', passwordOne: 'Password', passwordTwo: 'Password again' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {passwordOne: true, passwordTwo: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {passwordOne: 'bi bi-eyeglasses', passwordTwo: true}
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "Success", response: { passed: true } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Password set by forgot password code and login

Click to expand 
pxUserFrontend.showPasswordSetByForgotPasswordCodeLoginForm({
    containerElement: 'pxUserPasswordSetByForgotPasswordCodeLogin',
    showPasswordRules: false,
    labels: {
        username: 'Username',
        forgotPasswordCode: 'Forgot password code',
        passwordOne: 'Password',
        passwordTwo: 'Password again',
        buttonText: 'Set password and login',
    },
    icons: {
        togglePassword: {
            passwordOne: true,
            passwordTwo: true
        }
    },
    fallbackTargetUrl: 'https://www.example.com/password-set-by-forgot-password-code-login',
    fallbackButtonText: 'Set password and login',
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
containerElement required
HTML-Element where this widget will be rendered in.
showPasswordRules optional
Show password rules under the password field directly by typing.
Default: false
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Password set', username: 'Username', forgotPasswordCode: 'Forgot password code', passwordOne: 'Password', passwordTwo: 'Password again' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {passwordOne: true, passwordTwo: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {passwordOne: 'bi bi-eyeglasses', passwordTwo: true}
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "OK", response: { access_token: 'abc', access_token_lifetime_minutes: 120, access_token_expiration_utc: '2021-10-07T13:15:39.120677Z', refresh_token: 'xyz', refresh_token_lifetime_minutes: 43200, refresh_token_expiration_utc: '2021-11-06T11:15:39.121160Z' } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Confirm New Email

Click to expand 
    pxUserFrontend.showConfirmNewEmailForm({
        token: 'abc123',
        containerElement: 'pxUserConfirmNewEmail',
        fallbackTargetUrl: 'https://www.example.com/confirm-new-email',
        fallbackButtonText: 'Confirm New Email',
        onSuccess: (data) => {
            doSomethingWith(data)
        },
        onError: (error) => {
            doSomethingWith(error)
        }
    });
Parameter Description
containerElement required
HTML-Element where this widget will be rendered in.
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
onSuccess Function which will be called if form is submitted successfully.
Returns JSON object.
e.g. { success: true, code: 200, http_code: 200, message: "Success", response: { passed: true } }
onError Function which will be called if there is an error when submitting the form.
Returns JSON object.
e.g. { "success": false, "code": 1200, "http_code": 401, "message": "Unauthorized", "response": null, "metadata": [] }

Configure an External Identity Provider

Click to expand 
pxUserFrontend.showEipConfigForm({
    token: 'abc123',
    containerElement: 'pxUserEipConfig',
    fallbackTargetUrl: 'https://www.example.com/eip-config',
    fallbackButtonText: 'Save config',
    labels: {
        tenantId: 'Tenant ID',
        clientId: 'Client ID',
        clientSecret: 'Client Secret',
        groupId: 'Group ID',
        testButtonText: 'Test',
        saveButtonText: 'Save',
    },
    onSuccess: (payload) => {
        const source = payload.source;
        const data = payload.data;

        if (source === 'test') {
            showAlertSuccess('Config is valid. Found ' + data.response.userCount + ' users.');
        } else {
            showAlertSuccess('Config saved');
        }
    },
    onError: (error) => {
        showAlertDanger(`Error: ${error.data.message}, Source: ${error.source}`);
    }
});
Parameter Description
token required
Security-Token from URL.
containerElement required
HTML-Element where this widget will be rendered in.
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default values are used in the example above.
onSuccess Function which will be called if form is submitted successfully.
You can access an object in the callback argument. There are two types of responses you can get (one from the test endpoint and one from the save endpoint).
E.g. (Test response):
{ source: "test", data: { success: true, code: 200, http_code: 200, message: "Tested successfully.", response: { userCount: 450 } } }
E.g. (Save response):
{ source: "save", data: { success: true, code: 200, http_code: 200, message: "Credentials stored.", response: null } }
onError Function which will be called if there is an error when submitting the form.
You can access an object in the callback argument.
E.g. (Test response):
{ source: "test", data: { success: false, code: 422, http_code: 422, message: "Test not successful", response: null }
E.g. (Save response):
{ source: "save", data: { success: false, code: 500, http_code: 500, message: "Credentials storing failed.", response: null } }

Single Sign-On (widget)

Click to expand

Single Sign-On Widget follows OAuth 2.0 Authorization Code Grant. See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1 for more information. 

pxUserFrontend.showLoginSsoForm({
    // OAuth 2.0 + PKCE
    client_id: 'abc123',
    state: '7YiroLzzn2tmYdF58XlA6UVLjTbFJQRO',
    redirect_uri: 'https://user-frontend.api.pl-x.cloud/preview/dashboard'
    code_challenge: 'ZjBhZmE1YjQxMzEzYjY4NjQzMjM0YzcyM2I3M2JiMDY2MzQ0NTlmOGY1YjM2ZmZmOTIyNzJhY2I1YTliYjY2ZA',
    code_challenge_method: 'S256',
    // widget configuration
    containerElement: 'pxUserLoginSso',
    fallbackTargetUrl: 'https://www.example.com/login',
    fallbackButtonText: 'Login!',
    showLoginWithEip: true,
    eipLoginRedirectUri: 'https://www.example.com/login',
    messages: {
        ssoLoginFailed: 'Custom error message must be defined here.'
    },
    labels: {
        buttonText: 'Login!',
        username: 'Email-Address',
        password: 'Password',
        loginWithEntraId: 'Or login with your company\'s Microsoft login',
        emailOrUsername: 'Email/Username',
        continue: 'Continue',
    },
    icons: {
        togglePassword: {
            password: true
        }
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
client_id required
The client identifier. [1]
redirect_uri required Where to redirect after successful login. [2]
state recommended A state which is sent back to the redirect_url to verify the login's source [3]
code_challenge required A code challenge for the PKCE flow. Hints: use raw output of hash method and make the base64-encoded-string url-safe [4]
code_challenge_method required The method used to generate the code challenge. Currently only "S256" is supported [5]
containerElement required
HTML-Element where this widget will be rendered in.
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
messages optional Messages for the widget.
Default: { ssoLoginFailed: 'Login is not possible. Please check your username and password and try again. Your account may not be configured for SSO login. Please contact your administrator.' }
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Login', username: 'Username', password: 'Password' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {password: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {password: 'bi bi-eyeglasses'}
showLoginWithEip optional Show login with EIP form.
Default: false
eipLoginRedirectUri optional EIP redirect URI (URL to which the user is redirected after successful login). If not set, we current url will be used. It must match one of the URLs configured in the EIP.
Default: null
onSuccess Not used for SSO. Instead, the user will be redirected back to defined redirect_uri. The url contains following query parameters: code and state (see: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2). You have to use them to request access token (see: https://user.api.pl-x.cloud/docs/#token-POSTv1-oauth-token--token_type-- with grant_type=authentication_code)
onError Will be documented soon
References

[1]: See https://datatracker.ietf.org/doc/html/rfc6749#section-2.2 for more information about the client_id parameter.

[2]: See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information about the redirect_uri parameter.

[3]: See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1 for more information about the state parameter.

[4]: See https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 and https://datatracker.ietf.org/doc/html/rfc7636#appendix-A for more information about the code_challenge parameter.

[5]: See https://datatracker.ietf.org/doc/html/rfc7636#section-4.3 for more information about the code_challenge_method parameter.

Open ID Connect (widget)

Click to expand

Open ID Connect Widget follows OIDC 1.0 Authorization Code Grant. See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1 for more information. 

pxUserFrontend.showLoginOidcForm({
    client_id: 'abc123',
    state: '7YiroLzzn2tmYdF58XlA6UVLjTbFJQRO',
    redirect_uri: 'https://user-frontend.api.pl-x.cloud/preview/dashboard'
    code_challenge: 'ZjBhZmE1YjQxMzEzYjY4NjQzMjM0YzcyM2I3M2JiMDY2MzQ0NTlmOGY1YjM2ZmZmOTIyNzJhY2I1YTliYjY2ZA',
    code_challenge_method: 'S256',
    // widget configuration
    containerElement: 'pxUserLoginOidc',
    fallbackTargetUrl: 'https://www.example.com/login',
    fallbackButtonText: 'Login!',
    showLoginWithEip: true,
    eipLoginRedirectUri: 'https://www.example.com/login',
    scope: 'openid profile email',
    prompt: 'login',
    labels: {
        buttonText: 'Login!',
        username: 'Email-Address',
        password: 'Password',
        loginWithEntraId: 'Or login with your company\'s Microsoft login',
        emailOrUsername: 'Email/Username',
        continue: 'Continue',
    },
    icons: {
        togglePassword: {
            password: true
        }
    },
    onSuccess: (data) => {
        doSomethingWith(data)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
client_id required
The client identifier. [1]
redirect_uri required Where to redirect after successful login. [2]
state recommended A state which is sent back to the redirect_url to verify the login's source [3]
code_challenge required A code challenge for the PKCE flow. Hints: use raw output of hash method and make the base64-encoded-string url-safe [4]
code_challenge_method required The method used to generate the code challenge. Currently only "S256" is supported [5]
containerElement required
HTML-Element where this widget will be rendered in.
fallbackTargetUrl required
If there are errors in JS code, this is a fallback where form contents are sent to with a POST request.
fallbackButtonText required
If there are errors in JS code, this is the text for the submit button.
labels optional Labels for button and form elements.
Default: { buttonText: 'Login', username: 'Username', password: 'Password' }
icons.togglePassword optional Icons and onclick events for toggle (show/hide) the password.
Default: {password: true}. The default icon is eye.
E.g. use custom icon (bootstrap): {password: 'bi bi-eyeglasses'}
showLoginWithEip optional Show login with EIP form.
Default: false
scope required for OIDC The scope of data to be retrieved
prompt optional for OIDC The type of prompt to control user interaction:
- login: Force the user to re-authenticate.
- none: Silent authentication without user interaction.
- consent: Force the user to provide consent for requested scopes.
eipLoginRedirectUri optional EIP redirect URI (URL to which the user is redirected after successful login). If not set, we current url will be used. It must match one of the URLs configured in the EIP.
Default: null
onSuccess Not used for SSO. Instead, the user will be redirected back to defined redirect_uri. The url contains following query parameters: code and state (see: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2). You have to use them to request access token (see: https://user.api.pl-x.cloud/docs/#token-POSTv1-oauth-token--token_type-- with grant_type=authentication_code)
onError Will be documented soon
References

[1]: See https://datatracker.ietf.org/doc/html/rfc6749#section-2.2 for more information about the client_id parameter.

[2]: See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information about the redirect_uri parameter.

[3]: See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1 for more information about the state parameter.

[4]: See https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 and https://datatracker.ietf.org/doc/html/rfc7636#appendix-A for more information about the code_challenge parameter.

[5]: See https://datatracker.ietf.org/doc/html/rfc7636#section-4.3 for more information about the code_challenge_method parameter.

Single Sign-On (standalone)

Click to expand

Single Sign-On Standalone follows OAuth 2.0 Authorization Code Grant. See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1 for more information. 


    OAuth GET https://user-frontend.api.preprod.pl-x.cloud/plx:pxc/oauth2/v2.0/authorize
        ?response_type=code
        &client_id=demo_user_frontend_preview
        &redirect_uri=https%3A%2F%2Fexample.com%2Fdashboard
        &state=vHH_GWJv.-REfY~X
        &code_challenge=ZjBhZmE1YjQxMzEzYjY4NjQzMjM0YzcyM2I3M2JiMDY2MzQ0NTlmOGY1YjM2ZmZmOTIyNzJhY2I1YTliYjY2ZA
        &code_challenge_method=S256
        &css_url=https://example.com/widget-custom.css
        &messages={"ssoLoginFailed":"Custom message here"}
    OIDC GET https://user-frontend.api.preprod.pl-x.cloud/plx:pxc/oidc/v1.0/authorize
        ?response_type=code
        &client_id=demo_user_frontend_preview
        &redirect_uri=https%3A%2F%2Fexample.com%2Fdashboard
        &state=vHH_GWJv.-REfY~X
        &code_challenge=ZjBhZmE1YjQxMzEzYjY4NjQzMjM0YzcyM2I3M2JiMDY2MzQ0NTlmOGY1YjM2ZmZmOTIyNzJhY2I1YTliYjY2ZA
        &code_challenge_method=S256
        &css_url=https://example.com/widget-custom.css
        &prompt=none
        &scope=openid%20profile%20email


    EXAMPLE redirect to: https://example.com/dashboard?code=eyJpdiI6IjBT..yI6IiJ9&state=vHH_GWJv.-REfY~X&mode=
Parameter Description
response_type required
Currently only 'code' is supported. [1]
client_id required
The client identifier. [2]
redirect_uri required Where to redirect after successful login. [3]
state recommended A state which is sent back to the redirect_url to verify the login's source [4]
code_challenge required A code challenge for the PKCE flow. Hints: use raw output of hash method and make the base64-encoded-string url-safe [5]
code_challenge_method required The method used to generate the code challenge. Currently only "S256" is supported [6]
tenant required The tenant identifier.
domain required The domain identifier.
scope required for OIDC The scope of data to be retrieved
prompt optional for OIDC The type of prompt (login, none, consent)
css_url optional The URL to the CSS file used for customization of login form.
messages optional Messages for the widget.
Example: { ssoLoginFailed: 'Login is not possible. Please check your username and password and try again. Your account may not be configured for SSO login. Please contact your administrator.' }
Responses

The endpoint can return two types of responses:

  1. Success Response

    • Renders the login widget when all parameters are valid
    • Shows the platform X login form with:
      • Email/Username field
      • Password field
      • Login button
      • Optional EIP login section

  2. Error Response

    • Renders an error page when validation fails
    • Shows detailed information about what went wrong
    • HTTP Status Code: 400 Bad Request

Common validation errors:

  • Missing required parameters
  • Invalid response_type (must be 'code')
  • Invalid code_challenge_method (must be 'S256')
  • Invalid redirect_uri format
  • Mismatched client_id and redirect_uri
  • Invalid tenant or domain

Important note: The authentication_code which is added to the redirect_uri has a TTL of only 5 seconds.

After successful login, the user will be redirected to the specified redirect_uri with the authorization code and state parameters.

References

[1]: See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.1 for more information about the response_type parameter.

[2]: See https://datatracker.ietf.org/doc/html/rfc6749#section-2.2 for more information about the client_id parameter.

[3]: See https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2 for more information about the redirect_uri parameter.

[4]: See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1 for more information about the state parameter.

[5]: See https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 and https://datatracker.ietf.org/doc/html/rfc7636#appendix-A for more information about the code_challenge parameter.

[6]: See https://datatracker.ietf.org/doc/html/rfc7636#section-4.3 for more information about the code_challenge_method parameter.

MFA Setup

Click to expand

The MFA Setup widget allows a logged-in user to enable or disable multi-factor authentication. If MFA is not enabled, it renders a button to start the setup. On successful setup initiation, the widget automatically proceeds to the MFA initialization flow (QR code/verification step).

pxUserFrontend.showMfaSetupForm({
    token: 'abc123',
    containerElement: 'pxUserMfaSetup',
    onSuccess: (payload) => {
        // Called on successful actions (e.g., disable completed or flow progressed)
        doSomethingWith(payload)
    },
    onError: (error) => {
        doSomethingWith(error)
    }
});
Parameter Description
token required
Security-Token from URL.
containerElement required
HTML-Element where this widget will be rendered in.
onSuccess Function called on successful actions. Receives payload object.
onError Function called on errors. Receives payload object.

Notes:

  • If the user has MFA disabled, the widget starts the setup and then automatically navigates to the MFA initialization widget.
  • If the user already has MFA enabled, the widget renders a button to disable MFA.

Account Linking

Click to expand 
pxUserFrontend.showALS({
    hostUrlsParams: new URLSearchParams(window.location.search),
    redirect_uri: 'https://www.example.com/endpoint',  // <-- The product URL with login widget
    base_uri: 'https://www.example.com/endpoint', // <-- The product URL were the ALS widget is integrated
    ...({}),
    containerElement: 'pxUserAls',
    onSuccess: () => {},
    onError: () => {}
});

The ALS Widget knows which products to connect with each other. When using the ALS widget and start linking user accounts, you will first redirected to the login of the first product. After the user successfully logs into the first product he or she is redirected to the base_uri which must lead back to the page with the ALS Widget, which then recognize the first auth. Then it will redirect to the second product where the user has to sign in also. After the second successful login the user is once again redirected back to the base_uri where the ALS Widget will show him or her a confirmation that the accounts have been connected. There a Button will display which links to the provided redirect_uri. This Button and thus the redirect_uri should Link to a page where the OIDC Login Widget will display. The Login Widget will notice that the user has logged in during the ALS process and log the user into the portal.

Parameter Description
stage required
The stage your site runs on. Defines whether widgets should be served from testing or production environment.
Available values: preprod / prod.
domain required
Domain code which is provided by VNR for every product (e.g. px-user-frontend-preview).
tenant required
Tenant code which is provided by VNR for every product (e.g. demo).
cssUrl Absolute path to a CSS file to add custom styling to all widgets.
language Default language for messages and labels.
Available values: en / de.
labels optional Labels for button and form elements.
Default values are used in the example above.
onSuccess Function which will be called if form is submitted successfully.
onError Function which will be called if there is an error when submitting the form