For the Book: Authentication, write the Introduction. Draft in the Content section in this issue

Context and intentions

• In 1.3 it is still possible to postpone provisioning?=> Answer = yes
• AI: [Docs] New intro, explain the user journey.

Overview:  The customer is not ready to go into production yet.  They are still planning out what environments they need, so they are testing out different auth configurations/providers to determine what suits their needs 

Audience: RHDH administrator.

• Journey step 1: No auth

1. Journey step 2 - Enabling an authentication provider
   (based on: S1.2 - Authentication but no Ingestion)
   Description: The RHDH Admin sets up an auth provider for further evaluation but they do not want to ingest users and groups yet.
   Steps (for each section):
   1. Login failed; caused by Error: Sign in failed: users/groups have not been ingested into the catalog. Please refer to the authentication provider docs for more information on how to ingest users/groups to the catalog with the appropriate entity provider.
   2.  
2. Configure your auth provider.  Do not configure the ingester
3. Verify Login fails with the message: 
4. Set dangerouslyAllowSignInWithoutUserInCatalog to true.
5. Verify Login now works but no User Entities are in the Catalog

1. Journey step 3 - Provisioning the {product} user catalog
   (based on S2.1 - Authentication with Ingestion using a default resolver and S2.2 - Authentication with Ingestion using non-default resolvers, and S2.3 - Authentication with Ingestion of Users and Nested Groups)
   Description: The RHDH admin sets up a prod/test environment and provision the user catalog, including nested groups. They want to set up access based on the groups from their existing IdP which they are currently using to authenticate into their other services.  They want to set up groups based on business needs e.g team-test, team-dev, team-ops, etc.  For a more scalable solution, having a group entity sync'd from the IdP makes it easier to control access for individuals.  If someone leaves or moves teams, it should be a matter of updating the groups and the permissions should take into effect.  Otherwise, it'll be a manual effort to remove/reorg individuals in the permission policy file.
   Prerequisites: You have configured the respective auth provider.
   Steps (for each section):
   1. msgraph for Azure.  
   2. Keycloak Plugin for RHSSO
   3. Github Integration plugin for Github
2. Configure the ingester that corresponds to the Auth provider:
3. Use the default sign-in resolver that’s associated with the provider e.g. for OIDC, it’s emailLocalPartMatchingUserEntityName
4. Set dangerouslyAllowSignInWithoutUserInCatalog to false.  
5. Adjust the the User/Group entity sync refresh time
6. Verify the UserEntity is created according to the specifications of the resolver
7. Verify the UserEntities and Groups are created with the correct relationships in RHDH

1. Journey step 4 - Updating the RHDH user catalog
   Overview: RHDH has been running for several months now, but there’s been changes in the organization that may require removal of users, groups and/or re-organization of teams

User/Group entities are created via a one way sync from the IdP to RHDH. Therefore, deletion from the UI have unintended consequences.

You can configure the delay after which the user catagog receives an update.

Procedure:

Adjust the the User/Group entity sync refresh time

List UserEntities and Groups 

Content

Authentication and authorization are two separate processes in RHDH:

1. Authentication is defining the user identity, and passing on this information to RHDH.
2. Authorization is defining what actions an authenticated identity can perform in RHDH. See link:{authorizations-book-url}[Authorizations].

To start exploring RHDH features, don’t worry about authentication and authorization: after the default installation, you can authenticate with the Guest user, and use all the application features.

The authentication system in RHDH is handled by authentication providers.

RHDH supports multiple authentication providers, such as:

• Red Hat Single-Sign On (RHSSO)
• GitHub
• Microsoft Azure

You can configure RHDH to have multiple authentication providers, with only one provider being actively used at any given time for logging in users.

You might use additional authentication providers to add more information to the user identity.

To identify users in RHDH, you need to:

1. Authenticate users with your external authorization provider. It requires enabling an authentication provider.
2. Get, store, and update additional information about the users, such as group or team ownership, with the intention to use this information to define authorization. It requires provisioning users and groups in the RHDH catalog.

To explore the authentication system, and use RHDH without authorization system, you can enable your authentication provider without provisioning the RHDH user catalog.

RHDH uses a one way synchronization system to provision user and groups from your authentication system to the RHDH user catalog. Therefore, deleting users and groups by using RHDH Web UI or REST API might have unintended consequences.

Additional resources

• See link:{authorizations-book-url}[Authorizations].