2024 Update Rollup 1

Authentication With OAuthPermanent link for this heading

The following chapters describe the configuration of OAuth. This service can be used to authenticate at a Fabasoft Folio Web Service.

GeneralPermanent link for this heading

OAuth is an open standard for authentication and access control. It allows users to share their private resources stored on one site with another site without having to hand out their credentials, typically supplying username and password tokens instead. Further information can be found on the web (http://oauth.net/: new window and http://oauth.net/2/: new window).

The implementation is based on OAuth 2.0 Draft 25 and Bearer Tokens Draft 18. The grant type “authorization code” is supported. Refresh tokens are not supported.

PreparationPermanent link for this heading

Web Service ConfigurationPermanent link for this heading

To be able to log in using an OAuth access token, the Fabasoft Folio Web Service must be configured to require SAML authentication.

Client ConfigurationPermanent link for this heading

An OAuth client requires a client identifier and a client secret for being able to request an OAuth access token. These variables can be allocated by creating an OAuth Client object (FSCOWS@1.1001:OAuthClient). An OAuth client has the following properties:

  • Name
    Defines a name that represents the client and its use cases for accessing the service via OAuth.
  • Client ID
    Represents the OAuth Client ID to use for OAuth requests.
  • Client Secret
    Represents the OAuth Client Secret to use for OAuth token requests.
  • Redirect URI
    Defines an optional redirect URI. If specified, the service will redirect to the URI in the context of authorization requests. If an authorization request specifies a redirect URI and a redirect URI is configured, the values must match.
  • OAuth Token Expires After
    Defines the expiration time of an OAuth access token issued for the client. If not defined, the expiration time specified in the domain configuration is used.
  • Allowed Web Services
    Defines a list of web services (FSCOWS@1.1001:WebServiceDefinition) that can be accessed via OAuth for this client. The scope specified in an OAuth authorization request must be contained in this list, otherwise the request will be denied. If not specified, OAuth tokens cannot be requested or used for this client. If valid tokens exist at this point, these tokens cannot be used for as long as the scope is missing from this list.

Access ConfigurationPermanent link for this heading

In the scope argument of an OAuth authorization request, clients can specify the desired access for a token. In case of Fabasoft Folio, a scope is represented by a list of full references of Web Service Definition (FSCOWS@1.1001:WebServiceDefinition) instances separated by a space character.

A Web Service Definition contains a list of actions that represent web service implementations (SOAP, JSON, Friendly URLs).

The following well-known web service instances are available for use with OAuth:

  • WebDAV (FSCOWS@1.1001:WebDAVWebService)
  • CMIS (FSCCMIS@1.1001:CMISWebService)
  • The following properties are available:
  • Multilingual Name
    A list of language-specific names presented to the user during access confirmation. In the context of OAuth, the multilingual name represents a permission that can be granted as part of the confirmation process.
  • Web Service Actions
    This property defines a list of actions (COOSYSTEM@1.1:Action) of web service implementations (SOAP, JSON, FriendlyURL). In the context of OAuth, the list defines which web service implementations can be accessed via OAuth, if the OAuth scope contains the full reference of the Web Service Definition. An OAuth client can only specify Web Service Definitions that are explicitly allowed in the OAuth Client instance.

ConfigurationPermanent link for this heading

The following settings are available for the configuration of OAuth:

  1. Open the Web Service Configuration, which is referenced in the Current Domain or Domain Type.
  2. Click the „OAuth” tab.
    The following properties are available:
    • OAuth Code Expires After Minutes
      Defines the expiration time of an OAuth authorization code in minutes (default: 10).
    • OAuth Token Expires After
      Defines the expiration time of an OAuth access token (default: “1 Day”).
    • Trusted OAuth Clients
      Defines a list of trusted OAuth clients. In case of a trusted client, the access confirmation user interface is skipped.

OAuth can only be enabled as an alternative authentication method in combination with SAML. To enable OAuth, the environment variable FSCVEXT_ALTAUTHMETH must be set for a host or web service.

Client ExamplePermanent link for this heading

This sample is based on Apache Amber, an OAuth2 client for Java, and should serve as a guide for getting started with the Fabasoft Folio OAuth implementation.

ConfigurationPermanent link for this heading

Before being able to execute the sample, static variables must be initialized as follows:

private static final String BASEURI = "https://<hostname>/fsc";

Specify the Fabasoft Folio base URL comprised of URL scheme, hostname, port and virtual directory.

private static final String CLIENTID = "<client-id>";

Specify the value of the property Client ID of an OAuth Client (FSCOWS@1.1001:OAuthClient) instance in the target domain.

private static final String CLIENTSECRET = "<client-secret>";

Specify the value of the property Client Secret of an OAuth Client (FSCOWS@1.1001:OAuthClient) instance in the target domain.

private static final String REDIRECTURI = "http://localhost/";

The redirect URI can remain unchanged for the sample. The redirect URI specifies, which URL the Fabasoft Folio OAuth implementation redirects to if the user confirms requested access permissions.

private static final String SCOPE = "<wsdef-full-reference>";

Specify the full reference of one or more Web Service Definition (FSCOWS@1.1001:WebServiceDefinition) objects, separated by the space character.

// Object address of a NOTE@1.1:NoteObject instance
private static final String TESTOBJECT = "<noteobject-address>";

Specify the object address of a Note Object (NOTE@1.1:NoteObject) in your domain

CompilationPermanent link for this heading

The sample depends on Apache Amber (http://incubator.apache.org/amber/: new window) as well as Codehaus Jettison (http://jettison.codehaus.org/: new window).

Download the latest snapshot of oauth2-common.jar and oauth2-client.jar from

https://repository.apache.org/content/groups/snapshots/org/apache/amber/oauth2-common/: new window

https://repository.apache.org/content/groups/snapshots/org/apache/amber/oauth2-client: new window

Download the latest binary distribution containing jettision.jar from http://jettison.codehaus.org/: new window.

Create a file OAuthTest.java, copy the contents of into the file, and compile the sample as follows:

Windows

set CLASSPATH=.;jettison.jar;oauth2-common.jar;oauth2-client-jar
javac OAuthTest.java

Linux

export CLASSPATH=.:jettison.jar:oauth2-common.jar:oauth2-client-jar
javac OAuthTest.java

ExecutionPermanent link for this heading

Execute the sample as follows:

Windows

set CLASSPATH=.;jettison.jar;oauth2-common.jar;oauth2-client-jar

java OAuthTest

Linux

export CLASSPATH=.:jettison.jar:oauth2-common.jar:oauth2-client-jar

java OAuthTest

The sample prints an URL that must be accessed via a GUI browser. The query argument code of the URL the browser redirects to contains the OAuth authorization code. Copy the value and paste it into the console prompt. The application then requests a token based on the authorization code and attempts to access the configured note object using the token:

Confirm access via the following URL:

http://localhost/fsc/oauth2/authorize?scope=TEST%401.506%3AReadContents&redirect_uri=http%3A%2F%2Flocalhost%2F&client_id=COO.1.506.3.1001983&response_type=code

Enter 'code' query argument value: COO.1.506.1.15-0211a5cfcf00314daa3e0bdc73865257
Token:      COO.1.506.1.15-cc1166d3fb7ddc409e8b0d0d1dad88e9
Expiration: 86400 seconds
Data:

Network Working Group                                     E. Hammer, Ed.
Internet-Draft
Obsoletes: 5849 (if approved)                                D. Recordon
Intended status: Standards Track                                Facebook
Expires: November 2, 2012                                       D. Hardt
                                                               Microsoft
                                                             May 1, 2012

                 The OAuth 2.0 Authorization Framework
                         draft-ietf-oauth-v2-25

CodePermanent link for this heading

OAuthTest.java:

import java.io.*;
import java.net.*;
import org.apache.amber.oauth2.client.*;
import org.apache.amber.oauth2.common.exception.*;
import org.apache.amber.oauth2.common.message.types.*;
import org.apache.amber.oauth2.client.request.*;
import org.apache.amber.oauth2.client.response.*;

public class OAuthTest
{
  // Fabasoft Folio base URL (e.g. http://localhost/fsc)
  private static final String BASEURI = "https://<hostname>/fsc";
  // Client ID as defined by FSCOWS@1.1001:OAuthClient instance
  private static final String CLIENTID = "<client-id>";
  // Client secret as defined by FSCOWS@1.1001:OAuthClient instance
  private static final String CLIENTSECRET = "<client-secret>";
  // Arbitrary redirect URI required for the protocol
  private static final String REDIRECTURI = "http://localhost/";
  // Full reference of an FSCOWS@1.1001:WebServiceDefinition instance
  // containing the action FSCASP@1.1001:ReadContentFriendlyURL
  private static final String SCOPE = "<wsdef-full-reference>";
  // Object address of a NOTE@1.1:NoteObject instance
  private static final String TESTOBJECT = "<noteobject-address>";

  public static void main(String[] args) throws IOException, OAuthSystemException
  {
    try {

      //
      // Build authorization code request
      //
      OAuthClientRequest request = OAuthClientRequest
        .authorizationLocation(BASEURI + "/oauth2/authorize")
        .setClientId(CLIENTID)
        .setScope(SCOPE)
        .setRedirectURI(REDIRECTURI)
        .setResponseType("code")
        .buildQueryMessage();

      System.out.println("Confirm access via the following URL:");
      System.out.println();
      System.out.println(request.getLocationUri());
      System.out.println();
      System.out.print("Enter 'code' query argument value: ");
      BufferedReader reader =
        new BufferedReader(new InputStreamReader(System.in));
      String code = reader.readLine();

      //
      // Build and send token request
      //
      request = OAuthClientRequest
        .tokenLocation(BASEURI + "/oauth2/token")
        .setGrantType(GrantType.AUTHORIZATION_CODE)
        .setClientId(CLIENTID)
        .setClientSecret(CLIENTSECRET)
        .setRedirectURI(REDIRECTURI)
        .setCode(code)
        .buildBodyMessage();

      OAuthClient client = new OAuthClient(new URLConnectionClient());
      OAuthAccessTokenResponse response = client.accessToken(request);
      String accesstoken = response.getAccessToken();
      System.out.println("Token:      " + accesstoken);
      System.out.println("Expiration: " + response.getExpiresIn() + " seconds");

      //
      // Access resource
      //
      URL url = new URL(BASEURI + "/read/" + TESTOBJECT);
      URLConnection conn = url.openConnection();
      conn.setRequestProperty("Authorization", "Bearer " + accesstoken);
      System.out.println("Data:");
      System.out.println();
      reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));
      String line = reader.readLine();
      while (line != null) {
        System.out.println(line);
        line = reader.readLine();
      }
    }
    catch (OAuthProblemException e)
    {
      System.out.println("OAuth error:             " + e.getError());
      System.out.println("OAuth error description: " + e.getDescription());
    }
  }
}

Download PDF

Download PDF