The following chapters describe the configuration of OAuth. This service can be used to authenticate at a Fabasoft Folio Web Service.
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.
To be able to log in using an OAuth access token, the Fabasoft Folio Web Service must be configured to require SAML authentication.
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:
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:
The following settings are available for the configuration of OAuth:
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.
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.
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
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
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
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());
}
}
}