Project: Athenz (Provisioning / Key Management)
File: principal_authentication.md

-- * * * For a principal (either user or service) to authenticate himself/herself in Athenz, the server must have the appropriate authentication authority implementation configured. Athenz has implementation of several authorities that support variety of authentication methods. The system administrator may decide to configure and use one of the provided authorities or implement a completely new one to satisfy their requirements. -- The job of the Authority is authenticate a specific request and, if valid, generate and return an object representing the authenticated Principal. The Authority interface is defined in the following file: The system administrator can configure a list of authorities for supporting principal authentication. During startup, the server will call the `initialize()` method for all configured authorities. If the authority requires access to any of the service public keys registered within Athenz, then it needs to implement the `AuthorityKeyStore` interface as well and provide an implementation of the `setKeyStore()` method. The server implements the `KeyStore` interface and will automatically call the `setKeyStore()` method to pass its implementation to the authority. When processing a request the server goes through the list of authorities in their configured order and processes until it receives a successful principal object. As soon as a successful response is received from the authenticate method, the server will stop processing other authorities in the list and continue with the authorization check. If no authority returns an authenticated principal, the server returns 401 Unauthenticated response to the calling client. The Authority defines if the authentication details are based on a header or certificate: `getCredSource()`. If the returned value is `HEADER` then the Athenz server will retrieve the header, identified by the value returned by the `getHeader()` method, that the authority is looking for and if a value is present, it will call the `authenticate()` method to see if the request contains valid credentials or not. The returned principal object contains the Authority object that was used for authentication. This allows the Athenz servers, if necessary, to decide if further checks and/or restrictions are necessary. Both ZMS and ZTS Servers expect to find the list of authority classes in their respective system properties: ZMS: athenz.zms.authority_classes ZTS: athenz.zts.authority_classes The value of the property must be a comma separated (no spaces) list of authority class names. For example, ``` -Dathenz.zms.authority_classes=com.yahoo.athenz.auth.impl.PrincipalAuthority,com.yahoo.athenz.auth.impl.UserAuthority ``` If you're installing and running Athenz services using the binary packages provided, you can configure the list of authorities in the conf/zmsserver/zms.properties or conf/ztsserver/zts.properties files for ZMS and ZTS servers respectively: ``` athenz.zms.authority_classes=com.yahoo.athenz.auth.impl.PrincipalAuthority,com.yahoo.athenz.auth.impl.UserAuthority athenz.zts.authority_classes=com.yahoo.athenz.auth.impl.PrincipalAuthority,com.yahoo.athenz.auth.impl.UserAuthority ``` -- Here is the list of Athenz provided authorities with brief description of each one. -- Class:

This authority uses the Unix pam `login` profile to authenticate users. The user that the ZMS process runs as must have read access to the `/etc/shadow` file. There are two options available: Run the process as root using sudo. This is only recommended for a local development installation. Create a special Unix group that has read access to the `/etc/shadow` file and set the user that the ZMS process will be running as a member of that group. User Authority is typically not allowed to carry out any authorized operation. It is required that the user first must obtain an X509 certificate for his/her identity and use that certificate to carry out the authorized request. -- Class: com.yahoo.athenz.auth.impl.PrincipalAuthority This authority uses Athenz generated NTokens. It accepts NTokens, parses to extract the signature and the private key details that were used to sign this token: domain, service, and key id. Then it requests the corresponding public key and verifies the signature. Principal Authority is one of primary authorities in Athenz. It is used to validate NTokens that were issued by ZTS and service tokens generated by SIA Providers. By default, when authenticating an NToken, the authority validates that the IP address in the NToken matches to the IP address of the request. This provides extra security that changes to domain data are not carried out by NTokens that possible have been stolen. Class: com.yahoo.athenz.auth.impl.KerberosAuthority This authority supports environments with Kerberos servers. This authority expects to find the Kerberos Ticket in the `Authorization` header. There are several system properties that must be set for proper initialization of this authority: `athenz.auth.kerberos.service_principal` - Kerberos service principal `athenz.auth.kerberos.keytab_location` - Kerberos keytab location `athenz.auth.kerberos.jaascfgsection` - JAAS configuration section. If using a jaas.conf file then that path is specified by the system property `java.security.auth.login.config` For full details check out the implementation of the Kerberos Authority: Class: com.yahoo.athenz.auth.impl.CertificateAuthority The certificate authority expects that the server has been configured with a truststore that only includes the CA cert that it tasked with issuing principal certificates. The Authority only looks at the CommonName component of the certificate and expects it to include the service name in the {domain}.{service} format. For example: ``` Certificate Subject DN: c=US;o=Some Athenz Company;cn=sports.fantasy ``` The authenticated principal in this case is service `fantasy` in domain `sports`. Class: com.yahoo.athenz.auth.impl.LDAPAuthority Lightweight Directory Access Protocol (LDAP) authority uses the bind operation to authenticate users. The authentication mechanism used is `simple` where plain text username and passwords are used. The `hostname`, `port number` and `base DN` property of the LDAP server needs to be provided. An example of base dn is: ``` LDAP Server Base DN: dc=example,dc=com ```