
=== Core concepts and terms

Consider these core concepts and terms before attempting to use {project_name} to secure your web applications and REST services.

users::
  Users are entities that are able to log into your system.  They can have attributes associated with themselves like email,
  username, address, phone number, and birthday.  They can be assigned group membership and have specific roles assigned to them.
authentication::
  The process of identifying and validating a user.
authorization::
  The process of granting access to a user.
credentials::
  Credentials are pieces of data that {project_name} uses to verify the identity of a user.  Some examples are passwords,
  one-time-passwords, digital certificates, or even fingerprints.
roles::
  Roles identify a type or category of user.  `Admin`, `user`, `manager`, and `employee` are all typical roles that may exist
  in an organization.  Applications often assign access and permissions to specific roles rather than individual users as dealing
  with users can be too fine-grained and hard to manage.
user role mapping::
  A user role mapping defines a mapping between a role and a user.  A user can be associated with zero or more roles.  This
  role mapping information can be encapsulated into tokens and assertions so that applications can decide access permissions on
  various resources they manage.
composite roles::
  A composite role is a role that can be associated with other roles.  For example a `superuser` composite role could be associated with the
  `sales-admin` and `order-entry-admin` roles.  If a user is mapped to the `superuser` role they also inherit the `sales-admin` and `order-entry-admin` roles.
groups::
  Groups manage groups of users.  Attributes can be defined for a group.  You can map roles to a group as well.  Users that become members of a group
  inherit the attributes and role mappings that group defines.
realms::
  A realm manages a set of users, credentials, roles, and groups.  A user belongs to and logs into a realm.  Realms are isolated from one another
  and can only manage and authenticate the users that they control.
clients::
  Clients are entities that can request {project_name} to authenticate a user.  Most often, clients are applications and services that
  want to use {project_name} to secure themselves and provide a single sign-on solution.  Clients can also be entities that just want to request
  identity information or an access token so that they can securely invoke other services on the network that are secured by {project_name}.
client adapters::
  Client adapters are plugins that you install into your application environment to be able to communicate and be secured by {project_name}.  {project_name}
  has a number of adapters for different platforms that you can download.  There are also third-party adapters you can get for environments that we don't cover.
consent::
  Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process.
  After a user provides their credentials, {project_name} will pop up a screen identifying the client requesting a login and what identity
  information is requested of the user.  User can decide whether or not to grant the request.
client scopes::
  When a client is registered, you must define protocol mappers and role scope mappings for that client. It is often useful to store
  a client scope, to make creating new clients easier by sharing some common settings. This is also useful for requesting some
  claims or roles to be conditionally based on the value of `scope` parameter. {project_name} provides the concept of a client scope for this.
client role::
  Clients can define roles that are specific to them.  This is basically a role namespace dedicated to the client.
identity token::
  A token that provides identity information about the user.  Part of the OpenID Connect specification.
access token::
  A token that can be provided as part of an HTTP request that grants access to the service being invoked on.  This is part of
  the OpenID Connect and OAuth 2.0 specification.
assertion::
  Information about a user.  This usually pertains to an XML blob that is included in a SAML authentication response that
  provided identity metadata about an authenticated user.
service account::
  Each client has a built-in service account which allows it to obtain an access token.
direct grant::
  A way for a client to obtain an access token on behalf of a user via a REST invocation.
protocol mappers::
  For each client you can tailor what claims and assertions are stored in the OIDC token or SAML assertion.  You do this per client by creating and configuring
  protocol mappers.
session::
  When a user logs in, a session is created to manage the login session.  A session contains information like when the user logged in and what
  applications have participated within single sign-on during that session.  Both admins and users can view session information.
user federation provider::
  {project_name} can store and manage users.  Often, companies already have LDAP or Active Directory services that store user and credential
  information.  You can point {project_name} to validate credentials from those external stores and pull in identity information.
identity provider::
  An identity provider (IDP) is a service that can authenticate a user.  {project_name} is an IDP.
identity provider federation::
  {project_name} can be configured to delegate authentication to one or more IDPs.  Social login via
  Facebook or Google is an example of identity provider federation.  You can also hook {project_name} to delegate
  authentication to any other OpenID Connect or SAML 2.0 IDP.
identity provider mappers::
  When doing IDP federation you can map incoming tokens and assertions to user and session attributes.  This helps you propagate identity information from the external IDP
  to your client requesting authentication.
required actions::
  Required actions are actions a user must perform during the authentication process.  A user will not be able to complete the authentication process until these actions
  are complete.  For example, an admin may schedule users to reset their passwords every month.  An `update password` required action would be set for all these
  users.
authentication flows::
  Authentication flows are work flows a user must perform when interacting with certain aspects of the system.  A login flow can define
  what credential types are required.  A registration flow defines what profile information a user must enter and whether something like reCAPTCHA
  must be used to filter out bots.  Credential reset flow defines what actions a user must do before they can reset their password.
events::
  Events are audit streams that admins can view and hook into.
themes::
  Every screen provided by {project_name} is backed by a theme.  Themes define HTML templates and stylesheets which you can override as needed.
