From 952dd2a50fe3c3dc099b14af23cd050048235fa3 Mon Sep 17 00:00:00 2001 From: Changmin Teng Date: Thu, 25 Jul 2019 13:39:18 -0400 Subject: [PATCH] Add design document This document details authentication indicaters and kerberos ticket policies implemented in IPA. Resolves: https://pagure.io/freeipa/issue/8001 Signed-off-by: Changmin Teng Reviewed-By: Alexander Bokovoy Reviewed-By: Simo Sorce Reviewed-By: Robbie Harwood --- doc/designs/krb-ticket-policy.md | 116 +++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 doc/designs/krb-ticket-policy.md diff --git a/doc/designs/krb-ticket-policy.md b/doc/designs/krb-ticket-policy.md new file mode 100644 index 000000000..6346d775b --- /dev/null +++ b/doc/designs/krb-ticket-policy.md @@ -0,0 +1,116 @@ +# Policies by authentication indicators + +## Overview + +Based on the pre-authentication mechanism a user used to acquire the credential, +the KDC can enforce policies such as service access control, +user authentication and ticket lifetime/reissue time policies to achieve a finer control over ticket issuance. + +## Authentication indicators + +Authentication indicators are attached by KDC to tickets issued to user and depend on +which pre-authentication mechanism used to acquire the credential. +Indicators and corresponding mechanisms are listed below: + +| Authentication indicator | Mechanism | +|:------------------------ | :------------------- | +| radius | RADIUS | +| otp | Two factor authentication (password + OTP) | +| pkinit | PKINIT | +| hardened | Hardened Password (by SPAKE or FAST) | + +Hardened password means a password authentication with either SPAKE or FAST armoring enabled. +Although it is possible to assign separate indicators to SPAKE and FAST, when both SPAKE and FAST are used, +only the indicator for SPAKE will be applied. +Since there is no practical reason to forbid the use of SPAKE while using FAST armoring, +these two are assigned the same indicator to represent a brute-force hardened form of password authentication. + +By requiring certain authentication indicators to a user, we can force a user to be authenticated with one of +the mechanisms associated with those auth indicators to obtain a ticket. +By defining a white list of authentication indicators to a service, we can allow a user to use the service +only if the user obtained a ticket with at least one of those indicators included. + +#### Note + +For unattended services (services that is a part of the IPA core system), the authentication indicator should not be set, +or it may break the whole system. Examples for such services are `HTTP/*` (for webUI and IPA API end-points), +`ldap/*` (for user data management etc.), `cifs/*` (for SMB and DCE-RPC services), +also for `host/*` on IPA masters which are used by DCE-RPC services to validate client-server communication. + +## Available policies and user interface + +### Connection policy + +Different service may need different security strength and consequently requires different pre-auth mechanism. + +e.g. must have used 2FA or OTP in order to connect to `host/securemachine@REALM` + +Services with no authentication indicator assigned will accept tickets authenticated by any mechanism. + +#### CLI Workflow: + +Administrators can specify required auth indicators for a service via `ipa service-mod` command. + +e.g. `ipa service-mod service/@REALM --auth-ind otp --auth-ind pkinit` + +#### WebUI Workflow: + +Administrators can specify required auth indicator on service settings page. +As default no auth indicator is specified which means all pre-auth mechanism is accepted. + +### Ticket lifecycle policy + +Administrators may want to define different ticket expiration and renewal values +as well as ticket flags based on the type of the authentication conducted. + +e.g. the lifetime of the OTP based ticket can be longer than for a single-factor + +Tickets without an authentication indicator will have the default lifetime / renewtime. + +#### CLI Workflow: + +Administrators can specify max life and renew for each auth indicator and global default via `ipa krbtpolicy-mod` command. + +e.g. `ipa krbtpolicy-mod --setattr otp-maxlife=604800 pkinit-maxtime=604800` + +Current `--maxlife` and `--maxrenew` options for `ipa krbtpolicy-mod` will set the default max life / renew respectively. + +After this, the output for `ipa krbtpolicy-show` will look like: + +``` +Max life: + - default: 86400 + - otp: 604800 + - pkinit: 604800 +Max renew: + - default: 604800 +``` + +#### WebUI Workflow: + +In Policy/Kerberos Ticket Policy tab, there is a table +where administrators can specify max renew and life for each supported auth indicator. + +### Ticket lifetime jitter + +Ticket lifetimes can be jittered so that renewals / re-issues do not overwhelm the KDC at a certain moment. +The feature is enabled automatically so that we can avoid triggering an LDAP query on every `AS_REQ` and `TGS_REQ`. + +## Implementation + +Kerberos policy, as krb5 presents it, consists of two interfaces: +the authentication indicator attributes and the kdcpolicy plugin. +Authentication indicator attributes allow us to make boolean access choices +(i.e. allow or deny service principal requests) on the KDC based on configuration in the Kerberos Database (KDB). +The kdcpolicy plugin is a much more powerful hook, allowing refinement of the request itself rather than +a solely boolean decision. + +Connection Policy can be implemented with authentication indicator attribute in krb5 alone, +but ticket lifecycle policy will require LDAP to store relations between authentication indicators +and lifetime information. We have global ticket lifetime and renew time setting stored as attribute +`krbmaxticketlife` and `krbmaxrenewableage` inside the `cn=$REALM,cn=kerberos,$SUFFIX` subtree, +which represents the default lifetime policy. +For each authentication indicator, there will be an attribute to store specific lifetime for that indicator, +such as `krbmaxticketlifetop`, `krbmaxrenewableagepkinit` +They are stored in the same location as default policy in LDAP. +