... |
h2. Remote Connections |
On the server, edit the {{<jboss\-install>/standalone/configuration/standalone\-teiid.xml}} under teiid subsystem on "transport" definition, add the following: |
On the server, edit the {{<jboss\-install>/standalone/configuration/standalone\-teiid.xml}} under "security-domains" subsystem add the following. Make necessary changes related to your configuration in terms of key tab locations, service principal etc. You need to configure two separate security domains. |
|
For JDBC: |
h3.Configure one security domain to represent the identity of the server. The first security domain authenticates the container itself to the directory service. It needs to use a login module which accepts some type of static login mechanism, because a real user is not involved. This example uses a static principal and references a keytab file which contains the credential. |
|
{code:XML|title="standalone-teiid.xml"} <security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="principal" value="host/testserver@MY_REALM"/> <module-option name="keyTab" value="/home/username/service.keytab"/> <module-option name="doNotPrompt" value="true"/> <module-option name="debug" value="false"/> </login-module> </authentication> </security-domain> |
{code} |
h3. Configure a second security domain to secure the Teiid application. The second security domain is used to authenticate the individual user to the Kerberos server. You need at least one login module to authenticate the user, and another to search for the roles to apply to the user. The following XML code shows an example SPNEGO security domain. It includes an authorization module to map roles to individual users. You can also use a module which searches for the roles on the authentication server itself. {code:XML|title="standalone-teiid.xml"} <security-domain name="teiid-spengo" cache-type="default"> <authentication> <!-- Check the username and password --> <login-module code="SPNEGO" flag="requisite"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="serverSecurityDomain" value="host"/> </login-module> <!-- Search for roles --> <login-module code="UserRoles" flag="required"> <module-option name="password-stacking" value="useFirstPass" /> <module-option name="usersProperties" value="spnego-users.properties" /> <module-option name="rolesProperties" value="spnego-roles.properties" /> </login-module> </authentication> </security-domain> {code} SPENGO security-domain delegates the calls relating to Kerberos to Kerberos server based on "serverSecurityDomain" property set. If you also want to support a additional security-domain like "UsernamePassword" in case, if you would like configure the choice of logging into Kerberos or other, you can supply property {code:XML} <module-option name="usernamePasswordDomain" value="userNameBasedAuth"/> {code} under SPENGO security-domain. Selecting which domain "kerberos" or "userNameBasedAuth" to for Teiid's authentication is defined below. The above configured the domains, however usage of these domains in Teiid for authentication purposes can be configured in two different ways. h3. Defining a "default" authentication based on transport User can define a "default" authentication per transport as below that can be used for all the VDBs system wide. For JDBC: {code:XML} |
<transport name="jdbc" protocol="teiid" socket-binding="teiid-jdbc"/> |
<authentication security-domain="teiid-security" krb5-domain="krb5-domain"/> |
<authentication security-domain="teiid-spengo" type="GSS"/> |
</transport> {code} |
... |
For ODBC: |
{code:XML} |
<transport name="odbc" protocol="pg" socket-binding="teiid-odbc"/> |
<authentication security-domain="teiid-security" krb5-domain="krb5-domain"/> |
<authentication security-domain="teiid-spengo" type="GSS"/> |
</transport> {code} |
{tip:title="What is the value of Type"} The "type" attribute above defined the type of authentication that needs to be enforced on the configured security domain on a given transport. The allowed values for type are * USERPASSWORD - only allow user name/password based authentications * GSS - only allow GSS API based authrntication. (kerberos) * ANY - Allow both GSS or USERPASSWORD based. To use this option your "teiid-spengo" *must* define the "usernamePasswordDomain" module-option as defined above. |
|
Now we need to define a security domain context for kerberos with the name mentioned \(kbr5\-domain)in above. Since kerberos authorization cannot define authorization roles, we'll define them using another login context. Given below is a sample configuration to define roles using a UserRolesLoginModule. |
Not defining "type" value defaults to "ANY" value. Unless, you support both GSS and UserPassword based domains, it is recommended to set value to this attribute. {tip} |
{note} |
This configuration replaces the default Teiid login configuration, and you should change the principal and key tab locations accordingly to your runtime environment. |
{note} |
{code:XML|title=standalone-teiid.xml} <!--login module that negotiates the login conext for kerberos --> <subsystem xmlns="urn:jboss:domain:security:1.1"> <security-domains> <security-domain name="krb5-domain" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="storeKey">true</module-option> <module-option name="useKeyTab">true</module-option> <module-option name="principal">demo@EXAMPLE.COM</module-option> <module-option name="keyTab">path/to/krb5.keytab</module-option> <module-option name="doNotPrompt">true</module-option> <module-option name="debug">false</module-option> </login-module> </authentication> </security-domain> <!-- teiid's default security domain, replace this with your own if needs to be any other JAAS domain --> <security-domain name="teiid-security" cache-type="default"> <authentication> <login-module code="org.teiid.jboss.SimpleLoginModule" flag="required" module="org.jboss.teiid"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> <login-module code="org.jboss.security.auth.spi.CertRolesLoginModule" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="rolesProperties" value="${jboss.server.config.dir}/teiid-security-roles.properties"/> </login-module> </authentication> </security-domain> </security-domains> </subsystem> {code} |
h3. Defining VDB based authentication You can add a VDB property in the vdb.xml file as below |
|
{tip:title="verbose error"} With above setup you will see error like |
{code:XML} <property name="security-domain" value="teiid-spengo/USERPASSWORD" /> |
{code} |
PBOX000246: The JSSE security domain other is not valid. All authentication using this login module will fail! {code} This is captured at [https://issues.jboss.org/browse/WFLY-777] and is erroneous and can be safely ignored. {tip} |
|
the value is in the form "security-domain/type", and all the "type" values from above apply here also in enforcing the authentication requirements. Type value is optional, however in case if it is not specified, it is treated as "ANY" value as default. Using this model you can configure, different security-domains for different VDBS, they are no longer dependent upon what is enforced by a underlying transport. |
Edit the "standalone.conf" file in the "$\{jboss\-as}/bin" directory and add the following JVM options \(changing the realm and KDC settings according to your environment) |
... |
{code} |
This finishes the configuration on the server side, restart the server and make sure that there were no errors during start up. |
|
... |
In you client VM the JAAS configuration for kerberos authentication needs to be written. A sample configuration file \(client.conf) is show below |
{code:title="client.conf"} |
Client { com.sun.security.auth.module.Krb5LoginModule required |
... |
useKeyTab=true keyTab="/path/to/krb5.keytab" |
doNotPrompt=false doNotPrompt=true |
debug=false principal="demo@EXAMPLE.COM"; |
... |
{code} |
before you do make sure you have configured the "keytab". You can check this website for making sure you have access to KDC server and instructions on how to create keytabs especially on windows environments [http://spnego.sourceforge.net], for Redhat Linux see [https://access.redhat.com/site/solutions/208173] |
Add the following JVM options to your client's startup script - change Realm and KDC settings according to your environment {code} |
-Djava.security.krb5.conf=/path/to/krb5.conf (on Linux /etc/krb5.conf) |
-Djava.security.krb5.realm=EXAMPLE.COM -Djava.security.auth.login.config=/path/to/client.conf |
-Djava.security.krb5.kdc=kerberos.example.com |
-Djavax.security.auth.useSubjectCredsOnly=false -Dsun.security.krb5.debug=false |
-Djava.security.auth.login.config=/path/to/client.conf |
{code} |
or if you want to control the KDC and REALM system wide use below instead |
or |
{code} |
-Djava.security.krb5.conf=/path/to/krb5.conf (on Linux /etc/krb5.conf) |
-Djava.security.auth.login.config=/path/to/client.conf -Djava.security.krb5.realm=EXAMPLE.COM |
-Djava.security.krb5.kdc=kerberos.example.com |
-Djavax.security.auth.useSubjectCredsOnly=false -Dsun.security.krb5.debug=false |
-Djava.security.auth.login.config=/path/to/client.conf |
{code} |
Add the following additional URL connection properties to Teiid JDBC connection string along with URL etc. Note that when configured with Kerberos you do not need to provide "user" or "password" properties. The user name is derived automatically from GSS login context. |
{code} |
authenticationType=KRB5;jaasName=Client;kerberosServicePrincipleName=demo@EXAMPLE.COM jaasName=Client; |
{code} h3. ODBC Client Configuration |
TBD |
No additional configuration is needed as part of this, except that your workstation where the ODBC DSN is created is already authenticated using GSS API against Active Directory or Enterprise directory server. See this website [http://spnego.sourceforge.net] on instructions as to how to verify your system is logging into enterprise domain. Contact your company's operations team if you have any questions. |
|
h3. Supplying the Role information |
h2. How to choose authentication type when type is set to "ANY" As mentioned above the "teiid-spengo" security domain can be configured with both a Kerberos domain, and also UserPassword domain. The authentication type can be influenced by "user" connection property in JDBC and ODBC. If "user" name is defined as "GSS" it notified the Teiid server, that user prefers to login using the GSS, if "user" name is anything else it indicates that user prefers to use UsernamePassword Domain. Note that the authentication type must be "empty" or "ANY" in transport's type attribute Or on VDB, the "security-domain" property it must be ANY or not specified. |
|
There are two layers of security in this setup, one Kerberoes and next is security to access Teiid itself. The above configuration builds on top of each other so that you have single SSO based solution. |
The below table defines the behavior of the system with different settings |
|
There is no need to provide the separate user name and password for establishing a JDBC connection, it will authenticate using kerberoes with and provided username to negotiate a service token with kerberoes server and grant the JDBC connection. In order to supply the role information for the user defined on "kerberosServicePrincipleName" property, edit the "$\{jboss.server.config.dir\}/teiid-security-roles.properties" file and add appropriate role information. |
||Transport Type||VDB Type||User Name||Authentication Enforced||Reason|| |<blank>|<blank>|Fred|USERPASSWORD|Because this most common type| |ANY|<blank>|Fred|USERPASSWORD|Because name pattern does not match to GSS, and Server allows both| |ANY|<blank>|GSS|GSS|Because name pattern matches to GSS, and Server allows both| |USERPASSWORD|<blank>|GSS|USERPASSWORD|Fails, because Server enforcing USERPASSWORD, user name may not match one to one defined| |*|GSS|GSS or Fred|GSS|Server enforces GSS| |*|ANY|Fred|USERPASSWORD|Because name pattern does not match to GSS, and Server allows both| |*|ANY|GSS|GSS|Because name pattern matches to GSS, and Server allows both| |*|USERPASSWORD|GSS|USERPASSWORD|Fails, because Server enforcing USERPASSWORD, user name may not match one to one defined| |*|GSS|GSS or Fred|GSS|Server enforces GSS| |
|
You can also choose to replace "teiid-security" domain configuration with another JAAS based security domain, however in that case a user name and password need to be set on the JDBC connection URL, which will be used to authenticate with newly configured JAAS domain. |
\* When VDB based security-domain is defined, the transport based settings are no longer consulted. |
Teiid supports kerberos authentication using GSSAPI for single sign-on applications. This service ticket negotiation based authentication is supported through remote JDBC/ODBC drivers and LocalConnections. Client configuration is different for each client type.
Set the JDBC URL property PassthroughAuthentication as true and use JBoss Negotiation for authentication of your web-application with kerberos. When the web application authenticates with the provided kerberos token, the same subject authenticated will be used in Teiid. For details about configuration, check the JBoss Negotiation documentation.
On the server, edit the <jboss-install>/standalone/configuration/standalone-teiid.xml under "security-domains" subsystem add the following. Make necessary changes related to your configuration in terms of key tab locations, service principal etc. You need to configure two separate security domains.
The first security domain authenticates the container itself to the directory service. It needs to use a login module which accepts some type of static login mechanism, because a real user is not involved. This example uses a static principal and references a keytab file which contains the credential.
<security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="principal" value="host/testserver@MY_REALM"/> <module-option name="keyTab" value="/home/username/service.keytab"/> <module-option name="doNotPrompt" value="true"/> <module-option name="debug" value="false"/> </login-module> </authentication> </security-domain>
The second security domain is used to authenticate the individual user to the Kerberos server. You need at least one login module to authenticate the user, and another to search for the roles to apply to the user. The following XML code shows an example SPNEGO security domain. It includes an authorization module to map roles to individual users. You can also use a module which searches for the roles on the authentication server itself.
<security-domain name="teiid-spengo" cache-type="default"> <authentication> <!-- Check the username and password --> <login-module code="SPNEGO" flag="requisite"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="serverSecurityDomain" value="host"/> </login-module> <!-- Search for roles --> <login-module code="UserRoles" flag="required"> <module-option name="password-stacking" value="useFirstPass" /> <module-option name="usersProperties" value="spnego-users.properties" /> <module-option name="rolesProperties" value="spnego-roles.properties" /> </login-module> </authentication> </security-domain>
SPENGO security-domain delegates the calls relating to Kerberos to Kerberos server based on "serverSecurityDomain" property set. If you also want to support a additional security-domain like "UsernamePassword" in case, if you would like configure the choice of logging into Kerberos or other, you can supply property
<module-option name="usernamePasswordDomain" value="userNameBasedAuth"/>
under SPENGO security-domain. Selecting which domain "kerberos" or "userNameBasedAuth" to for Teiid's authentication is defined below.
The above configured the domains, however usage of these domains in Teiid for authentication purposes can be configured in two different ways.
User can define a "default" authentication per transport as below that can be used for all the VDBs system wide.
For JDBC:
<transport name="jdbc" protocol="teiid" socket-binding="teiid-jdbc"/> <authentication security-domain="teiid-spengo" type="GSS"/> </transport>
For ODBC:
<transport name="odbc" protocol="pg" socket-binding="teiid-odbc"/> <authentication security-domain="teiid-spengo" type="GSS"/> </transport>
"What is the value of Type" The "type" attribute above defined the type of authentication that needs to be enforced on the configured security domain on a given transport. The allowed values for type are
Not defining "type" value defaults to "ANY" value. Unless, you support both GSS and UserPassword based domains, it is recommended to set value to this attribute. |
This configuration replaces the default Teiid login configuration, and you should change the principal and key tab locations accordingly to your runtime environment. |
You can add a VDB property in the vdb.xml file as below
<property name="security-domain" value="teiid-spengo/USERPASSWORD" />
the value is in the form "security-domain/type", and all the "type" values from above apply here also in enforcing the authentication requirements. Type value is optional, however in case if it is not specified, it is treated as "ANY" value as default. Using this model you can configure, different security-domains for different VDBS, they are no longer dependent upon what is enforced by a underlying transport.
Edit the "standalone.conf" file in the "${jboss-as}/bin" directory and add the following JVM options (changing the realm and KDC settings according to your environment)
JAVA_OPTS = "$JAVA_OPTS -Djava.security.krb5.realm=EXAMPLE.COM -Djava.security.krb5.kdc=kerberos.example.com -Djavax.security.auth.useSubjectCredsOnly=false"
This finishes the configuration on the server side, restart the server and make sure that there were no errors during start up.
In you client VM the JAAS configuration for kerberos authentication needs to be written. A sample configuration file (client.conf) is show below
Client { com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true storeKey=true useKeyTab=true keyTab="/path/to/krb5.keytab" doNotPrompt=true debug=false principal="demo@EXAMPLE.COM"; };
before you do make sure you have configured the "keytab". You can check this website for making sure you have access to KDC server and instructions on how to create keytabs especially on windows environments http://spnego.sourceforge.net, for Redhat Linux see https://access.redhat.com/site/solutions/208173
Add the following JVM options to your client's startup script - change Realm and KDC settings according to your environment
-Djava.security.krb5.conf=/path/to/krb5.conf (on Linux /etc/krb5.conf) -Djava.security.auth.login.config=/path/to/client.conf -Djavax.security.auth.useSubjectCredsOnly=false -Dsun.security.krb5.debug=false
or
-Djava.security.krb5.realm=EXAMPLE.COM -Djava.security.krb5.kdc=kerberos.example.com -Djavax.security.auth.useSubjectCredsOnly=false -Dsun.security.krb5.debug=false -Djava.security.auth.login.config=/path/to/client.conf
Add the following additional URL connection properties to Teiid JDBC connection string along with URL etc. Note that when configured with Kerberos you do not need to provide "user" or "password" properties. The user name is derived automatically from GSS login context.
jaasName=Client;
No additional configuration is needed as part of this, except that your workstation where the ODBC DSN is created is already authenticated using GSS API against Active Directory or Enterprise directory server. See this website http://spnego.sourceforge.net on instructions as to how to verify your system is logging into enterprise domain. Contact your company's operations team if you have any questions.
As mentioned above the "teiid-spengo" security domain can be configured with both a Kerberos domain, and also UserPassword domain. The authentication type can be influenced by "user" connection property in JDBC and ODBC. If "user" name is defined as "GSS" it notified the Teiid server, that user prefers to login using the GSS, if "user" name is anything else it indicates that user prefers to use UsernamePassword Domain. Note that the authentication type must be "empty" or "ANY" in transport's type attribute Or on VDB, the "security-domain" property it must be ANY or not specified.
The below table defines the behavior of the system with different settings
Transport Type | VDB Type | User Name | Authentication Enforced | Reason |
---|---|---|---|---|
<blank> | <blank> | Fred | USERPASSWORD | Because this most common type |
ANY | <blank> | Fred | USERPASSWORD | Because name pattern does not match to GSS, and Server allows both |
ANY | <blank> | GSS | GSS | Because name pattern matches to GSS, and Server allows both |
USERPASSWORD | <blank> | GSS | USERPASSWORD | Fails, because Server enforcing USERPASSWORD, user name may not match one to one defined |
* | GSS | GSS or Fred | GSS | Server enforces GSS |
* | ANY | Fred | USERPASSWORD | Because name pattern does not match to GSS, and Server allows both |
* | ANY | GSS | GSS | Because name pattern matches to GSS, and Server allows both |
* | USERPASSWORD | GSS | USERPASSWORD | Fails, because Server enforcing USERPASSWORD, user name may not match one to one defined |
* | GSS | GSS or Fred | GSS | Server enforces GSS |
* When VDB based security-domain is defined, the transport based settings are no longer consulted.