.. 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``):

.. code-block:: bash

 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

NOTE: If using Azure AD:
  Example Attribute mapping (this will depend on how Azure AD is configured, and the token it generates):
  attributeMappings="sub=>name;azp=>role"

  The OAuth config in Server Administration is for EDG being an OAuth client for some other service, like another EDG (publish to Explorer, etc.).  
  The relying party is the URL of the remote service.

  For API clients, go to https://github.com/TopQuadrant/api-clients for some examples written in Python. You can get an initial access token by 
  going to https://server.com/edg/oauth/getTokens and entering your client ID and secret.
  Depending on how your Azure AD is set up, you may also need a scope, which you would get from your IDP team.

  Go to App Registrations in Azure AD
  Select the EDG app
  Select Manifest
  Change:
  "accessTokenAcceptedVersion": null,
  to
  "accessTokenAcceptedVersion": 2,
  and Save
  
  This is due to a bug in Azure AD which affects token validation using third-party JWT libraries.
  Unless you set accessTokenAcceptedVersion to 2, it will default to issuing version 1 tokens, which use a different issuer ID, which causes validation to fail.

.. code-block:: xml

 <?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
* **Scope** obtained by your SSO administrator for this Application (if required)
* **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