.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _oauth_authentication:

OAuth Authentication
--------------------

Integrating APIs with EDG using OAuth
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

TopBraid EDG supports OAuth for client APIs. Interactive users will need to use another authentication method (SAML, Basic, or Forms).
Unzip TopBraid-Auth.zip into the /lib directory of your Tomcat installation.  
E.g. /var/lib/tomcat8.5/lib

* cd /var/lib/tomcat8.5

* unzip TopBraid-Auth.zip -d lib

* If you had TopBraid SAML or OAuth from a previous version of EDG, you will need to remove the old jars
 
Add Oauth config to EDG context.xml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Edit webapps/edg/META-INF/context.xml

* If you previously had TopBraid SAML from a version of EDG prior to 6.4.2, then you need to adjust the className for SAML to  org.topbraidlive.auth.adapters.saml.tomcat.SamlValve

* Make sure the OAuth valve comes before the SAML valve

::

 <?xml version=’1.0′ encoding=’utf-8′?>

 <!– Copyright (c) 2016 TopQuadrant, Inc. All rights reserved. –>

 <Context path=”/edg”>

     <!–

       By default, Tomcat 8 tries to scan our jars for tag library

       definitions.  We don’t have any, so skipping these jars will

       improve startup and JSP compile times.

     –>

     <JarScanner>

         <JarScanFilter defaultTldScan=”false”/>

     </JarScanner>

 

     <Resources cacheMaxSize=”40960″/>

         <!–  Disable session persistence per PLAT-769 because Java8/Mars seems to have broken it.  –>

         <Manager pathname=”” />

 

   <!–

    TopBraid adapter for OAuth

   –>

   <Valve className=”org.topbraidlive.auth.adapters.oauth.tomcat.OAuthValve”

       attributeMappings=”sub=>name;appid=>name;role=>role;apptype=>role”
 
       authorizationServer=”https://oauth-idp.topquadrant.com/adfs”

       resourceURI=”https://oauth-edg.topquadrant.com/edg/”

       tokenRedirectURI=”https://oauth-edg.topquadrant.com/edg/oauth/getTokens”

       tokenRequestURI=”/oauth/getTokens”/>

 

   <!–

    TopBraid adapter for SAML

   –>

   <Valve className=”org.topbraidlive.auth.adapters.saml.tomcat.SamlValve”

            assertionConsumerService=”/saml”           attributeMappings=”http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress=>name;http://schemas.microsoft.com/2012/12/certificatecontext/field/subjectname=>role”           federationMetadata=”https://saml-idp.topquadrant.com/FederationMetadata/2007-06/FederationMetadata.xml”

            serviceProvider=”https://saml-edg.topquadrant.com/edg/saml”/>

 </Context>

Browse to your EDG webapp UI.  Navigate to Server Administration -> Server Configuration


Under the OAuth Parameters, fill in the following:

* **Token Request URL**  (eg, ADFS https://server/adfs/oauth2/token)
* **Client ID** obtained by your SSO administrator for this Application
* **Client secret** obtained by your SSO administrator for this Application

OAuth workflows
^^^^^^^^^^^^^^^

The **authorization code workflow** involves the following steps: 

The OAuth client initiates the flow when it directs the user agent of the resource owner to the authorization endpoint.
The OAuth client requests an access token from the authorization server through the token endpoint.  
This is likely where you will utilize internal scripts/apis to access EDG.

The **client credentials workflow** involves EDG-to-EDG applications, such as Publishing to Explorer, Send Projects or Federated Sparql queries.  
The system authenticates and authorizes the app (EDG) rather than a user. 
For this scenario, typical authentication schemes like username + password or social logins don’t make sense. 
Instead, uses the Client Credentials Flow in which they pass along their Client ID and Client Secret to authenticate themselves and get a token.

1. Your app authenticates with the Authorization Server using its Client ID and Client Secret (**/https://server/adfs/oauth2/token endpoint**).

2. Your Authorization Server validates the Client ID and Client Secret.

3. Your Authorization Server responds with an Access Token.

4. Your application can use the Access Token to call an API on behalf of itself.

5. The API responds with requested data.
  
The **Password grant workflow** is a way to exchange a user’s credentials for an access token. 
Because the client application has to collect the user’s password and send it to the authorization server, it is not recommended that this grant be used at all anymore.

This flow provides no mechanism for things like multifactor authentication or delegated accounts, so is quite limiting in practice.

**The latest OAuth 2.0 Security Best Current Practice disallows the password grant entirely.**

These 4 attributes are needed to fulfil OAuth authorization requirements in EDG.

* appid

* sub

* role

* apptype

 *A role of Confidential must be placed in web.xml for ADFS OAuth*

If you need to test programs against EDG, you can do so with the tool included at https://yourserver/edg/oauth/getTokens