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