Skip to content

Commit

Permalink
BZ-1338926: modifications for overlay of the WAR file insted of repla…
Browse files Browse the repository at this point in the history 
…cing the WAR file and also provide CLI scripts where applicable
  • Loading branch information
@rareddy
rareddy committed Jun 1, 2016
1 parent 5ca3f85 commit 2b77a8d
Show file tree
Hide file tree
Showing 3 changed files with 246 additions and 38 deletions.
128 changes: 113 additions & 15 deletions security/Kerberos_support_through_GSSAPI.adoc
View file
Expand Up @@ -6,16 +6,29 @@ Teiid supports kerberos authentication using GSSAPI for single sign-on applicati

== LocalConnection

Set the JDBC URL property _PassthroughAuthentication_ as true and use http://community.jboss.org/docs/DOC-10680[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.
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 configuring the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/7.0/how-to-set-up-sso-with-kerberos/how-to-set-up-sso-with-kerberos[SSO with Kerberos in EAP]

== Remote Connections (JDBC/ODBC)

On the server, edit the `<jboss-install>/standalone/configuration/standalone-teiid.xml` under "security-domains" subsystem add the following. Make necessary changesrelated to your configuration in terms of key tab locations, service principal etc. You need to configure two separate security domains.
== Server configuration for Remote JDBC/ODBC Connections

=== Configure one security domain to represent the identity of the server.
To support kerberos SSO on remote JDBC and ODBC connections, both client side and server side configurations need to be modified. On the server side, EAP needs to be configured with two different login modules. The below CLI script shows examples of it. Make necessary changes related to your configuration in terms of key tab locations, service principal etc.

=== Configure 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.

[source,CLI]
----
/subsystem=security/security-domain=host:add(cache-type=default)
/subsystem=security/security-domain=host/authentication=classic:add
/subsystem=security/security-domain=host/authentication=classic/login-module=Kerberos:add(code=Kerberos, flag=required,
module-options=[storeKey=true, refreshKrb5Config=true, useKeyTab=true,
principal=host/testserver@MY_REALM, keyTab=/path/to/service.keytab, doNotPrompt=true, debug=false])
reload
----

The above command will generate resulting XML in the standalone.xml file or domain.xml file.

[source,xml]
.standalone-teiid.xml
----
Expand All @@ -28,14 +41,28 @@ The first security domain authenticates the container itself to the directory se
<module-option name="keyTab" value="/path/to/service.keytab"/>
<module-option name="doNotPrompt" value="true"/>
<module-option name="debug" value="false"/>
<module-option name="refreshKrb5Config" value = "true"/>
</login-module>
</authentication>
</security-domain>
----

=== Configure a second security domain to secure the Teiid application.
=== Configure 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. Note the name of security-domain MUST match realm. The following CLI script shows example of creating the login module

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. Note the name of security-domain MUST match realm
[source,CLI]
----
/subsystem=security/security-domain=MY_REALM:add(cache-type=default)
/subsystem=security/security-domain=MY_REALM/authentication=classic:add
/subsystem=security/security-domain=MY_REALM/authentication=classic/login-module=SPNEGO:add(code=SPNEGO, flag=requisite,
module-options=[serverSecurityDomain=host,password-stacking=useFirstPass])
/subsystem=security/security-domain=MY_REALM/authentication=classic/login-module=UserRoles:add(code=SPNEGO, flag=requisite,
module-options=[usersProperties=spnego-users.properties,rolesProperties=spnego-roles.properties])
reload
----

The above CLI will result in following result XML in standalone.xml or domain.xml depending upon configuration

[source,xml]
.standalone-teiid.xml
Expand All @@ -58,26 +85,66 @@ The second security domain is used to authenticate the individual user to the Ke
----

NOTE: *"User Roles/Groups associations"* Kerberos does not assign any user roles to the authenticated subject, that is reason you need to configure a separate role mapping module to assign roles. As an example in the above, "UserRoles" login-module is added. User need to edit `"spnego-roles.properties" file and add groups
in the format of `user@MY_REALM=my-group`. Check JBoss EAP documentation, as to all the available mapping modules available.
in the format of `user@MY_REALM=my-group`. Check JBoss EAP documentation, as to all the available mapping modules that are available.

SPENGO security-domain delegates the calls relating to Kerberos to Kerberos server based on "serverSecurityDomain" property. If you would like configure the choice of authenticating using Kerberos or some other
security domain on the same JDBC/ODBC transport, then you need to supply property
additional security domain on the same JDBC/ODBC transport, then you need to supply an additional module option (this can also be viewed as fallback authentication model)

[source,xml]
----
<module-option name="usernamePasswordDomain" value="{user-name-based-auth}"/>
----

under SPENGO security-domain. The process of selecting "kerberos" or "\{user-name-based-auth}" domain for authentication is defined below.

The above configuration defined security-domains, before you can use these domains for logging into Teiid, they need to be associated with Teiid’s transport configuration or VDB configuration. Paragraphs below offer both solutions.
the resulting xml will look like below where \{user-name-based-auth} replaced with a JAAS based simple username/password login module "app-fallback"

=== Defining a "default" authentication based on Teiid Transport
[source,xml]
.standalone-teiid.xml
----
<security-domain name="MY_REALM">
<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"/>
<module-option name="usernamePasswordDomain" value="app-fallback"/>
</login-module>
<!-- Search for roles -->
<login-module code="UserRoles" flag="requisite">
<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>
<security-domain name="app-fallback" cache-type="default">
<authentication>
<login-module code="UsersRoles" flag="required">
<module-option name="usersProperties" value="file:${jboss.server.config.dir}/fallback-users.properties"/>
<module-option name="rolesProperties" value="file:${jboss.server.config.dir}/fallback-roles.properties"/>
</login-module>
</authentication>
</security-domain>
----

=== Server Transport Configuration

The above configuration defined security-domains, before you can use these domains for login into Teiid, they need to be associated with Teiid's transport configuration or VDB configuration. Paragraphs below offer both solutions.

==== Defining a "default" authentication based on Teiid Transport

User can define a "default" authentication per transport as below that can be used for all the VDBs system wide.

[source,xml]
.For JDBC:

Use below CLI commands to edit the configuration
----
/subsystem=teiid/transport=jdbc:write-attribute(name=authentication-security-domain, value=MY_REALM)
/subsystem=teiid/transport=jdbc:write-attribute(name=authentication-type, value=GSS)
----

Will result in following changes (or you can edit the standalone-teiid.xml file directly)
----
<transport name="jdbc" protocol="teiid" socket-binding="teiid-jdbc"/>
<authentication security-domain="MY_REALM" type="GSS"/>
Expand All @@ -86,9 +153,16 @@ User can define a "default" authentication per transport as below that can be us

[source,xml]
.For ODBC:

Use below CLI commands to edit the configuration
----
/subsystem=teiid/transport=odbc:write-attribute(name=authentication-security-domain, value=MY_REALM)
/subsystem=teiid/transport=odbc:write-attribute(name=authentication-type, value=GSS)
----

----
<transport name="odbc" protocol="pg" socket-binding="teiid-odbc"/>
<authentication security-domain="MY_REALM" type="GSS"/>
<authentication security-domain="MY_REALM" type="GSS"/>
</transport>
----

Expand Down Expand Up @@ -138,7 +212,9 @@ and if the user name is like "mike-simple", then that user will be subjected to

=== Required System Properties on Server

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)
JBoss EAP offers the ability to configure system properties related to connecting to Kerberos servers. Depending on the KDC, Kerberos Domain, and network configuration, the below system properties may or may not be required.

Edit the "standalone.conf" or domain.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"
Expand Down Expand Up @@ -233,4 +309,26 @@ The default OData client is configured with HTTP Basic authentication, to conver
mvn clean install
----

Then copy the WAR file from "odata-kerberos/target" directory to replace the original OData WAR file with same name. For example testing see https://developer.jboss.org/wiki/HowToImplementKerberosAuthenticationWithASimpleRESTWebApp
This will generate a new WAR file in "odata-kerberos/target" directory. Follow the below deployment direction based on your server

==== Community Teiid Server based on WildFly

Replace the <wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war" file with new WAR file, by executing a command similar to

{code}
cp teiid-web-security/odata-kerberos/target/teiid-odata-kerberos-{version}.war <wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war
{code}

==== JDV Server

If you are working with JDV 6.3 server or greater, then run the following CLI script, you may have change the below script to adopt to the correct version of the WAR and directory names where the content is located.

----
undeploy teiid-olingo-odata4.war
deploy teiid-web-security/odata-kerberos/target/teiid-odata-kerberos-{version}.war
----

or overlay the new one using CLI script like
----
deployment-overlay add --name=myOverlay --content=/WEB-INF/web.xml=teiid-web-security/odata-kerberos/src/main/webapp/WEB-INF/web.xml,/WEB-INF/jboss-web.xml=teiid-web-security/odata-kerberos/src/main/webapp/WEB-INF/jboss-web.xml,/META-INF/MANIFEST.MF=teiid-web-security/odata-kerberos/src/main/webapp/META-INF/MANIFEST.MF --deployments=teiid-olingo-odata4.war --redeploy-affected
----
79 changes: 71 additions & 8 deletions security/OAuth2_Based_Security_For_OData_Using_KeyCloak.adoc
View file
Expand Up @@ -41,23 +41,55 @@ image:images/database-client.png[database-client]
* Download Keycloak SAML adapter for EAP, and unzip over the Teiid server installation. (optional but need for another exercise)
* Edit the standalone-teiid.xml, add the following sections

In extensions add
Run the following CLI to add Keycloak specific modules to the server

[source,CLI]
----
/extension=org.keycloak.keycloak-saml-adapter-subsystem:add(module=org.keycloak.keycloak-saml-adapter-subsystem)
/extension=org.keycloak.keycloak-adapter-subsystem:add(module=org.keycloak.keycloak-adapter-subsystem)
----

above commands will result in XML in standalone.xml or domain.xml file like

[source,xml]
----
<extension module="org.keycloak.keycloak-saml-adapter-subsystem"/>
<extension module="org.keycloak.keycloak-adapter-subsystem"/>
----


Add these two subsystems any where in the file
Add these two subsystems any where in the file, use the following the CLI script

[source,CLI]
----
/subsystem=keycloak:add
/subsystem=keycloak-saml:add
----

above commands will result in XML in standalone.xml or domain.xml file like

[source,xml]
----
<subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1"/>
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
----

In security-domains add following security domains
In security-domains add following security domains using the following CLI

[souce,CLI]
----
/subsystem=security/security-domain=oauth:add(cache-type=default)
/subsystem=security/security-domain=oauth/authentication=classic:add
/subsystem=security/security-domain=oauth/authentication=classic/login-module=oauth:add(code=org.teiid.jboss.PassthroughIdentityLoginModule, flag=required, module=org.jboss.teiid)
/subsystem=security/security-domain=keycloak:add(cache-type=default)
/subsystem=security/security-domain=keycloak/authentication=classic:add
/subsystem=security/security-domain=keycloak/authentication=classic/login-module=keycloak:add(code=org.keycloak.adapters.jboss.KeycloakLoginModule, flag=required)
reload
----

above commands will result in XML in standalone.xml or domain.xml file like (you can also edit standalone.xml directly)

[source,xml]
----
Expand All @@ -76,21 +108,28 @@ In security-domains add following security domains

Under Teiid subsystem, change the "security-domain" of the "odata" transport, to

[source,CLI]
----
/subsystem=teiid/transport=odata:write-attribute(name=authentication-security-domain, value=oauth)
----

results in XML

[source,xml]
----
<transport name="odata">
<authentication security-domain="oauth"/>
</transport>
----
This finishes all the server side changes that are required to make OAuth authentication using Keycloak.

== OData Application WAR

=== Remove the default OData WAR file.

By default Teiid installation comes with OData web service WAR file configured with "HTTP Basic" authentication. Before we can replace it with new OAuth security based WAR file, this file needs to be removed. You can find this in "<eap>/modules/system/layers/dv/org/jboss/teiid/deployments" directory with "-odata4" post fix. Move this file to a different location from installation directory.
In order to use OAuth authentication, the OData WAR needs to be updated to make use of the OAuth based security domain. By default Teiid installation comes with OData web service WAR file configured with "HTTP Basic" authentication. This WAR needs to either replaced or updated.

=== Build the new OData WAR file that supports OAuth.

To build OAuth based OData WAR file, Teiid provides a template maven project, that you (the developer) need to download, and update some configuration and build the WAR file. To download the template visit URL https://github.com/teiid/teiid-web-security
To build OAuth based OData WAR file, Teiid provides a template maven project, either download or clone the project from https://github.com/teiid/teiid-web-security

The above link provides templates for creating two WAR files, one WAR file is to create Teiid's OData service with OAuth, the next is a sample "database-service" for this demo. Please note that "database-service" is to mimic the database service, that will be different in a real use-case, however the steps defined for the access will be same.

Expand All @@ -105,7 +144,31 @@ to build the WAR files running the maven command
mvn clean package
----

Copy the WAR files from the "target" directories of the build directory into the "<eap>/standalone/deployments" directory for deployment.
The above command will generate a new WAR file for deployment. Follow the below directions to deploy this new WAR file.

==== Community Teiid Server on WildFly

Replace the <wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war" file with new WAR file, by executing a command similar to

{code}
cp teiid-web-security/odata-oauth-keycloak/target/teiid-odata-oauth-keycloak-{version}.war <wildfly>/modules/system/layers/dv/org/jboss/teiid/main/deployments/teiid-olingo-odata4.war
{code}

h4. JDV Server

If you are working with JDV 6.3 server or greater, then run the following CLI script, you may have change the below script to adopt to the correct version of the WAR and directory names where the content is located.

[source,CLI]
----
undeploy teiid-olingo-odata4.war
deploy teiid-web-security/odata-oauth-keycloak/target/teiid-odata-oauth-keycloak-{version}.war
----

or overlay the new one using CLI script like
[source,CLI]
----
deployment-overlay add --name=myOverlay --content=/WEB-INF/web.xml=teiid-web-security/odata-oauth-keycloak/src/main/webapp/WEB-INF/web.xml,/WEB-INF/jboss-web.xml=teiid-web-security/odata-oauth-keycloak/src/main/webapp/WEB-INF/jboss-web.xml,/META-INF/MANIFEST.MF=teiid-web-security/odata-oauth-keycloak/src/main/webapp/META-INF/MANIFEST.MF,/WEB-INF/keycloak.json=teiid-web-security/odata-oauth-keycloak/src/main/webapp/WEB-INF/keycloak.json /WEB-INF/lib/teiid-odata-oauth-keycloak-{version}.jar=teiid-web-security/odata-oauth-keycloak/src/main/webapp/WEB-INF/lib/teiid-odata-oauth-keycloak-{version}.jar --deployments=teiid-olingo-odata4.war --redeploy-affected
----


=== Working with example VDB
Expand Down

0 comments on commit 2b77a8d

Please sign in to comment.