Procedure 2.1. Task

1. Obtain the GWT Client Provider library jar file and add it to the classpath of your project. If you are using Maven, you can achieve this by adding the Sonatype OSS repository and GWT Client Provider dependency to your pom.xml as follows in the example below. If you are using any other build tool, download the appropriate jar file from the Maven repository and add it as a library.

   <project>
       ...
       <repositories>
           <repository>
               <id>oss-repo</id>
               <name>OSS repository</name>
               <url>https://oss.sonatype.org/content/groups/public/</url>
           </repository>
       </repositories>
       ...
       <dependencies>
           <dependency>
               <groupId>org.jboss.pressgang.belay</groupId>
               <artifactId>gwt-client-provider</artifactId>
               <version>${belay.version}</version>
           </dependency>
       </dependencies>
       ...
   </project>
   

2. Add the library to your GWT application's Module.gwt.xml file using the following code:

   <inherits name="org.jboss.pressgang.belay.oauth2.gwt.OAuth2GwtClientProvider"/>

Procedure 2.2. Task

1. Declare and instantiate an OAuthHandler in your application using the following code:

   import org.jboss.pressgang.belay.oauth2.gwt.client.OAuthHandler;
   
   public class App implements EntryPoint {         
   
       private static final OAuthHandler AUTH_HANDLER = OAuthHandler.get();
   
   }
   

2. Using this handler, you can authorize an end-user, using an OpenID Provider. To do this, you require:

   • The auth URL of your OAuth2 Authorization Server implementation.

   • The client ID of your application, as defined by your OAuth2 Authorization Server implementation.

   • The URL or domain name of the OpenID provider to use for end-user authentication.

   • The names of the access scopes to request.

   Where the auth URL is https://mydomain:443/MyAuthServer/rest/auth/login, the OpenID provider domain is gmail.com, the client ID is appClientId and the scope required is PERFORM_USER_MANAGEMENT, the code will be as follows:

   
   final AuthorizationRequest request = RequestUtil.openIdAuthorizationRequest("https://mydomain:443
     /MyAuthServer/rest/auth/authorize", "appClientId", 
     "gmail.com").withScopes("PERFORM_USER_MANAGEMENT");
   AUTH_HANDLER.sendAuthRequest(request, new Callback<String, Throwable>() {
   
       @Override
       public void onSuccess(String result) {
       	// Do something
       }
   
       @Override
       public void onFailure(Throwable caught) {
           // Handle error
       }
   });
   

Procedure 2.3. Task

• To make a request to a Resource Server, you need to construct an OAuthRequest. The constructor parameters required are:

  • The REST method type.

  • The URL to request.

  Optionally, the request headers, timeout and/or request data can be set, the same as with a GWT RequestBuilder.

  Here is an example of a basic GET request:

  
  AUTH_HANDLER.sendRequest(new OAuthRequest(RequestBuilder.GET, "https://mydomain:443
    /MyResourceServer/rest/resource"), new RequestCallback() {
               
      @Override
      public void onResponseReceived(Request request, Response response) {
      	// Do something
      }
  
      @Override
      public void onError(Request request, Throwable exception) {
          // Handle error
      }
  });
  

Procedure 2.4. Task

• To make a request for user information, for example, use the following code as a template:

  
  AUTH_HANDLER.sendRequest(new OAuthRequest(RequestBuilder.GET, "https://mydomain:443
    /MyAuthServer/rest/auth/user/queryUser"), new RequestCallback() {
  
      @Override
      public void onResponseReceived(Request request, Response response) {
      	// Do something
      }
   
      @Override
      public void onError(Request request, Throwable exception) {
          // Handle error
      }
  });
  

Procedure 2.5. Task

• The RequestUtil class includes helper methods to assist with the creation of an appropriate OAuthRequest for end-user identity association, and the designation of an end-user's primary identity. Here is an example of adding a second identity to an end-user. The second identity must be authorized before the associate request can be made, and the authorization from the first identity must be recorded, as both identities need to be authorized by the Authorization Server in order to be associated. AUTH_HANDLER.getLastTokenResult() is used to retrieve the access token of the first identity before the second identity is authorized (as a forced request) and overwrites this information (as the client application is the same for both). If either identity were already associated with other identities, the entire identity group would end up associated with the same end-user. The parameters used are:

  • The HTTP method of the association endpoint.

  • The association URL.

  • The application's unique client ID.

  • A current access token for the end-user to associate.

  • Whether or not the new identity should be the resulting user's primary identity.

  
  final String originalToken = AUTH_HANDLER.getLastTokenResult();
  final AuthorizationRequest authRequest = 
    RequestUtil.openIdAuthorizationRequest("https://mydomain:443
    /MyAuthServer/rest/auth/authorize", "appClientId", "http://username.myopenid.com")
                                                      .withScopes(PERFORM_USER_MANAGEMENT)
                                                      .forceNewRequest(true);
  AUTH_HANDLER.sendAuthRequest(authRequest, new Callback<String, Throwable>() {
      @Override
      public void onSuccess(String result) {
          final OAuthRequest request = RequestUtil.associateIdentitiesRequest(
            RequestBuilder.POST, 
            "https://mydomain:443/MyAuthServer/rest/auth/user/associate", 
            "appClientId",
            originalToken, 
            false);
          AUTH_HANDLER.sendRequest(request, new RequestCallback() {
  
              @Override
              public void onResponseReceived(Request request, Response response) {
                  // Do something
              }
  
              @Override
              public void onError(Request request, Throwable exception) {
                  // Handle error
              }
          });
      }
  
      @Override
      public void onFailure(Throwable caught) {
          // Handle error
      }
  });
  

Procedure 2.6. Task

• The RequestUtil class includes a helper method to create an OAuthRequest to change an end-user's primary identity. The end-user must be authorized before this request is made, and the identity specified must be associated with the end-user. Here is an example. The parameters used are:

  • The HTTP method of the endpoint to make an identity primary.

  • The URL of the endpoint to make an identity primary.

  • The identifier to make primary.

  
  AUTH_HANDLER.sendRequest(RequestUtil.makeIdentityPrimaryRequest(RequestBuilder.GET, 
    "https://mydomain:443/MyAuthServer/rest/auth/user/makeIdentityPrimary", 
    "http://username.myopenid.com"), new RequestCallback() {
      @Override
      public void onResponseReceived(Request request, Response response) {
          // Do something
      }
  
      @Override
      public void onError(Request request, Throwable exception) {
          // Handle error
      }
  });
  

Procedure 2.7. Task

• To clear stored tokens, use the OAuthHandler as follows :

  AUTH_HANDLER.clearAllTokens();
  

Procedure 2.8. Task

• To invalidate a token grant, make a request to the invalidate endpoint as follows:

  AUTH_HANDLER.sendRequest(RequestUtil.invalidateTokenGrantRequest(RequestBuilder.GET, 
    "https://mydomain:443/MyAuthServer/rest/auth/invalidate", 
    "appClientId"), new RequestCallback() {
      @Override
      public void onResponseReceived(Request request, Response response) {
          // Do something
      }
  
      @Override
      public void onError(Request request, Throwable exception) {
          // Handle error
      }
  });
  

Procedure 2.9. Task

• To retreive access tokens, use the following code:

  String accessToken = AUTH_HANDLER.getLastTokenResult();
  String accessTokenForSpecificRequest = 
    AUTH_HANDLER.getTokenForRequest(myStoredAuthRequest);
  

Procedure 2.10. Task

• To encode a URL, use the following code:

  AUTH_HANDLER.encodeUrl("http://myurl");
  

Procedure 2.11. Task

1. Navigate to the Belay GitHub page and clone the repository.

2. Navigating to your local installation of a JBoss Application Server 7.X. Make sure your instance has SSL enabled.

   Add a username and password to the ApplicationRealm with the role guest, for use by the OpenID Provider.

   Add usernames and passwords for the authserver and resourceserver in the ApplicationRealm, with the role clientapp. Make sure these credentials are reflected in the resoureserver.properties files in the AuthServer and SecuredRestApp projects.

   Check that your JBoss instance has the jar file httpclient-4.1.1.jar in /modules/org/apache/httpcomponents/main, and that it is listed in the module.xml. Bugs may arise if this file is not present.

   Start your local instance of JBoss Application Server 7.X.

3. In a terminal, enter the command mvn clean install -DskipTests to build the projects. To deploy the various war files to your JBoss instance, use the command mvn package jboss-as:deploy. You will need to deploy the OpenIdProvider, OAuth2AuthServer, OAuth2SecuredRestApp and OAuth2GwtClientApp projects for all aspects of the GWT Client Application demonstration to function.

4. In a browser, navigate to https://localhost:8443/OAuth2GwtClientApp to try the demo application (replace 8443 with the port number your JBoss instance is using for SSL if necessary).

5. If you wish to run the GwtClientApp functional tests, edit the functionaltest.properties file in OAuth2GwtClientApp/src/test/resources/functional and add the usernames and passwords of your external OpenID accounts for Google, Yahoo, Fedora etc. Alternatively, you can add these details as arguments when you run mvn using the parameter values in the functionaltest.properties file: ie: mvn clean install -Dgoogle.user=myid@gmail.com -Dgoogle.pass=password.

Procedure 3.1. Task

1. Obtain the Resource Server Provider library jar file and add it to the classpath of your project. If you are using Maven, you can achieve this by adding the OSS repository and Resource Server Provider dependency to your pom.xml as follows in the example below. If you are using any other build tool, download the appropriate jar file from the Maven repository and add it as a library.

   <project>
       ...
       <repositories>
           <repository>
               <id>oss-repo</id>
               <name>OSS repository</name>
               <url>https://oss.sonatype.org/content/groups/public/</url>
           </repository>
       </repositories>
       ...
       <dependencies>
           <dependency>
               <groupId>org.jboss.pressgang.belay</groupId>
               <artifactId>resource-server-provider</artifactId>
               <version>${belay.version}</version>
           </dependency>
       </dependencies>
       ...
   </project>
   

2. In {project.basedir}/src/main/webapp/WEB-INF, create a datasource XML file for the resource server database, such as oauth2resourceserver-ds.xml. Take note of the JNDI name as it must be included under jta-data-source in your persistence.xml. Adding to your persistence.xml will be continued in later steps. Here is an example datasource configuration file for an in-memory database:

   <?xml version="1.0" encoding="UTF-8"?>
   <datasources xmlns="http://www.jboss.org/ironjacamar/schema" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://www.jboss.org/ironjacamar/schema 
     http://docs.jboss.org/ironjacamar/schema/datasources_1_0.xsd">
       <datasource jndi-name="java:jboss/datasources/OAuth2ResourceServerDS" 
         pool-name="oauth2resourceserver" enabled="true"use-java-context="true">
           <connection-url>
               jdbc:h2:mem:oauth2resourceserver;DB_CLOSE_ON_EXIT=FALSE
           </connection-url>
           <driver>h2</driver>
           <security>
               <user-name>sa</user-name>
               <password>sa</password>
           </security>
       </datasource>
   </datasources>
   

3. While you are working in the directory {project.basedir}/src/main/webapp/WEB-INF, create a file there called beans.xml. Its content should be as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <beans xmlns="http://java.sun.com/xml/ns/javaee" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="va.sun.com/xml/ns/javaee 
     http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
   </beans>
   

4. Create a persistence.xml file under ${project.basedir}/src/main/resources/META-INF, or open your existing one. Add a persistence unit for the data source you defined in step 2, making sure the JTA data source specified matches the JNDI name in your data source XML and that the Resource Server Provider model classes to be used (OAuth2RSScope and OAuth2RSEndpoint) are listed. Here is an example persistence.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <persistence version="2.0" 
     xmlns="http://java.sun.com/xml/ns/persistence" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="</br>  http://java.sun.com/xml/ns/persistence 
     http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
   	<persistence-unit name="oauth2-resourceserver">
       	<jta-data-source>java:jboss/datasources/OAuth2ResourceServerDS</jta-data-source>
           <jar-file>resource-server-provider-1.0-SNAPSHOT.jar</jar-file>
           <class>
               org.jboss.pressgang.belay.oauth2.resourceserver.data.model.OAuth2RSScope
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.resourceserver.data.model.OAuth2RSEndpoint
           </class>
           <!-- Demo database settings only. Not suitable for production environment -->
           <properties>
               <property name="jboss.entity.manager.factory.jndi.name"
                 value="java:app/OAuth2ResourceServerManagerFactory" />
               <property name="hibernate.hbm2ddl.auto" value="create-drop" />
               <property name="hibernate.hbm2ddl.import_files"
                 value="resourceserver-import.sql" />
               <property name="hibernate.show_sql" value="false" />
           </properties>
       </persistence-unit>
   </persistence>
   

5. In the same directory, ${project.basedir}/src/main/resources/META-INF, create a file called resourceserver.properties. This file must be present with all properties set -- other than tokenExpiryExtensionThreshold, which is optional -- in order for the Resource Server Provider library to function. Here is an example resourceserver.properties file with comments explaining each property:

   authServerUsername=resourceserver #Basic auth username for the Resource Server, as set on the Auth Server. This is used when the library needs to request information about an OAuth token
   
   authServerPassword=password #Basic auth password for the Resource Server, as set on the Auth Server
   
   authServerInfoUrl=https://localhost:8443/OAuth2AuthServer/rest/auth/info #The endpoint the Resource Server Provider should query for OAuth2 token information
   
   entityManagerFactoryJndiAddress=java:app/OAuth2ResourceServerManagerFactory #The JNDI address of the Resource Server manager factory, as specified in your persistence.xml (see step 4)
   
   tokenExpiryExtensionThreshold=300 # If a token used by a public client (which can't access refresh tokens) is within this many seconds of expiring when a request is made, the expiry time will be extended. Defaults to 900 (15 minutes)
   

6. The Resource Server Provider library needs to know what endpoints the Resource Server provides, and which scopes grant access to a particular endpoint. Endpoints are defined by their URL pattern, which can be a Java regular expression (see http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html), and their HTTP method. If the endpoint URL should be treated as regex, the URL_REGEX boolean should be set to true. If the HTTP Method is null for a given URL pattern it will match all methods. The scope names used must match those used by the Auth Server, as it is the Auth Server that grants client access to particular scopes on behalf of end-users. If a token has any of the scopes mapped to an endpoint, requests made with that token will be granted access to the endpoint. The endpoints, scopes and mappings between them is information that needs to be imported into the database. Here is a sample resourceserver-import.sql file, placed in ${project.basedir}/src/main/resources to import data to a data source when the application is deployed. Using this sample data, only GET requests are allowed under the DEFAULT scope.

   
   insert into RS_SCOPE (SCOPE_ID, SCOPE_NAME) values (-1, 'DEFAULT')
   
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-1, 'https://localhost:8443/OAuth2SecuredRestApp/rest/people', 'GET', false)
   
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-2, 'https://localhost:8443/OAuth2SecuredRestApp/rest/people/[0-9]+', 'GET', 
     true)
   
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-3, 'https://localhost:8443/OAuth2SecuredRestApp/rest/people', 'POST', false)
   
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-4, 'https://localhost:8443/OAuth2SecuredRestApp/rest/people', 'PUT', false)
   
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-5, 'https://localhost:8443/OAuth2SecuredRestApp/rest/people/[0-9]+', 
     'DELETE', true)
   
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-1, -1)
   
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-1, -2)
   

7. The last major part of configuring a Resource Server using the Resource Server Provider library is to add a filter for the protected resources. This is done in the web.xml file. Create a file called web.xml under ${project.basedir}/src/main/webapp/WEB-INF, or open your existing file. You need to add a filter using the org.jboss.pressgang.belay.oauth2.resourceserver.filter.OAuth2RSFilter class and a mapping indicating which URLs should be protected by this filter. You also need to define a context parameter to tell the library which class to use to make the access decisions. Here is an example web.xml that secures all endpoints under and including /rest/people:

   <web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
     http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
       <display-name>PressGang Belay OAuth2-secured App Example</display-name>
       <filter>
           <filter-name>OAuth2 Filter</filter-name>
           <filter-class>
               org.jboss.pressgang.belay.oauth2.resourceserver.filter.OAuth2RSFilter
           </filter-class>
       </filter>
       <filter-mapping>
           <filter-name>OAuth2 Filter</filter-name>
           <url-pattern>/rest/people/*</url-pattern>
       </filter-mapping>
       <context-param>
           <param-name>oauth.rs.provider-class</param-name>
           <param-value>
               org.jboss.pressgang.belay.oauth2.resourceserver.filter.OAuth2RSProvider
           </param-value>
       </context-param>
   </web-app>
   

Procedure 4.1. Task

1. Obtain the Auth Server Provider library jar file and add it to the classpath of your project. If you are using Maven, you can achieve this by adding the OSS repository and Auth Server Provider dependency to your pom.xml as follows in the example below. If you are using any other build tool, download the appropriate jar file from the Maven repository and add it as a library.

   <project>
       ...
       <repositories>
           <repository>
               <id>oss-repo</id>
               <name>OSS repository</name>
               <url>https://oss.sonatype.org/content/groups/public/</url>
           </repository>
       </repositories>
       ...
       <dependencies>
           <dependency>
               <groupId>org.jboss.pressgang.belay</groupId>
               <artifactId>auth-server-provider</artifactId>
               <version>${belay.version}</version>
           </dependency>
       </dependencies>
       ...
   </project>
   

2. Create a package under {project.basedir}/src/main/java in which to keep your web service code. Alternatively, you can define your endpoint paths in your web.xml. This documentation does not discuss this approach. To use the Java EE 6 no-XML approach to activating JAX-RS, in this package, create a class called JaxRsActivator that looks like the following, using your desired web service endpoint base in the @ApplicationPath annotation:

   import javax.ws.rs.ApplicationPath;
   import javax.ws.rs.core.Application;
   
   @ApplicationPath("/rest")
   public class JaxRsActivator extends Application {
      /* class body intentionally left blank */
   }
   

3. The Auth Server Provider library uses the Belay Resource Server Provider library. As such, there are properties files for both libraries for custom configuration. Create a file called resourceserver.properties in the directory ${project.basedir}/src/main/resources/META-INF/. This file must be present with the first four properties set if you wish to use the Auth Server endpoint implementations provided by the Auth Server Provider library; the token expiry threshold property is optional. Here is an example resourceserver.properties file with comments explaining each property:

   authServerUsername=authserver #Basic auth username for the Auth Server, as set on your server. This is used when the Resource Server Provider library needs to request information about an OAuth token used to access an OAuth2-protected Auth Server endpoint, such as /rest/auth/identity/query
   
   authServerPassword=password #Basic auth password for the Auth Server, as set on your server
   
   authServerInfoUrl=https://localhost:8443/OAuth2AuthServer/rest/auth/info #The endpoint the Resource Server Provider should query for OAuth2 token information
   
   entityManagerFactoryJndiAddress=java:app/OAuth2AuthServerManagerFactory #The JNDI address of the Auth Server manager factory, as specified in your persistence.xml (see step 8)
   
   tokenExpiryExtensionThreshold=300 #If a token used by a public client (which can't access refresh tokens) is within this many seconds of expiring when a request is made, the expiry time will be extended. Defaults to 900 (15 minutes)
   

4. In {project.basedir}/src/main/resource/META-INF you should also create a persistence.xml file. The important things to include are:

   • A reference to the Resource Server Provider jar file, as you will be using its model classes, and a listing of those classes

   • A reference to the Auth Server Provider jar file, as you will be using its model classes, and a listing of those classes

   • The property jboss.entity.manager.factory.jndi.name, which should be set to the same JNDI address you set in your resourceserver.properties file for the entityManagerFactoryJndiAddress property. This allows the Resource Server Provider to create an appropriate Entity Manager. The persistence unit name must be oauth2-authserver.

   Here is an example persistence.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <persistence version="2.0"
     xmlns="http://java.sun.com/xml/ns/persistence"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="
     http://java.sun.com/xml/ns/persistence
     http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
       <persistence-unit name="oauth2-authserver">
       	<jta-data-source>java:jboss/datasources/OAuth2AuthServerDS</jta-data-source>
           <jar-file>resource-server-provider-1.0.jar</jar-file>
           <jar-file>auth-server-provider-1.0.jar</jar-file>
           <class>
               org.jboss.pressgang.belay.oauth2.resourceserver.data.model.OAuth2RSScope
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.resourceserver.data.model.OAuth2RSEndpoint
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.ClientApplication
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.ClientApproval
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.Identity
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.OpenIdProvider
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.Scope
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.TokenGrant
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.CodeGrant
           </class>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.data.model.User
           </class>
           <!-- Demo database settings only. Not suitable for production environment -->
           <properties>
               <property name="jboss.entity.manager.factory.jndi.name"
                 value="java:app/OAuth2AuthServerManagerFactory" />
               <property name="hibernate.hbm2ddl.auto" value="create-drop" />
               <property name="hibernate.show_sql" value="false" />
           </properties>
       </persistence-unit>
   </persistence>
   

5. If you are simply testing the system with an in-memory database, you will want to create an import.sql file in ${project.basedir}/src/main/resources to put some data in your database when the Auth Server starts. Whether you are using an in-memory database or a file database, you will need to make sure your database contains the same sort of information as included in the following sample import.sql. The data to import includes:

   • The Clients authorized to use the Auth Server, including their unique identifier, name and the redirect URI they use.

   • The OpenID providers available for end-user authentication, including their name and URL, either in full or just the domain if appropriate. OpenID providers that include a user ID as part their domains (ie: MyOpenID) should be recorded with the static part of the domain only.

   • The scopes that the Auth Server can assign to end-user identities, which must have unique names. There must be a default scope (as defined in the authserver.properties file) as this is the scope all end-users are allocated when they are first created.

   • The scopes that the Resource Server Provider uses when it is protecting Auth Server endpoints, such as the user management endpoints. These names should match the scope names used in the SCOPE table as it is the Auth Server that assigns these to end-users.

   • The Auth Server endpoints that the Resource Server Provider is being used to protect. Each endpoint must have a URL, which can be in the form of a Java regular expression, an HTTP method, and a boolean value specifying whether the URL should be treated as a regular expression or not.

   • The mapping between Resource Server scopes and Resource Server endpoints, ie: which scopes a user must have to access an endpoint.

   Here is a sample import.sql file. Note that this data allows clients to perform user management by default; you may wish to put these endpoints under a separate scope:

   insert into CLIENT (CLIENT_ID, CLIENT_IDENTIFIER, CLIENT_NAME, CLIENT_REDIRECT_URI, 
     GRANTS_MUST_EXPIRE) values (-1, 'pressgang_belay_id', 'GwtOAuth2Client', true, 
     'https://localhost:8443/OAuth2GwtClientApp/org.jboss.pressgang.belay.oauth2.gwt
     .sample.App/oAuthWindow.html')
   
   insert into OPENID_PROVIDER (PROVIDER_ID, PROVIDER_NAME, PROVIDER_URL) values (-1, 
     'Google', 'gmail.com')
   insert into OPENID_PROVIDER (PROVIDER_ID, PROVIDER_NAME, PROVIDER_URL) values (-2, 
     'BelayOpenID', 'https://localhost:8443/OpenIdProvider')
   insert into OPENID_PROVIDER (PROVIDER_ID, PROVIDER_NAME, PROVIDER_URL) values (-3, 
     'Yahoo', 'me.yahoo.com')
   insert into OPENID_PROVIDER (PROVIDER_ID, PROVIDER_NAME, PROVIDER_URL) values (-4, 
     'Facebook', 'facebook.com')
   insert into OPENID_PROVIDER (PROVIDER_ID, PROVIDER_NAME, PROVIDER_URL) values (-5, 
     'myOpenID', 'myopenid.com')
   insert into OPENID_PROVIDER (PROVIDER_ID, PROVIDER_NAME, PROVIDER_URL) values (-6, 
     'Fedora Account System','admin.fedoraproject.org')
   
   insert into SCOPE (SCOPE_ID, SCOPE_NAME) values (-1, 'DEFAULT')
   
   insert into RS_SCOPE (SCOPE_ID, SCOPE_NAME) values (-1, 'DEFAULT')
   
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX) 
     values (-1, 'https://localhost:8443/OAuth2AuthServer/rest/auth/user/associate',
     'POST', false)
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-2, 'https://localhost:8443/OAuth2AuthServer/rest/auth/user/makeIdentityPrimary',
     'GET', false)
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-3, 'https://localhost:8443/OAuth2AuthServer/rest/auth/user/queryIdentity',
     'GET, false')
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-4, 'https://localhost:8443/OAuth2AuthServer/rest/auth/user/queryUser',
     'GET', false)
   insert into RS_ENDPOINT (ENDPOINT_ID, ENDPOINT_URL, ENDPOINT_METHOD, URL_REGEX)
     values (-5, 'https://localhost:8443/OAuth2AuthServer/rest/auth/invalidate',
     'GET', false)
   
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-2, -1)
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-2, -2)
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-2, -3)
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-2, -4)
   insert into RS_SCOPE_RS_ENDPOINT (SCOPE_ID, ENDPOINT_ID) values (-1, -5)
   

6. Create or navigate to the directory {project.basedir}/src/main/webapp/WEB-INF. In this directory, create a file called beans.xml. Its content should be as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <beans xmlns="http://java.sun.com/xml/ns/javaee" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="
     http://java.sun.com/xml/ns/javaee 
     http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
   </beans>
   

7. In {project.basedir}/src/main/webapp/WEB-INF, create a datasource xml file for your database, such as oauth2authserver-ds.xml. Its JNDI name must match the jta-data-source included in your persistence.xml. Here is an example datasource configuration file for an in-memory database:

   <?xml version="1.0" encoding="UTF-8"?>
   <datasources xmlns="http://www.jboss.org/ironjacamar/schema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.jboss.org/ironjacamar/schema 
     http://docs.jboss.org/ironjacamar/schema/datasources_1_0.xsd">
       <datasource jndi-name="java:jboss/datasources/OAuth2AuthServerDS"
         pool-name="oauth2authserver" enabled="true"
         use-java-context="true">
           <connection-url>
               jdbc:h2:mem:oauth2authserver;DB_CLOSE_ON_EXIT=FALSE
           </connection-url>
           <driver>h2</driver>
           <security>
               <user-name>sa</user-name>
               <password>sa</password>
           </security>
       </datasource>
   </datasources>
   

8. In {project.basedir}/src/main/webapp/WEB-INF, create a web.xml file. There are several aspects of the Auth Server set-up to configure here. These are:

   • GuiceOverrideServletContextListener: The OpenID Filter library that the Auth Server uses is by default configured to use a Host Meta Fetcher that sends requests to Google as part of the OpenID provider discovery process. This may be undesirable if you are using a custom OpenID provider with an internal URL you don't wish to share, or for performance reasons. The GuiceOverrideServletContextListener overrides this behaviour and uses a default Host Meta Fetcher implementation that does not send requests to Google by default.

   • OpenID Filter: The OpenID filter must be configured for the OAuth2 auth endpoint that utilizes OpenID for end-user authentication.

   • OAuth Filter: The OAuth filter must be configured for the endpoints that have resources protected by OAuth2, such as the user management and token grant invalidation endpoints.

   • OAuth2 Context Parameters: Context params must be set to configure the OAuth2 libraries, which need to know which class to use as a resource server provider, what types of token transmission to accept (ie: query, header) and which endpoints to use for token requests and authorization requests.

   • Security Constraints: Basic security (or an alternative) needs to be set up for protected resource endpoints, such as the token endpoint for confidential clients.

   Here is a sample web.xml with all of these configured:

   <web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
     http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
   	<display-name>PressGang Belay OAuth2 Auth Server</display-name> 
   
   	<!-- Used to override Guice binding in the openid-filter library -->
   	<listener>
           <listener-class>
               org.jboss.pressgang.belay.oauth2.authserver.openid
                 .GuiceOverrideServletContextListener
           </listener-class>
       <listener>
   
   	<!-- The OpenID Filter handles identity authentication -->
       <filter>
           <filter-name>OpenID Filter</filter-name>
           <filter-class>com.google.code.openid.RelyingPartyFilter</filter-class>
       </filter>
   
   	<!-- This defines the URL that requires OpenID authentication -->
       <filter-mapping>
           <filter-name>OpenID Filter</filter-name>
           <url-pattern>/rest/auth/authorize</url-pattern>
       </filter-mapping>
   
       <filter>
           <filter-name>OAuth Filter</filter-name>
           <filter-class>
               oss.pressgang.belay.oauth2.resourceserver.filter.OAuth2RSFilter
           </filter-class>
       </filter>
   
       <filter-mapping>
           <filter-name>OAuth Filter</filter-name>
           <url-pattern>/rest/auth/user/*</url-pattern>
           <url-pattern>/rest/auth/invalidate</url-pattern>
       </filter-mapping>
   
       <context-param>
           <param-name>oauth.rs.provider-class</param-name>
           <param-value>
               org.jboss.pressgang.belay.oauth2.resourceserver.filter.OAuth2RSProvider
           </param-value>
       </context-param>
   
       <context-param>
           <param-name>oauth.provider.tokens.request</param-name>
           <param-value>/rest/auth/token</param-value>
       </context-param>
   
       <context-param>
           <param-name>oauth.provider.tokens.access</param-name>
           <param-value>/rest/auth/authorize</param-value>
       </context-param>
   
       <context-param>
           <param-name>oauth.rs.tokens</param-name>
           <param-value>HEADER</param-value>
       </context-param>
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>ClientResources</web-resource-name>
               <url-pattern>/rest/auth/token</url-pattern>
               <url-pattern>/rest/auth/info</url-pattern>
           </web-resource-collection>
   
           <auth-constraint>
               <role-name>clientapp</role-name>
           </auth-constraint>
   
           <user-data-constraint>
               <transport-guarantee>CONFIDENTIAL</transport-guarantee>
           </user-data-constraint>
       </security-constraint>
   
       <login-config>
           <auth-method>BASIC</auth-method>
           <realm-name>ApplicationRealm</realm-name>
       </login-config>
   
       <security-role>
           <role-name>clientapp</role-name>
       </security-role>
   
   </web-app>
   

Procedure 4.2. Task

1. Create a class extending your desired library implementation of the endpoint, for example, GrantEndpointImpl.

2. Add the @Path and any relevant request annotations. For example:

   import org.jboss.pressgang.belay.oauth2.authserver.rest.impl.GrantEndpointImpl;
   
   import javax.enterprise.context.RequestScoped;
   import javax.ws.rs.Path:
    
   @RequestScoped
   @Path("/auth/invalidate")
   public class GrantWebService extends GrantEndpointImpl {
       /* class body intentionally left blank */
   }

Procedure 4.3. Task

• Use the following code as a template for your implementation:

  import org.apache.amber.oauth2.common.exception.OAuthProblemException;
  import org.apache.amber.oauth2.common.exception.OAuthSystemException;
  import org.jboss.pressgang.belay.oauth2.authserver.rest.impl.UserManagementEndpointImpl;
  import org.jboss.pressgang.belay.oauth2.shared.data.model.IdentityInfo;
  import org.jboss.pressgang.belay.oauth2.shared.data.model.UserInfo;
   
  import javax.enterprise.context.RequestScoped;
  import javax.servlet.http.HttpServletRequest;
  import javax.ws.rs.GET;
  import javax.ws.rs.Path;
  import javax.ws.rs.Produces;
  import javax.ws.rs.QueryParam;
  import javax.ws.rs.core.Context;
  import javax.ws.rs.core.MediaType;
  import javax.ws.rs.core.Response;
  import java.net.URISyntaxException;
   
  @RequestScoped
  @Path("/auth/user")
  public class UserManagementWebService extends UserManagementWebServiceImpl {
      @Override
      @GET
      @Produces(MediaType.APPLICATION_JSON)
      @Path("/myCustomQueryUserPath")
      public UserInfo getUserInfo(@Context HttpServletRequest request, String identifier) {
         	return super.getPrimaryUserInfo(request, identifier);
      }
  
      @Override
      @GET
      @Produces(MediaType.APPLICATION_JSON)
      @Path("/myCustomQueryIdentityPath")
      public IdentityInfo getIdentityInfo(@Context HttpServletRequest request, 
                                          @QueryParam("id") String identifier) {
          return super.getPrimaryIdentityInfo(request, identifier);
      }
  
      @Override
      @GET
      @Path("/myCustomMakeIdentityPrimaryPath")
      public Response makeIdentityPrimary(@Context HttpServletRequest request, 
                                          @QueryParam("id") String identifier) {
          return super.makeIdentityPrimary(request, identifier);
      }
  }

  Note

  If you wish to write your own implementations for some or all of the OAuth2 endpoints defined by the Auth Server Provider, you can implement the interfaces supplied (ie: TokenEndpoint, UserManagementEndpoint). You can then configure your Auth Server implementation to use your authorization and token endpoints in your web.xml. You should also inform your resource servers and OAuth2 clients where these endpoints are located.

Procedure 4.4. Task

• Here is an example authserver.properties files showing the default values with comments explaining each property available:

  oAuthTokenExpiry=3600 #The expiry time of an OAuth2 access token in seconds, set when the token is created. This is also the time used to extend public client access tokens by when their expiry time is pushed out
  
  oAuthCodeExpiry=60 #The expiry time of an OAuth2 authorization code in seconds, set when the code is created
  
  urlEncoding=UTF-8 #The encoding type specified when encoding or decoding URLs
  
  openIdRealm=/OAuth2AuthServer/rest/auth/ #The OpenID realm of the Auth Server
  
  restEndpointBasePath=/OAuth2AuthServer/rest #The base path for the Auth Server's RESTful endpoints, as defined by the application name and JAX-RS base path
  
  authEndpoint=/auth/authorize #The path to the OAuth2 authorization endpoint, relative to the project's JAX-RS base path
  
  openIdReturnUri=/OAuth2AuthServer/rest/auth/authorize #The endpoint to use as the OpenID return URI, which should match the grantEndpoint property but be expressed relative to the server's domain
  
  defaultScopeName=DEFAULT #The name of the scope that all users should have upon creation and all token grants are given, capitalized by convention. This must have a matching definition in the database
  
  promptEndUserToApproveClientAppOnEveryLogin=false #Boolean true/false. True if you want the end-user to be prompted to approve client access of their auth info and resources on every login
  
  endUserConsentUri=/auth/consent #The URI to redirect end-users to give consent for client access to their auth info and resources, relative to the project's JAX-RS base path
  
  endUserConsentFormCssLocation= #The URL where a style sheet for the end-user consent page can be found; optional
  

Procedure 4.5. Task

1. If you wish to override this service, you can create your own implementation of the org.jboss.pressgang.belay.oauth2.authserver.service.TokenIssuer interface decorated with the javax.enterprise.inject.Alternative annotation using the following example code:

   import org.apache.amber.oauth2.common.exception.OAuthSystemException;
   import org.jboss.pressgang.belay.oauth2.authserver.service.TokenIssuer;
   import javax.ejb.Stateless;
   import javax.enterprise.inject.Alternative;
   
   @Alternative
   @Stateless
   public class AlternativeTokenIssuer implements TokenIssuer {
   
       @Override
       public String accessToken() throws OAuthSystemException {
           return "foo";
       }
   
       @Override
       public String refreshToken() throws OAuthSystemException {
           return "bar";
       }
   
       @Override
       public String authorizationCode() throws OAuthSystemException {
           return "foobar";
       }
   }
   

2. Enable your implementation and override the default by adding your class to the Auth Server's beans.xml:

   <beans>
       ...
       <alternatives>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.sample
                 .service.AlternativeTokenIssuer
           </class>
       </alternatives>
   </beans>
   

Procedure 4.6. Task

1. If you wish to override the DefaultAuthService implementation, create your own implementation of the org.jboss.pressgang.belay.oauth2.authserver.service.AuthService interface decorated with the javax.enterprise.inject.Alternative annotation.

2. Enable your implementation and override the default by adding your class to the Auth Server's beans.xml:

   <beans>
       ...
       <alternatives>
           <class>
               org.jboss.pressgang.belay.oauth2.authserver.sample
                 .service.AlternativeAuthService
           </class>
       </alternatives>
   </beans>