Keycloak SSO¶
Note
Game Warden authenticates users through Keycloak, ensuring only your customers have access to your application. You then have the freedom to control user authorization, using access controls that you build into your application.
Keycloak is the Identity and Access Management (IAM) solution that allows you to securely access the Game Warden Web App, your products, and other Game Warden-hosted solutions using a single set of login credentials.
Game Warden's Keycloak integrates with the Platform One Single Sign-on (P1 SSO). Both function similarly, allowing secure access to the same applications. This article content provides insight into Game Warden's Keycloak and how you can use it to control access to your applications.
Establishing Your Keycloak Account¶
By performing the steps in the New User Account article, you automatically establish your own Keycloak account.
About Keycloak¶
Keycloak uses three primary components that work in unison as background processes to confirm user validity:
Authentication Service (Istio’s Authservice software)
Verifies Game Warden users based on their login credentials. For additional information, read Authservice Documentation and Architecture Overview.
JSON Web Token (JWT)
Shares information between devices, such as a client and a server. During this process, JWT performs authorization to ensure the user requesting application access is the same user who provided login credentials during the authentication process. JWT receives the user profile from Authservice and, using public keys, verifies the login credentials to determine if the JWT sender (user) is safe for application access.
Example: the client (browser/user) sends a username and password along with profile information gathered by Authservice to the server which, in turn, creates a JWT and assigns a secret only known to the JWT. At this point, the JWT contains user profile information, login credentials, and a secret. The server sends the JWT to the client. The client returns the JWT to the server. The server verifies that the JWT has not been altered, signally that the user requesting application access is the same user who provided login credentials. If valid, the server grants application access. Since JWT stores all user information on the client, the user has application access.
A JWT has three parts, each comprising specific data:
Header – Sends data to and from the client. The header includes the token type, JWT, for example. It also includes the algorithm in use, such as “alg”: “HS256” (which works in conjunction with the Signature to verify users and is used to encode/decode data), and a token expiration date.
Payload – Includes user information and any designated groups/roles. For example, the payload might include the sub or subject, such as the user ID. It also might include the username.
Signature – Reviews header and payload data before it is returned to the server to ensure the client has not altered this data. Verifies the JWT sender (user) and, if valid, grants application access.
Istio Sidecar
Manages network traffic and enforces policies, functioning as a traffic cop of sorts. The policies enable Istio Sidecar to allow or deny application access to users.
Below is a workflow diagram of the Keycloak SSO process:
Note
The diagram above references a Common Access Card (CAC), External Certification Authority (ECA), and a Federal Personal Identity Verification (PIV) card. These cards provide access to Game Warden-hosted IL4+ applications in the Staging (STG) and Production (PRD) environments. For additional information, read Government Access Cards.
Controlling Access via Keycloak Groups¶
A Keycloak Group, while optional, is a collection of users who share common attributes or roles. For example, you might create a group and designate each user with IL4+ access along with roles whose attributes permit read-only actions. Another group, such as IT Administrators, might have access to Impact Level 2 (IL2) with roles whose attributes permit them to add and remove users.
Game Warden's customer environments are Keycloak-protected. To restrict specific groups from accessing certain environments, you can create custom Istio policies. The Game Warden team will apply these policies.
Common methods to manage Keycloak Groups
- The Game Warden team can provide unrestricted access to your Production (PRD) environment via Keycloak such that users with IL4 credentials may access this endpoint.
- For non-Production environments, you might prefer to limit access. You may do so by creating Istio policies that the Game Warden team will apply. We can apply policies for the PRD environment as well.
- The Game Warden team can manually add users to environments that do not have existing Istio policies. As customers, you must provide our team with the user names and email addresses. When these users attempt to access these environments, our team will need to add them to the Keycloak Group. This is the least preferred method, as certain constraints would make this effort time-consuming if manually performed for all users and approximately 100+ applications.
Group hierarchies enable you to assign groups and roles with quickness, efficiency, and ease. Most applications within Keycloak use a standard group hierarchy.
Below is a high-level example of a group hierarchy:
Accessing Keycloak Groups¶
You can gain access to Keycloak groups via Dynamic Provisioning, Manual Provisioning, or Keycloak Registration.
Dynamic Provisioning¶
- Our team automatically adds users with .gov or .mil email addresses to groups with access to IL2, IL4, and IL5.
- Users with customer domain email addresses must contact our team before completing Keycloak registration. Our team updates our dynamic provisioning scripts such that script execution automatically adds these email addresses to the appropriate groups.
- The Game Warden team adds end users from third parties with other company domain email addresses to dynamic provisioning. In this case, you must send these email addresses, in advance, for us to include in our dynamic provisioning scripts.
Manual Provisioning¶
-
Game Warden uses Istio in concert with Keycloak to employ authorization policies. Customer configured, customized Authorization Policies can be used to limit access to endpoints using Gamewarden’s keycloak groups, giving you options for granular access control.
-
For example, an authorization policy could limit access to your developers in a DEV environment or you could permit only Airforce users to access your endpoint.
-
After you draft your policy, provide it to your Customer Ops representative and we will apply it to your cluster.
Example Policy
# This policy ensures that Identities without this string
# "/Customers/<customer_name>/<some group>" in their JWTs
# group claim are not allowed to reach pods and services
# labeled with "app.kubernetes.io/name": foo
apiVersion: "security.istio.io/v1beta1"
kind: "AuthorizationPolicy"
metadata:
name: "pgadmin-allow-mmt-developer-group"
namespace: "mmt"
spec:
selector:
matchLabels:
"app.kubernetes.io/name": foo
action: DENY
rules:
- to:
- operation:
hosts: [foo.il2.afwerx.dso.mil"]
when:
- key: request.auth.claims[groups]
notValues: ["/Customers/<customer_name>/<some group>"]
# Auth Pols are granular and flexible in nature instead
# of blocking for a whole host you could just block for a path
# instead by changing the rule object to some like this
- to:
- operation:
paths: ["/admin"]
when:
- key: request.auth.claims[groups]
notValues: ["/Customers/<customer_name>/admins"]
# This would have the effect of only allowing users with the admin group
# in the claim from being able to hit the admin endpoints within the application
- Reach out to your Customer Operations representative or submit a Support Ticket for any questions you may have.
Keycloak Registration¶
Completing the steps of the New User Account article automatically adds you to Game Warden's Keycloak group.
Application Integration¶
Keycloak authenticates applications deployed to the Game Warden platform.
When integrating your applications with Game Warden, two primary actions occur:
- Authentication (AuthN)
- Keycloak authenticates user requests.
- Authorization (AuthZ)
- Keycloak determines the level of access a user should receive.
- If a user registers with a DoD-supported Public Key Infrastructure (PKI) method, our Keycloak SSO automatically assigns the appropriate Impact Level groups and roles.
After the Authservice validates a request, it sets the Authorization: Bearer header (which contains JWT authentication) in the request that it passes into the application code. This data is in JWT format, can be parsed with any JWT library, and contains the user's Keycloak profile.
Developers can identify data within encoded and decoded JWTs by viewing each of its three parts: Header, Payload, and Signature.
Sample Decoded JWT with Payload Data
Sample Encoded JWT
An encoded JWT displays the Header, Payload, and Signature. A period separates each.
Note
As the Game Warden product evolves and the customer base increases, our team will update documentation to ensure the inclusion of any additional application integration requirements.
JWT Authorization¶
JWT authorization exists for each user request. Application teams might leverage this tool solely for authentication. They also might manage authorization internally relative to application code, if they require role or group-based authentication. For example, you can store users’ roles/groups in the application database and use the authenticated ID of users in the JWT to compare to those groups using the application code.
You must manage your application user roles and permissions.
At IL4+, you must use our Keycloak SSO. You can perform any additional authorization within your application; however, using our Keycloak SSO is a requirement. The Game Warden team performs this authorization on your behalf via the ATO. Our Keycloak SSO authorization satisfies two requirements:
- Does the user have a valid CAC/ECA/PIV, which allows access to DoD data?
- Is the user part of your defined user group?
Our team supports your option to integrate with Keycloak SSO directly using other security methods such as Open Authorization (OAuth2) or Security Assertion Markup Language (SAML). However, when implementing, OAuth2 or SAML must be the only login method your application provides. We ensure this behavior with automated testing. If you do not use OAuth2 or SAML, you can integrate with KeyCloak SSO directly.
GUIDANCE? Contact your Customer Operations lead via Slack.