https://docs.microsoft.com/en-us/style-guide/procedures-instructions/formatting-text-in-instructions

https://docs.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui

From Jessica at Plotly

• You can trim your copy a lot by getting rid of quotation marks around UI elements, bolding them instead, and omitting the type of element (ex. "button")
• Some good pointers about which verbs to use in order to be clear, consistent, and inclusive. You'll find Google docs still say "click," but that's because they're behind. 🙂 I noticed you have "select" in most places but a couple instances of "click".

Placeholder for how we are going to call Keycloak and Phase Two APIs from a single class/object.

Goals:

1. Reduce cut-n-paste in the code
2. Make it so we can easily replace the URL paths with the org url for future multi-org
3. Make convenience methods so that calling the API does not require knowing the full request object (e.g. just the attribute.name and user.attribute for calling the /mappers endpoint)

No reason to have the logos in the grid before we support at least one protocol.

per @jeffpatzer the useParams hook isn't working when I try to call it from useKeycloakAdminApi when rendering the dashboard. we need this so we can get access to the realm in the path. E.g.

import KcAdminClient from "@keycloak/keycloak-admin-client";
import keycloak from "src/keycloak";
import { useParams } from "react-router-dom";

export const useKeycloakAdminApi = () => {
  let { realm } = useParams();
  
  const getServerUrl = () => {
    if (typeof keycloak.authServerUrl !== "undefined") {
      var u = keycloak.authServerUrl;
      if (u.charAt(u.length - 1) == "/") {
        u = u.substring(0, u.length - 1);
      }
      return u;
    } else {
      return undefined;
    }
  };

  const getRealm = () => {
    console.log("getRealm", realm);
    return realm;
  };

  const getAuthRealm = () => {
    if (typeof keycloak.realm !== "undefined") {
      return keycloak.realm;
    } else {
      return undefined;
    }
  };

  const settings = {
    baseUrl: getServerUrl(),
    realmName: getRealm(),
  };

  const kcAdminClient = new KcAdminClient(settings);

  const setKcAdminClientAccessToken = async () => {
    kcAdminClient.setAccessToken(keycloak.token!);
  };

  // Should be able to initiate off the bat and still provide as a callback
  setKcAdminClientAccessToken();

  return [
    kcAdminClient,
    setKcAdminClientAccessToken,
    getServerUrl,
    getRealm,
    getAuthRealm,
  ] as const;
};

User, login stats

On-prem:

• Active sessions: count from sessions
• Offline sessions: count from sessions
• Logins Today: count from events table
• Logins This Week: count from events table
• Users: all enabled users in this realm
• Failed Logins: count from events table
• Users Locked Out: tbd

Multi-organization

• Active sessions: count from sessions, filter by members of org
• Offline sessions: count from sessions, filter by members of org
• Logins Today: count from events table, filter by members of org
• Logins This Week: count from events table, filter by members of org
• Users: all enabled users who are members of this org
• Failed Logins: count from events table, filter by members of org
• Users Locked Out: tbd

There are several places where we use demo.phasetwo.io. This should be replaced with the current hostname. This value may change in the future, so we should have a helper function that returns the current hostname, but might change to a different/configurable value.

Plotly user was able to log in but didn't get the restricted access page.

should be dynamic using the name of the IdP

add an emailAsUsername flag

1. would cause a conditional mapper to appear on the mappers pages
2. would change the default keycloak mappers to set the remote idp email address to the keycloak username

Connection Status portlet on dashboard should show list of configured IdPs, with the active one on the top. Color (green, yellow) to differentiate status.

We used to auto fill the form fields in step 1 based on user input of "LDAP Host". it doesn't work anymore. Possible to bring it back?

If someone doesn't have the right role, make sure that the page doesn't flash, but shows a loader until the access is cleared. Really only and issue on a first page load.

Needs to have

view-identity-providers
manage-identity-providers
view-realm
manage-realm
view-events

Progress will be loss. Add a dialog to confirm the user wants to leave.

The alias key gets regenerated whenever the component is reloaded. It needs to make sure it only gets generated once for that account and that it doesn't change.

No additional wizard state needs to be saved at the moment.

When creating the IdP using the new IdP method, default values for config vars should be used if they were not present in the metadata url/file imports.

  ...
  config: {
    ...
    nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    principalType: "SUBJECT",
    ....
  }
  ...

This definitely is needed for Azure SAML, but probably is true of others.

Should be larger

We need a mechanism to tell the wizard that certain features are on/off, and have certain enums/modes set.

1. the backend will serve a json file with a feature:value hash. this will be on a per realm basis. /auth/realms//wizard/config.json
2. the frontend will fetch this file when it loads and make it available (as a hook?). the utility that loads it should have fallback values for each expected flag

Current flags:

• groupMapping: true/false. whether group mapping steps should be displayed in the wizards and the group mappers should be created when calling the api
• apiMode: cloud/onprem. which APIs to use
• enableLdap: true/false. allow LDAP wizards (this is related to apiMode, but might change in the future, so adding it separately)
• enableDashboard: true/false. whether or not to show the dashboard and link

Spec: https://docs.google.com/document/d/1PElZuqcANo4vqMnt313mY9EXSWqh86PkpHcxPEEfLxg/edit

Step index looks like this after clicking "continue" in step 1.

Instructions and link for initiating a login flow

Must set prompt=login

TBD spec

When a validation error occurs, highlight should be red.

Logout link needs to call keycloak.logout() and redirect to login (should be automatic)

Update and refactor to new formats to use correct validations and forms

We need to have a mode that allows the use of the wizards by two agents, 1. keycloak admins (kcadmin), and 2. organization admins (orgadmin)

The mode will dictate the URLs that are used for the API requests.

How do we differentiate between modes

• Can we serve a json doc that indicates the mode, config params, feature flags? See #83

What API methods are used for each mode

• For kcadmin, APIs used are as currently written
• For orgadmin, APIs are documented here http://phasetwo.io/api/ (specifically see the Identity Providers section)

What are the feature flags

• For orgadmin, we currently need a way to turn off any LDAP IdPs
• We want to conditionally enable the Dashboard
• API realm (currently indicated by the realm in the url)
• Authentication realm (currently indicated by the keycloak.json file, which is dynamically served for each realm

Missing because it's f-ing convoluted how you do it in OneLogin.

This screenshot should be its own instruction
src/app/images/azure/saml/azure-3a.png

1. user assignment
2. toggle to allow user access (upper right hand corner)

The following mappers need to be created following the creation of the IdP. (using the POST /realms/{realm}/identity-provider/instances/{idp-alias}/mappers endpoint)

email

{"identityProviderAlias":"azure-saml","config":{"syncMode":"INHERIT","attributes":"[]","attribute.name":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress","user.attribute":"email"},"name":"email","identityProviderMapper":"saml-user-attribute-idp-mapper"}

firstName

{"identityProviderAlias":"azure-saml","config":{"syncMode":"INHERIT","attributes":"[]","attribute.name":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname","user.attribute":"firstName"},"name":"firstName","identityProviderMapper":"saml-user-attribute-idp-mapper"}

lastName

{"identityProviderAlias":"azure-saml","config":{"syncMode":"INHERIT","attributes":"[]","are.attribute.values.regex":"","attribute.name":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname","user.attribute":"lastName"},"name":"lastName","identityProviderMapper":"saml-user-attribute-idp-mapper"}

username

{"identityProviderAlias":"azure-saml","config":{"syncMode":"INHERIT","attributes":"[]","attribute.name":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name","user.attribute":"username"},"name":"username","identityProviderMapper":"saml-user-attribute-idp-mapper"}

The confirmation screen needs some modification when we are in cloud mode:

1. User won't know about "Keycloak", so the button should say "Create Identity Provider"
2. Following successful creation, there should be no link back to the Keycloak Admin UI

Need to add group mapping step for all the wizards

TODO:

• @xgp specs
• @jeffpatzer Update the wizards to conditionally show the step based on the groupMapping feature flag
• @xgp show a prototype of how to add a group mapper to the default IdP mappers we create with the API
• @jeffpatzer add the group mapper to the default API calls when the IdP is created. enabled if the groupMapping feature flag is true

Once an IdP is successfully created on the confirmation page, provide a link "Manage {idp friendly name} in Keycloak" with the format: https://{host}/auth/admin/{realm}/console/#/realms/{realm}/identity-provider-settings/provider/{"oidc"|"saml"}/{alias}

Spec: https://docs.google.com/document/d/1lrJsPy1vI3PfVEEPOirqi2VELGw7-GbOojw0Br7WLq0/edit

customUserSearchFilter

These should show the EntityId and ACS URL. This is probably something I f-ed up when I switched how step 2 gets called.

Where possible, use the generic forms for metadata file and urls.

Filter by members of org (if applicable)

Show only username/email

Json popup from detail link

Allowed Events:

• VERIFY_EMAIL
• VERIFY_EMAIL_ERROR
• CUSTOM_REQUIRED_ACTION
• CUSTOM_REQUIRED_ACTION_ERROR
• DELETE_ACCOUNT
• DELETE_ACCOUNT_ERROR
• LOGIN
• LOGIN_ERROR
• LOGOUT
• LOGOUT_ERROR
• REGISTER
• REGISTER_ERROR
• RESET_PASSWORD
• RESET_PASSWORD_ERROR
• UPDATE_CONSENT
• UPDATE_CONSENT_ERROR
• UPDATE_EMAIL
• UPDATE_EMAIL_ERROR
• UPDATE_PASSWORD
• UPDATE_PASSWORD_ERROR
• UPDATE_PROFILE
• UPDATE_PROFILE_ERROR
• VERIFY_EMAIL
• VERIFY_EMAIL_ERROR
• VERIFY_PROFILE
• VERIFY_PROFILE_ERROR

Wizards for kcadmin (on-prem or keycloak administrator use case) is fine as-is, and doesn't need a dashboard.

For orgadmin (inter-realm organization administrator), they need a place to administer their org and setup IdPs

This is basically the new organizations section of the keycloak-admin-ui (without the ability to create new orgs) plus the ability to launch the wizards.

All instances of demo.phasetwo.io should be replaced with the actual host.

default entry point for /auth/realms/foo/wizard should be the idp selector. dashboard should still be accessible and linked, but under a different path (e.g. /auth/realms/foo/wizard/dashboard)

At the end of the confirmation step, if the creation of the IdP and Mappers in Keycloak is successful, clear the alias from state/storage.

This is useful because the user may want to create another IdP of the same type.

1. Alias of the created identity provider will be different than the submitted value. This must be taken from the Location header of the successful creation of an idp and used when creating the mappers. The Location header will be a full URL. The alias will be a UUID at the last segment, following the last /.
2. There should be a description of how to try the completed idp. Something like "Test the identity provider (this will log you out of the wizard, or you can open it in an incognito window)". This should be a normal realm login link with prompt=login and kc_idp_hint=<alias>

In the IdP selector screen, the 3 generic protocols do not use the base path in their links. E.g. from a selector screen with url

https://keycloak-xgp.ddns.net/auth/realms/demo/wizard/idp

The generic SAML protocol should link

https://keycloak-xgp.ddns.net/auth/realms/demo/wizard/idp/saml/saml

but currently links

https://keycloak-xgp.ddns.net/idp/saml/saml

Ping needs updated screenshots.

I stole these, and they're not the official ones anyway.

• G SAML should be just G, Google or Google Workspace
• ADFS should be Active Directory (because we'll support FS and DS)
• etc

Using older style of form validation and steps.