> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/identity-and-access-management/iam-fundamentals.md).
# IAM fundamentals
## Authenticate, authorize, and access resources
Identity and access management (IAM) ensures that the appropriate subjects - whether people, machines, or software components - gain access to the correct Spark resources at the right time.
1. First, a subject must prove their identity by demonstrating who or what they claim to be.
2. The subject is then either granted or denied access to specific Spark resources based on their permissions.
3. The user (resource owner) initiates an authentication request from the client application (Spark) to the identity provider/authorization server ([Keycloak](https://www.keycloak.org/documentation)). Spark generates a random string called the code verifier and derives a hashed version of it, known as the code challenge, using `SHA-256`. The code challenge and its `S256` method are included in the authentication request.
4. Spark redirects the user to Keycloak’s sign-in page. The request includes the code challenge, redirect URI, and other required parameters.
5. The user enters their sign-in details. If the credentials are valid, Keycloak authenticates the user. Once authorized, an authorization code is sent to Spark through the redirect URI.
6. Spark sends a token request to the identity provider/authorization server. The request includes the authorization code, the original code verifier, and the redirect URI.
7. Keycloak validates the code verifier against the previously sent code challenge. If the verification is successful, Keycloak issues an access token, an ID token, and a refresh token to Spark.
8. Spark attaches the access token to subsequent requests made to the protected resource server (Spark APIs). The resource server validates the access token and, if valid, grants access to the requested protected resources.
9. Spark processes the server's response and presents the resource to the user.
## What are authentication and authorization?
In simple terms, authentication is the process of verifying who an actor is, while authorization is the process of verifying what they have access to.
| Authentication | Authorization |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Determines whether users are who they claim to be. | Determines what users can and cannot access. |
| Challenges the user to validate credentials (for example, through passwords, answers to security questions, or facial recognition). | Verifies whether access is allowed through policies and rules. |
| Performed before authorization. | Performed after successful authentication. |
| Transmits info through an ID token. | Transmits info through an access token. |
| Governed by the OpenID Connect (OIDC) protocol. | Governed by the OAuth 2.0 framework. |
| Users are required to enter their credentials (username and password) prior to accessing Spark home page. | After users successfully authenticate, Spark determines which folders users are allowed to access. |
## Spark access control list
Spark access control list (ACL) is a security mechanism used to define which users or systems (subjects) are authorized to access specific resources (objects) and what actions they are allowed to perform on those resources.
List of rules:
* The list contains a set of rules that specify the permissions for users or groups.
* Each rule consists of:
* A subject (user or group).
* An object (typically folder).
* A set of actions (`create`, `read`, `update`, `execute`, and `delete`).
Granular permissions:
* The Spark ACLs allow fine-grained control over who can access what and how, providing flexibility and detailed security policies.
### Validate access control list rules
Spark validates ACL rules two ways:
* OAuth2: Validates actions based on the subject (`sub` claim) or group (`groups` claim) in the access token.
* API key: Validates actions based on the group assigned to the API key.
## Federation
Spark implements service provider-initiated authentication using the identity broker pattern. In service provider-initiated authentication, the user first attempts to access the service provider (Spark), which then redirects the user to the identity broker (Keycloak) for authentication, rather than the process being initiated directly by the identity provider.
The identity broker pattern, which is a part of federation, involves an intermediary (the identity broker) that sits between an identity provider and a service provider.
### Components
#### Identity provider
The identity provider is responsible for authenticating users. It stores user identities, credentials, and other relevant attributes. When a user attempts to sign in, the identity provider handles the authentication process.
#### Identity broker: Keycloak
Keycloak acts as the intermediary between the identity provider and service provider. It brokers authentication requests by receiving them from the service provider, forwarding them to the identity provider, and then processing the response. Keycloak can also manage additional identity services, such as role/attribute mapping or session management.
#### Service provider: Spark
The service provider is the application or service that requires authentication to grant users access. It relies on Keycloak to manage the authentication process. The service provider trusts Keycloak to verify user identities and provide the necessary user information (e.g. groups, permissions) after authentication.
### Authentication flow
This flow demonstrates how Spark's IAM architecture operates using the identity broker pattern, where Spark initiates the authentication process, Keycloak brokers the requests to the identity provider, and Spark grants access based on the tokens provided. This ensures secure and streamlined federation.
1. The user accesses Spark. Since the application is protected, the user must be authenticated.
2. Spark, recognizing that the user is not authenticated, redirects the user's browser to Keycloak, the identity broker. This redirection initiates the authentication process using the authorization code flow with PKCE.
3. Keycloak forwards the authentication request to the configured identity provider. The user is prompted to authenticate with the identity provider. This typically involves entering credentials (e.g., username and password).
4. Upon successful authentication, the identity provider sends a response back to Keycloak.
* If OpenID Connect (OIDC) is used: The response will include an ID token and possibly an access token.
* If SAML is used: The response will include a SAML assertion.
5. Keycloak processes the authentication response and issues its own ID token, access token, and refresh token. These tokens are stored in the user's browser local storage.
6. Keycloak then redirects the user back to Spark with the necessary authentication information. Spark receives the tokens from Keycloak via the browser and verifies them. Once the tokens are validated, the application grants access to the user.
