commons/federation/README

   1 README
   2 ===============================================================================
   3 Federated AAA is deployed using several config files.  This file explains a
   4 simple scenario utilizing two servers:
   5 a) ipa.example.com
   6    - Runs the IPA Server Software
   7 b) odl.example.com
   8    - Runs the IPA Client Software
   9    - Runs an Apache proxy frontend (AuthN through mod_lookup_identity.so)
  10    - Runs ODL
  11
  12 This setup for this scenario is illustrated in Figure 1 below:
  13
  14       -----------------------
  15      | odl.example.com       |
  16      | (Fedora 20 Linux)     |
  17      |                       |
  18      |  -------------------  |
  19      | | ODL Jetty Server  | |
  20      | | (Port 8181 & 8383)| |
  21      |  -------------------  |
  22      |   ^              .    |
  23      |   .   (Apache    .    |  SSSD Requests/Responses
  24      |   .    Reverse   .    |           /
  25      |   .     Proxy)   .    |          /
  26      |   .              v    |         /
  27      |  -------------------  |        |          ------------------
  28      | | Apache            |<|..................| ipa.example.com  |
  29      | | (Port 80)         |.|.................>| (FreeIPA         |
  30      |  -------------------  |                  |   Kerberos And   |
  31      | ______________________|                  |     LDAP)        |
  32                                                  ------------------
  33 Figure 1: Shows the setup for a simple Federated AAA use case utilizing
  34 FreeIPA as an identity provider.
  35
  36
  37 These instructions were written for Fedora 20, since SSSD is unique to RHEL based
  38 distributions.  SSSD is NOT a requirement for Federation though;  you can use
  39 any supported linux flavor.  At this time, SSSD is the only Filter available
  40 with regards to capturing IdP attributes that can be used in making advanced mapping
  41 decisions (such as IdP group membership information).
  42
  43
  44
  45 1) Install FreeIPA Server on ipa.example.com.  This is achieved through running:
  46 # yum install freeipa-server bind bind-dyndb-ldap
  47 # ipa-server-intall
  48
  49
  50
  51 2) Add a FreeIPA user called testuser:
  52 $ kinit admin@EXAMPLE.COM
  53 $ ipa group-add odl_users --desc "ODL Users"
  54 $ ipa group-add odl_admin --desc "ODL Admin"
  55 $ ipa user-add testuser --first Test --last USER --email test.user@example.com
  56 $ ipa group-add-member odl_users --user testuser
  57 $ ipa group-add-member odl_admin --user testuser
  58
  59
  60
  61 3) Install FreeIPA Client on odl.example.com.  This is achieved through running:
  62 # yum install freeipa-client
  63 # ipa-client-install
  64
  65
  66
  67 4) Set up Client keytab for HTTP access on odl.example.com:
  68 # ipa-getkeytab -p HTTP/odl.brcd-sssd-tb.com@BRCD-SSSD-TB.COM \
  69     -s freeipa.brcd-sssd-tb.com -k /etc/krb5.keytab
  70 # chmod 644 /etc/krb5.keytab
  71 NOTE: The second command allows Apache to read the keytab.  There are more
  72 secure methods to support such access through SELINUX, but they are outside
  73 the scope of this tutorial.
  74
  75
  76
  77 5) Install Apache on odl.example.com.  This is achieved through running:
  78 # yum install httpd
  79
  80
  81
  82 6) Create an Apache application to broker federation between ODL and FreeIPA.
  83 Create the following file on odl.example.com:
  84
  85 [root@odl /]# cat /etc/httpd/conf.d/my_app.conf
  86 <Location "/*">
  87   AuthType Kerberos
  88   AuthName "Kerberos Login"
  89   KrbMethodNegotiate On
  90   KrbMethodK5Passwd on
  91   KrbAuthRealms EXAMPLE.COM
  92   Krb5KeyTab /etc/krb5.keytab
  93   require valid-user
  94 </Location>
  95
  96
  97 <LocationMatch "/*">
  98
  99  RequestHeader set X-SSSD-REMOTE_USER expr=%{REMOTE_USER}
 100  RequestHeader set X-SSSD-AUTH_TYPE expr=%{AUTH_TYPE}
 101  RequestHeader set X-SSSD-REMOTE_HOST expr=%{REMOTE_HOST}
 102  RequestHeader set X-SSSD-REMOTE_ADDR expr=%{REMOTE_ADDR}
 103  LookupUserAttr mail REMOTE_USER_EMAIL
 104  RequestHeader set X-SSSD-REMOTE_USER_EMAIL %{REMOTE_USER_EMAIL}e
 105  LookupUserAttr givenname REMOTE_USER_FIRSTNAME
 106  RequestHeader set X-SSSD-REMOTE_USER_FIRSTNAME %{REMOTE_USER_FIRSTNAME}e
 107  LookupUserAttr sn REMOTE_USER_LASTNAME
 108  RequestHeader set X-SSSD-REMOTE_USER_LASTNAME %{REMOTE_USER_LASTNAME}e
 109  LookupUserGroups REMOTE_USER_GROUPS ":"
 110  RequestHeader set X-SSSD-REMOTE_USER_GROUPS %{REMOTE_USER_GROUPS}e
 111 </LocationMatch>
 112
 113 ProxyPass / http://localhost:8383/
 114 ProxyPassReverse / http://localhost:8383/
 115
 116
 117
 118 7) Install the ODL distribution in the /opt folder on odl.example.com.
 119
 120
 121
 122 8) Add a federation connector to the jetty server hosting ODL on
 123 odl.example.com:
 124
 125 [user@odl distribution]$ cat etc/jetty.xml
 126 <?xml version="1.0"?>
 127 <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//
 128 DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
 129
 130 <Configure class="org.eclipse.jetty.server.Server">
 131
 132     <!-- =========================================================== -->
 133     <!-- Set connectors -->
 134     <!-- =========================================================== -->
 135     <!-- One of each type! -->
 136     <!-- =========================================================== -->
 137
 138     <!-- Use this connector for many frequently idle connections and for
 139         threadless continuations. -->
 140     <Call name="addConnector">
 141         <Arg>
 142             <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
 143                 <Set name="host">
 144                     <Property name="jetty.host" />
 145                 </Set>
 146                 <Set name="port">
 147                     <Property name="jetty.port" default="8181" />
 148                 </Set>
 149                 <Set name="maxIdleTime">300000</Set>
 150                 <Set name="Acceptors">2</Set>
 151                 <Set name="statsOn">false</Set>
 152                 <Set name="confidentialPort">8443</Set>
 153                 <Set name="lowResourcesConnections">20000</Set>
 154                 <Set name="lowResourcesMaxIdleTime">5000</Set>
 155             </New>
 156         </Arg>
 157     </Call>
 158     <!-- Trusted Authentication Federation proxy connection -->
 159     <Call name="addConnector">
 160      <Arg>
 161          <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
 162            <Set name="host">127.0.0.1</Set>
 163      <Set name="port">8383</Set>
 164      <Set name="maxIdleTime">300000</Set>
 165      <Set name="Acceptors">2</Set>
 166      <Set name="statsOn">false</Set>
 167      <Set name="confidentialPort">8445</Set>
 168      <Set name="name">federationConn</Set>
 169      <Set name="lowResourcesConnections">20000</Set>
 170      <Set name="lowResourcesMaxIdleTime">5000</Set>
 171     </New>
 172    </Arg>
 173  </Call>
 174     <!-- =========================================================== -->
 175     <!-- Configure Authentication Realms -->
 176     <!-- Realms may be configured for the entire server here, or -->
 177     <!-- they can be configured for a specific web app in a context -->
 178     <!-- configuration (see $(jetty.home)/contexts/test.xml for an -->
 179     <!-- example). -->
 180     <!-- =========================================================== -->
 181     <Call name="addBean">
 182         <Arg>
 183             <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
 184                 <Set name="name">karaf</Set>
 185                 <Set name="loginModuleName">karaf</Set>
 186                 <Set name="roleClassNames">
 187                     <Array type="java.lang.String">
 188                         <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal
 189                         </Item>
 190                     </Array>
 191                 </Set>
 192             </New>
 193         </Arg>
 194     </Call>
 195     <Call name="addBean">
 196         <Arg>
 197             <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
 198                 <Set name="name">default</Set>
 199                 <Set name="loginModuleName">karaf</Set>
 200                 <Set name="roleClassNames">
 201                     <Array type="java.lang.String">
 202                         <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal
 203                         </Item>
 204                     </Array>
 205                 </Set>
 206             </New>
 207         </Arg>
 208     </Call>
 209 </Configure>
 210
 211
 212
 213 9) Add the idp_mapping rules file on odl.example.com
 214
 215 [user@odl distribution]$ cat etc/idp_mapping_rules.json
 216 [
 217    {
 218       "mapping":{
 219          "ClientId":"1",
 220          "UserId":"1",
 221          "User":"admin",
 222          "Domain":"BRCD-SSSD-TB.COM",
 223          "roles":"$roles"
 224       },
 225       "statement_blocks":[
 226          [
 227             [
 228                "set",
 229                "$groups",
 230                [
 231
 232                ]
 233             ],
 234             [
 235                "set",
 236                "$roles",
 237                [
 238                   "admin",
 239                   "user"
 240                ]
 241             ]
 242          ]
 243       ]
 244    }
 245 ]
 246
 247 NOTE:  This is a very basic mapping example in which all federated users are
 248 mapped into the default "admin" account.
 249
 250
 251
 252 10) Start ODL and install the following features on odl.example.com:
 253 # bin/karaf
 254 karaf> feature:install odl-aaa-authn-sssd-no-cluster odl-restconf
 255
 256
 257
 258 11) Get a refresh_token on odl.example.com through Apache proxy port (80 forwarded to 8383):
 259 [user@odl distribution]$ kinit testuser
 260 [user@odl distribution]$ curl -s --negotiate -u : -X POST http://odl.example.com/oauth2/federation/
 261
 262
 263
 264 12) Obtain an access_token on odl.example.com through normal port (8181):
 265 [user@odl distribution]$ curl -s -d 'grant_type=refresh_token&refresh_token=<PUT RESULT FROM ABOVE STEP HERE>&scope=sdn' http://odl.example.com:8181/oauth2/token
 266
 267
 268
 269 13) Use the access_token to make authenticated rest calls from odl.example.com through normal port (8181):
 270 [user@odl distribution]$ curl -s -H 'Authorization: Bearer <PUT RESULT FROM ABOVE STEP HERE>' http://odl.brcd-sssd-tb.com:8181/restconf/streams/
 271