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. Standalone Single Sign-On

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',
    },
    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.preprod.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',
    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
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.


    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%2Fuser-frontend.api.preprod.pl-x.cloud%2Fpreview%2Fsso%2Fdashboard
        &state=vHH_GWJv.-REfY~X
        &code_challenge=ZjBhZmE1YjQxMzEzYjY4NjQzMjM0YzcyM2I3M2JiMDY2MzQ0NTlmOGY1YjM2ZmZmOTIyNzJhY2I1YTliYjY2ZA
        &code_challenge_method=S256
        &css_url=https://user-frontend.api.preprod.pl-x.cloud

    EXAMPLE redirect to: https://user-frontend.api.preprod.pl-x.cloud/preview/sso/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.
css_url optional The URL to the CSS file used for customization of login form.
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

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.