Login Algorithm

Initial Login

This walks through how login works for both an Application and a OAuth Client

Application visit

• Browser visits application.com
• Application checks to see if already logged in
• If logged in, continue
• Application creates a STATE session cookie to a random value. This cookie is an OAUTH 2.0 mechanism so that the Application will know that it originated the login protocol
• Application redirects to Keycloak realm resource passing the value of STATE, a REDIRECT_URI, and the Application's CLIENT_ID as query parameters to the redirect. (The STATE cookie is set with this redrect). Location: https://keycloak.org/realms/demo/tokens/login?state=...&redirect_uri=...&client_id=...
• The Application can also send a "scope" parameter. Scope defines what roles the Application is interested in obtaining a Token for. This will usually be for an OAuth client and not an Application

Redirect to Keycloak server

• Keycloak checks to see if the realm and client_id are valid and enabled.
• Keycloak checks to see if the client_id has permission to request a login
• Keycloak checks to see if a realm "identity cookie" is set. This cookie's value is a Json Web Signature (JWS) containing an identity token specifying the user's identity. Basically this is a cookie to determine if the Browser has already logged in. ** If the identity cookie is set, Keycloak checks to see if the client_id has a role of "KEYCLOAK_RESOURCE". If so, this means that Keycloak does not need for the user to manually authorize the login. GOTO Redirect back to Application section. If client_id is not a KEYCLOAK_RESOURCE, then the user needs to grant permission for the login manually. GOTO User OAuth Grant.
• If the identity cookie is not set, do a servlet forward to the loginForm.jsp. This page is rendered with hidden form INPUT fields containing the client_id, state, redirect_uri, and scope parameters. It is also rendered with a variable set of credential input fields i.e. password, one-time-password

Process Login

• User enters in credentials and clicks submit
• Keycloak verifies that realm, client_id, username are all valid and enabled
• Keycloak authenticates the user
• Keycloak verifies that the client_id is allowed to request a login
• Keycloak generates an AccessCode and registers it in temporary storage
• if client_id is a KEYCLOAK_RESOURCE goto Redirect back to Application section. Otherwise goto User OAuth Grant

User OAuth Grant

• Keycloak does a servlet forward to the oauthGrantForm.jsp.
• This page displays information about the client_id and describes to the user what privileges the client_id is asking for.
• Privileges are obtain from the intersection of the user's role mappings and the client_id's scope mappings and, if it was submitted, the "scope" parameter passed from the Application's initial redirect. These privileges are both realm and resource roles that will be used to generate the Skeleton Key access token.
• Page contains a hidden INPUT field with a JWS value containing the AccessCode id.
• User browser can accept or decline the grant.

Redirect back to the Application

• Keycloak redirects back to the redirect_uri sent by the Application.
• The redirect URI will also contain query parameters of: the "state" parameter sent in the initial Application redirect, and the accessCode which is contained in a JWS.
• Location: https://application.com/index.html?state=....&accessCode=&&&

Application turns Access Code into an Access Token

• Application extracts the "state" query param from the redirect URI and checks to make sure it is the same as the STATE session cookie it set earlier. This is a check to make sure the application originated the request.
• Application extracts the "accessCode" query parameter.
• Application invokes an authenticated request to Keycloak asking it to transform the accessCode to a token.
• The request is a form post containing the APplications client_id and credentials as well as the accessCode
• Keycloak authenticates the client_id and credentials.
• Keycloak generates an access token which contains user information and user/role mappings for the realm as well as all the resource role mappings. These privilges are again an intersection of user's role mappings, the client_id's scope mappings, and the "scope" parameter.
• The Access token is a derivative of the Json Web Token (JWT). Keycloak encodes this token and encapsulates it in a JWS and sends it back to the Application in the HTTP response.
• Application extracts the token and sets up the appropriate role mappings of the user that it needs to authorize access to its resources.