Usage

The Dev Portal comes with a built-in login page that allows users to authenticate via basic authentication or single sign-on (SSO). Internally, this page uses the form-login component which can additionally be used in a custom login page created in your Dev Portal to allow for customizing the layout and design of the login experience.

The form-login component
::form-login
---
basic-auth-cta-text: "Log in"
sso-auth-cta-text: "Continue with SSO"
---
::

The Form Login component will automatically enable or disable UI elements and functionality based on the authentication methods enabled in your Dev Portal settings.

Along with built-in authentication flow and error handling logic, the component includes the following UI elements:

Basic Authentication

  • Email input
  • Password input
  • Forgot password link
  • Submit button
  • Sign up link (if basic auth is enabled)
  • Error state(s)

Single Sign-On (SSO)

  • SSO button with customizable text
  • SSO loading state
  • Error state(s)

The component is automatically hidden in the following scenarios:

  • When the user is already authenticated (logged in)
  • When the Dev Portal is public (does not support authentication)
  • If the component is utilized on a page that does not have a path of /login

Custom Login page

Important

To create a custom login page, you must ensure it is created with a root slug of /login in order to override the default Dev Portal login page content. In addition, the form-login component must be included on a page set to visibility: 'public' in order for unauthenticated users to access the form.

To create a customized login page in your Dev Portal:

  1. Create a new Page in your Dev Portal at the root of the tree with a slug of /login. You must create the page with visibility set to 'public'. This will override the built-in login page content.
  2. Set the page's layout front matter property to custom. The custom layout renders no navigation sidebar or built-in page header, so the login experience gets the full page. See Layouts for more details.
  3. Customize the page with markdown and MDC, including other components, layout elements, etc. as desired.
  4. Add the form-login component to the page's content to allow users to authenticate into your Portal.
  5. Optionally, customize the component props to fit your desired experience.

Simple Example

Here's a simple example of a custom login page that uses the form-login component:

Example of the default registration form
---
title: "Log in"
description: "Log in to our Developer Portal."
---

::container
---
vertical-align: "center"
height: "100%"
display: "flex"
flex-direction: "column"
align-items: "center"
justify-content: "center"
padding: "var(--kui-space-0, 0px) var(--kui-space-70, 20px)"
---
  :::card
  ---
  margin: "var(--kui-space-70, 20px) var(--kui-space-auto, auto)"
  max-width: "460px"
  ---
  #title
  Log in

  #default
    ::::form-login
    ---
    basic-auth-cta-text: "Log in"
    sso-auth-cta-text: "Continue with SSO"
    ---
    ::::

  :::
::

Advanced Example

Here's a more advanced example of a custom login page that uses the form-login component, along with additional MDC components and custom styles:

Example of an advanced login form with an image
---
title: "Sign in to your account"
description: "Sign in to access your Dev Portal account."
---

::container
---
width: "100%"
height: "300px"
background: "linear-gradient(90deg, var(--kui-color-background-primary-strong) 0%, var(--kui-color-background-primary) 50%, var(--kui-color-background-primary-strongest) 100%)"
styles: |
  position: absolute;
  top: 0;
  clip-path: polygon(0 0, 100% 0, 100% 75%, 0 100%);
  -webkit-clip-path: polygon(0 0, 100% 0, 100% 75%, 0 100%);
  overflow: hidden;
---
::

::page-section
---
full-width: true
full-height: true
background-color: "var(--kui-color-background-primary-strongest)"
---
  :::page-section
  ---
  vertical-align: "center"
  height: "100%"
  display: "flex"
  flex-direction: "column"
  align-items: "center"
  justify-content: "center"
  padding: "var(--kui-space-0, 0px)"
  max-width: "var(--kui-breakpoint-tablet)"
  styles: |
    position: relative;
    z-index: 1;
  ---
    ::::multi-column
    ---
    vertical-align: "center"
    columns-breakpoints:
      desktop: 2
      laptop: 2
      tablet: 2
      phablet: 2
      mobile: 1
    ---
      :::::container
      ---
      background-image:
        url: "https://example.com/your-image.png"
        background-size: "cover"
      border-radius: "var(--kui-border-radius-50)"
      width: "100%"
      height: "100%"
      ---
      :::::

      :::::card
      #title
      Sign in to your account

      #default
        ::::::form-login
        ---
        basic-auth-cta-text: "Sign in"
        max-width: "none"
        ---
        ::::::
      :::::
    ::::
  :::
::

Props

basicAuthCtaText

The basic authentication form submit button text.

  • Type: string
  • Default: Log in

ssoAuthCtaText

The single sign-on (SSO) submit button text.

  • Type: string
  • Default: Continue with SSO

ssoAuthInstructionText

The single sign-on (SSO) instruction text displayed above the SSO button when only SSO is enabled and basic auth is disabled.

  • Type: string
  • Default: To access the developer portal, please log in using the organization's single sign-on (SSO) provider.

Shared Props

This component also includes the shared props listed below:

  • background - default is initial.
  • backgroundColor - default is initial.
  • border - default is initial.
  • borderRadius - default is var(--kui-border-radius-0, 0).
  • margin - default is var(--kui-space-0, 0).
  • maxWidth - default is 400px.
  • padding - default is var(--kui-space-0, 0).
  • width - default is auto.
  • styles - default is ''.