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

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.

<?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 the Server Configuration Parameters Admin Page.

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