{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"This topic is about the use of Kerberos strictly on the IdP server. If you're looking for the end-to-end use of Kerberos with a web browser using the SPNEGO GSS-API mechanism (often referred to as desktop authentication), see the ","type":"text"},{"text":"SPNEGOAuthnConfiguration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631622"}}]},{"text":" topic.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Current File(s):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"conf/authn/password-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":", ","type":"text"},{"text":"conf/authn/krb5-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":" (V4.0), ","type":"text"},{"text":"conf/authn/authn.properties","type":"text","marks":[{"type":"em"}]},{"text":" (V4.1+)","type":"text"},{"type":"hardBreak"},{"text":"Format:","type":"text","marks":[{"type":"strong"}]},{"text":" Native Spring, Properties, Kerberos","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"0cd342a5-22f4-4f4f-a4f9-f1d361a232d9"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"10beba35-ee34-4066-842f-bc363c82ed49"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"},{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"This CredentialValidator back-end for the ","type":"text"},{"text":"password authentication","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631611"}}]},{"text":" login flow uses the Kerberos library built into Java for password-based authentication instead of using the JAAS module that traditionally wraps those calls.","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"The primary advantage of this approach is the capability to prevent a rogue KDC from spoofing responses by validating its knowledge of a service principal key configured locally in a keytab file, which is a standard practice for safe use of Kerberos in server-side scenarios. It is ","type":"text"},{"text":"STRONGLY","type":"text","marks":[{"type":"strong"}]},{"text":" urged that this feature be used when possible.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"General Configuration","type":"text"}]},{"type":"expand","attrs":{"title":"V4.0"},"content":[{"type":"paragraph","content":[{"text":"Configuring Kerberos as a back-end in the simplest fashion relies on beans defined via an import in ","type":"text"},{"text":"authn/password-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Import in authn/password-authn-config.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"A few beans are defined in this file to globally configure this back-end by setting some Kerberos-related options. With V4, these beans are chiefly used for backward compatibility, and as default settings that can be overridden on specific instances of beans inheriting from ","type":"text"},{"text":"shibboleth.KerberosValidator","type":"text","marks":[{"type":"strong"}]},{"text":" defined in ","type":"text"},{"text":"authn/password-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":" in the ","type":"text"},{"text":"shibboleth.authn.Password.Validators","type":"text","marks":[{"type":"strong"}]},{"text":" bean.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the simple case of a single back-end:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Defining use of Kerberos in password-authn-config.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\t\n \n","type":"text"}]}]},{"type":"expand","attrs":{"title":"V4.1+"},"content":[{"type":"paragraph","content":[{"text":"Configuring Kerberos as a back-end relies on beans internally that are configured using ","type":"text"},{"text":"authn/authn.properties","type":"text","marks":[{"type":"em"}]},{"text":" along with the OS-supplied Kerberos configuration.","type":"text"}]},{"type":"paragraph","content":[{"text":"Older releases included an ","type":"text"},{"text":"authn/krb5-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":" file; this remains supported but is no longer required or provided.","type":"text"}]},{"type":"paragraph","content":[{"text":"Adding additional beans may be needed in very advanced cases where a higher degree of control is required, and you are welcome to place them within ","type":"text"},{"text":"authn/password-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"In the simple case of a single back-end:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Defining use of Kerberos in password-authn-config.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\t\n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"If desired, it's possible to directly configure the various settings within the validator bean instead of or in addition to relying on the defaults. Refer to the ","type":"text"},{"text":"KerberosCredentialValidator","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.impl.KerberosCredentialValidator"}}]},{"text":" javadoc for a complete summary, along with the example below.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Kerberos Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The actual Kerberos library configuration is managed in a conf or ini file that can be placed in a number of different locations. On non-Windows servers, using a system-wide configuration in ","type":"text"},{"text":"/etc/krb5.conf","type":"text","marks":[{"type":"em"}]},{"text":" is generally advised. It's possible to have Java-specific configurations and/or provide the path to a configuration using a system property. Refer to the Java ","type":"text"},{"text":"documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.oracle.com/en/java/javase/11/security/kerberos-requirements.html"}}]},{"text":" for details.","type":"text"}]},{"type":"paragraph","content":[{"text":"It is of critical concern that you consider the impact of foreign realm usage.","type":"text","marks":[{"type":"strong"}]},{"text":" Operating the Java Kerberos client in its default configuration without including a service principal is inherently dangerous because Java defaults to locating foreign realm KDCs via DNS. Therefore you MUST do one of the following to prevent inadvertent access by principals in realms other than your own:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Set ","type":"text"},{"text":"dns_lookup_kdc = false","type":"text","marks":[{"type":"strong"}]},{"text":" in the ","type":"text"},{"text":"[libdefaults]","type":"text","marks":[{"type":"strong"}]},{"text":" section of the Kerberos configuration file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Supply a service principal and keytab to ensure that the IdP shares a key with the KDC that responds to it.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"It is also possible to implement rules within the IdP controlling the permissible usernames, but these are workarounds at best and one of the above is more strongly recommended.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Chaining Validators","type":"text"}]},{"type":"paragraph","content":[{"text":"One complication of chaining Kerberos KDCs together is that the overall realm configuration is global to Java, so you can't just have separate krb5.conf files in each case. That means you have to manipulate the user's input to ensure that the values will be explicitly realm-qualified.","type":"text"}]},{"type":"paragraph","content":[{"text":"Under the assumption that principal names in the two realms are unique (without which, things get much more complex and dangerous obviously), something like this would allow chaining of the two. The example considers two realms, \"FOO.EXAMPLE.ORG\" and \"BAR.EXAMPLE.ORG\", and the transforms applied strip the username if it's entered in the form of an email address before appending the realm.","type":"text"}]},{"type":"expand","attrs":{"title":"password-authn-config.xml"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\t\n \n \n\n\n\n \n \t\n \t\n \t\n \t\n \n\n\n\n \n \t\n \t\n \t\n \t\n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference","type":"text"}]},{"type":"expand","attrs":{"title":"Beans (V4.0)"},"content":[{"type":"paragraph","content":[{"text":"The beans defined in ","type":"text"},{"text":"authn/krb5-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":" follow. These are defaults that can be overridden per-validator in whole or in part.","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","localId":"4d3a1174-3f61-4183-847c-352e74a628e1"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Bean ID","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[704.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.authn.Krb5.RefreshConfig","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"False","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[704.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to reload the underlying Kerberos configuration (generally in /etc/krb5.conf) on every login attempt","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.authn.Krb5.PreserveTicket","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"Boolean","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"False","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[704.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to preserve the resulting Kerberos TGT in the Java Subject's private credential set","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.authn.Krb5.ServicePrincipal","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"String","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[704.0]},"content":[{"type":"paragraph","content":[{"text":"Name of a service principal to use to verify the KDC supplying the TGT, by requesting and verifying a service ticket issued for it","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"shibboleth.authn.Krb5.Keytab","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph","content":[{"text":"Path","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[72.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[704.0]},"content":[{"type":"paragraph","content":[{"text":"Path to a keytab file containing keys belonging to the service principal defined above","type":"text"}]}]}]}]}]},{"type":"expand","attrs":{"title":"Properties (V4.1+)"},"content":[{"type":"paragraph","content":[{"text":"The following properties are usable in ","type":"text"},{"text":"authn/authn.properties","type":"text","marks":[{"type":"em"}]},{"text":" to control Kerberos use. These are defaults that can be overridden per-validator in whole or in part.","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","localId":"1d82ffd2-5433-4531-a792-4b2705f2eb45"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[255.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[67.0]},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[880.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[255.0]},"content":[{"type":"paragraph","content":[{"text":"idp.authn.Krb5.refreshConfig","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[67.0]},"content":[{"type":"paragraph","content":[{"text":"false","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[880.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to reload the underlying Kerberos configuration (generally in /etc/krb5.conf) on every login attempt","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[255.0]},"content":[{"type":"paragraph","content":[{"text":"idp.authn.Krb5.preserveTicket","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[67.0]},"content":[{"type":"paragraph","content":[{"text":"false","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[880.0]},"content":[{"type":"paragraph","content":[{"text":"Whether to preserve the resulting Kerberos TGT in the Java Subject's private credential set","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[255.0]},"content":[{"type":"paragraph","content":[{"text":"idp.authn.Krb5.servicePrincipal","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[67.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[880.0]},"content":[{"type":"paragraph","content":[{"text":"Name of a service principal to use to verify the KDC supplying the TGT, by requesting and verifying a service ticket issued for it","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[255.0]},"content":[{"type":"paragraph","content":[{"text":"idp.authn.Krb5.keytab","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[67.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[880.0]},"content":[{"type":"paragraph","content":[{"text":"Path to a keytab file containing keys belonging to the service principal defined above","type":"text"}]}]}]}]}]},{"type":"paragraph"}],"version":1}

Browser not supported